How-to · Cursor for Mac
How to add a doc for @Docs context in Cursor on Mac: cursor add docs mac
To add a doc for @Docs in Cursor on Mac, press ⌘⇧J to open Cursor Settings, go to Indexing and Docs, click Add Doc, and paste a public documentation URL. Wait until the entry shows Indexed with a timestamp, then type @Docs in a new chat and pick your doc from the list.
Quick answer
- Open Cursor Settings with ⌘⇧J, then go to Indexing and Docs and click Add Doc.
- Paste a public docs URL and wait for Indexed with a timestamp before you start a new chat.
- On Cursor 3.0 or later, switch to the Editor Window first. Staff say @Docs is not in the Agents Window.
- If @Docs does not list the doc, use + Add new doc in chat, click Resync, or delete, restart and re-add the entry.
What you need
- Cursor installed on macOS.
- A public URL for the docs site or the section you need.
- Patience while indexing runs. No forum report gives a fixed time.
- Labels vary by version. Reports name 2.6.18 and 3.7.21.
How to Add a custom doc for @Docs in Cursor in Cursor on a Mac
Switch to the Editor Window on Cursor 3.0
⌘⇧P
If Cursor opens the Agents Window, switch first. Press ⌘⇧P, type Open Editor Window, and press Return. Staff say the docs settings live in the Editor Window, not the Agents Window.
Tip: Skip this step on builds where you never saw the Agents Window.
Open Cursor Settings
⌘⇧J
Press ⌘⇧J. Cursor Settings opens in its own window. If the shortcut does nothing, open the Cursor menu in the menu bar and choose Settings.
Tip: Menu names can shift between builds. The shortcut is the more reliable route.
Go to Indexing and Docs
Find Indexing and Docs in the list of sections. Some guides write it as Indexing & Docs. Some 2025 threads describe a Features tab instead.
Tip: Look for the list that shows your docs and their status.
Click Add Doc
Click Add Doc. A field appears for the URL. Paste the address of the docs root or the section you need.
Tip: Forum reports describe public pages, so avoid URLs behind a login.
Paste the URL and confirm
Paste the URL and confirm. The new entry appears in the list while Cursor reads the pages. Do not close Cursor during this step.
Tip: Keep the window open until the entry appears in the list.
Wait for Indexed with a timestamp
Watch the status. The doc is ready when it shows Indexed and a timestamp. A Failed status, or a status that never changes, means the doc needs a fix. See the troubleshooting list.
Tip: Staff suggest waiting for indexing to finish before you open a new chat.
Open a new chat
Open the chat panel and start a new chat. A chat that was open before indexing finished may not show the new doc.
Tip: If you already have an old chat open, start a fresh one.
Type @Docs and choose your doc
Type @ in the chat box, then choose Docs. Find your doc in the list next to the built-in docs. Select it before you type your question.
Tip: Pick the doc first, so the question goes to the right source.
Add the doc from chat if it is missing
If your doc is missing, choose + Add new doc in the @Docs menu. Paste the same URL. The bug report says you repeat this in each chat.
Tip: Use this only when the entry does not show in the list.
Resync or re-add the entry
Back in Cursor Settings, open Indexing and Docs and click Resync. If the doc still does not show, delete the entry, restart Cursor, add the URL again, and wait for Indexed.
Tip: A restart starts indexing from scratch, so expect a wait.
Ask a question that names the doc
In the chat, type @Docs, select your doc, and ask something specific. Compare the answer with the page it came from. Keep that page open while you check.
Tip: Test with a question you already know the answer to first.
What @Docs does in Cursor on Mac
@Docs is how Cursor's chat reads documentation you give it. You add a library's docs once. After that, the chat can pull answers from those pages when you ask about that library. This helps most with fast-moving tools, where the model's memory of an API may be old. You still choose which pages the chat trusts, so the URL you paste matters.
What you need before you start
You need Cursor on your Mac and a public URL for the docs you want. Pick the URL with care. Use the docs root or the section you actually use, not one tutorial page. The forum reports describe public pages, so a page behind a login makes a poor first test. Open the URL in a browser first, so you know it loads.
Also note your version. Reports on this feature name Cursor 2.6.18 and 3.7.21, and menu labels change between releases. If your screen does not match these steps, look for the same idea under a similar name. The Cursor Settings window is the one that ⌘⇧J opens.
Check which window you are in on Cursor 3.0
Cursor 3.0 came out on April 2, 2026. It added an Agents Window, which you open with ⌘⇧P, then Agents Window. You can switch back to the IDE at any time, or keep both windows open. The docs settings work differently. A Cursor staff member wrote on June 9, 2026 that @Docs is not available in the Agent Window. To reach it, press ⌘⇧P and choose Open Editor Window, then find @Docs in Cursor Settings.
Add the doc and wait for Indexed
Open Cursor Settings and go to Indexing and Docs. Click Add Doc, paste the URL, and confirm. The entry appears in the list while Cursor reads the pages. Do not start a chat yet. Wait until the status reads Indexed and a timestamp shows beside it. Staff in the forum threads suggest this order, because a chat opened too early may miss the new doc.
A worked example: a charting library's config docs
Say you build a dashboard with a charting library. You want answers about its configuration options. Copy the URL of the configuration section, not the homepage. Open Cursor Settings, go to Indexing and Docs, click Add Doc, and paste it. Wait for Indexed. Then start a new chat, type @Docs, pick the library, and ask how to set an axis label. A good answer names the option from that page. If the answer guesses, the doc may not have loaded, so check the status again.
Choose a URL the chat can actually read
A good doc URL is one the chat can read in full. A homepage full of links gives the chat little text to use. A section page with reference text usually helps more. If a big page does not index, try a narrower page from the same site. Test with a question you already know the answer to. That tells you whether the chat reads the doc before you depend on it.
Confirm the status before you blame the chat
Three statuses matter. Indexed with a timestamp means the doc is ready. Failed means indexing did not work, and a 2025 forum thread reports this state with no confirmed fix. A status that stays the same for a long time suggests indexing has stalled. Check the status before you blame your question or the model.
A restart does not repair a stuck doc on its own. Staff say a restart starts indexing from scratch. Wait for Indexed to show again after any restart before you rely on the doc in chat.
46%
of developers do not trust the accuracy of AI tool output, in the 2025 survey, up from 31% the year before
Stack Overflow 2025 Developer Survey press release25.5%
of 3,127 respondents said they used Cursor as a coding agent or assistant in the past year
AI data 2026: Stack Overflow Developer SurveyUse @Docs in a new chat
Open the chat panel and start a new chat. Type @ in the chat box and choose Docs. You should see the built-in docs and your own doc in the list. Select your doc, then ask a question that names the library and the function. Specific questions give the doc a better chance to matter.
A Cursor 2.6.18 bug report describes a doc that shows Indexed in Settings but is missing from the @Docs dropdown. The dropdown showed only built-in docs and + Add new doc. The report covers macOS and Windows. If you see the same thing, the steps below cover the fixes users reported.
When your doc is missing from the @Docs list
Start with the workaround from the bug report. In chat, pick @Docs, then + Add new doc, and paste the same URL. The reporter says you must repeat this in each chat, so treat it as a patch. Next, return to Cursor Settings, open Indexing and Docs, and click Resync. If the doc still does not appear, delete the entry, restart Cursor, add the URL again, and wait for Indexed.
| Symptom | What to try |
|---|---|
| Doc shows Indexed in Settings but not in the @Docs list | Pick + Add new doc in chat and paste the same URL |
| Status shows Failed or stops changing | Click Resync, or delete, restart and re-add the entry |
| @Docs is missing after upgrading to Cursor 3.0 or later | Press ⌘⇧P, choose Open Editor Window, then find @Docs in Cursor Settings |
| Only one page of the docs site was indexed | Add the section URL as its own doc, or paste the relevant text into chat |
Mistakes people make with @Docs
- Asking a question before the status shows Indexed with a timestamp.
- Looking for @Docs in the Agents Window. Staff say it is not there.
- Adding a homepage when a section page would hold the reference text.
- Opening a chat that was already open before indexing finished.
- Deleting the doc before trying Resync, which is the first fix staff suggest.
- Trusting an answer without opening the page it came from.
How much to trust answers from a doc
A doc makes answers more specific. It does not make them correct. Stack Overflow's 2025 survey found that 46% of developers do not trust the accuracy of AI tool output, up from 31% the year before. Treat each answer as a draft. Open the page it cites, check the function or option name, and run the code before you ship it.
Shared URLs, refresh, and large sites
Cursor de-duplicates matching URLs. If another user already indexed the same address, you can get that result without starting over. Staff say docs refresh when another user adds the same URL. They also refresh periodically in the background, so your copy can change without any action from you.
Large sites need care. A 2025 forum user describes a prefix setting for narrowing a large doc. Other users report a docs site that indexed only one page. Check what the chat actually cites before you trust it. If answers look thin, add a narrower section URL as its own doc.
Where @Docs is headed
The latest three changelog entries, dated October 20 to November 6, 2026, do not mention docs, indexing, or Settings changes. That is not a promise either way. Staff call @Docs not an active development area, so the menus may move again. Check the Settings window in your own build before you follow an older guide.
What to do next
Once the doc shows Indexed, ask one real question from your project and note which doc answered it. Then set up the rest of your chat workflow. The Cursor setup guide for developers on Mac covers rules and shortcuts in more depth.
Cursor shortcuts for this on Mac
| To do this | Press |
|---|---|
| Open Cursor Settings | ⌘⇧J |
| Open the Command Palette | ⌘⇧P |
If it does not work
- Doc shows Indexed in Settings but not in the @Docs list
- In chat, use @Docs, then + Add new doc, and paste the same URL. The 2.6.18 bug report says this workaround repeats in each chat. Then try Resync in Indexing and Docs.
- Status stays Failed or stops changing
- Click Resync first. If it still fails, delete the entry, restart Cursor, and add the URL again. A 2025 thread reports the same states with no confirmed fix, so report it on the forum with your version.
- @Docs is missing after upgrading to Cursor 3.0 or later
- Staff say @Docs is not in the Agent Window. Press ⌘⇧P, choose Open Editor Window, then find @Docs in Cursor Settings.
- Only one page of the docs site got indexed
- A 2025 thread reports this. Add the section URL as its own doc. Or paste the relevant text into chat, which staff suggest when a doc does not work.
- A doc you removed or added comes back after a restart
- Reported in a 2025 thread. Check Indexing and Docs after each restart. Wait for Indexed again before you rely on the doc.
- Cannot find the Indexing and Docs section
- Labels differ by version. Try Indexing & Docs, or look for a Features tab in older builds. Compare with the version you run.
Faster with Lazur
Do it faster: ask Lazur while you are in Cursor
Hold ⌥ ⌘ and say what you want. Lazur sees your Cursor window. Lazur guides you one click at a time and waits for each click.
- 1
Hold ⌥⌘ and talk
- 2
Lazur guides you one click at a time and waits for each click.
- 3
You stay in Cursor. Nothing to copy into a chat window.
Free for 3 days, then $18/month. Download for Mac
You say“Walk me through adding a doc for @Docs”
Lazur · walks you through itLazur guides you one click at a time and waits for each click before the next step.
Questions people ask
Where is the Add Doc button in Cursor on Mac?
Press ⌘⇧J to open Cursor Settings, then go to Indexing and Docs. Click Add Doc there. On Cursor 3.0 or later, open the Editor Window first with ⌘⇧P and Open Editor Window, because staff say the docs settings live there.
Why does my doc say Indexed but not show up in @Docs?
A Cursor 2.6.18 bug report describes exactly this. In chat, use + Add new doc in the @Docs menu and paste the same URL. If that fails, click Resync, or delete, restart and re-add the entry. Start a new chat only after the status shows Indexed.
Can I add a private or login-protected doc?
The forum reports describe public URLs. A page behind a login may not index. Test with a public page first. If that works, try the private one and check whether the status reads Indexed before you rely on it.
Does @Docs work in the Agents Window?
No, according to a staff reply dated June 9, 2026. Switch to the Editor Window with ⌘⇧P and Open Editor Window, then look for @Docs in Cursor Settings.
Do I need to add the doc again in every chat?
The workaround in the 2.6.18 bug report says yes, using + Add new doc in each chat. Resync or a re-add in Settings may fix the list. The reports do not confirm which fix works for every setup.
How often do docs refresh?
Staff say docs refresh in the background on a schedule, and when another user adds the same URL. Matching URLs are de-duplicated, so a successful index from another user can become available to you.
What if I cannot find @Docs at all?
Staff suggest pasting the relevant section, or a link, into chat instead. That works for short text. It skips the index, so the chat only sees what you paste into the message.
Is the @Docs feature still supported?
A 2026 staff reply calls @Docs not an active development area and says there are no plans to move it to the Agent Window. A 2025 staff reply said the docs feature is still available. Check your version before you rely on it.
Sources
- Keyboard Shortcuts | Cursor Docs · Cursor · checked 2026-11-08
- New Cursor Interface · Cursor Changelog (Cursor 3.0) · Cursor · checked 2026-11-08
- Cursor Changelog · Cursor · checked 2026-11-08
- Indexing docs missing: Cursor Community Forum (incl. staff reply by Colin) · Cursor Community Forum · checked 2026-11-08
- Custom doc indexed in Settings but not listed in @Docs chat dropdown · Cursor Community Forum · checked 2026-11-08
- Custom Doc Indexing: Cursor Community Forum · Cursor Community Forum · checked 2026-11-08
- AI data 2026: Stack Overflow Developer Survey · Stack Overflow · checked 2026-11-08
- Stack Overflow 2025 Developer Survey press release · Stack Overflow · checked 2026-11-08
- Cursor docs home · Cursor · checked 2026-11-08
Try Lazur free for 3 days
Hold a key and ask. Lazur sees your screen, points at the button and talks you through it, in any Mac app. No credit card.