CursorContext managementLevel 3: Workflows

How Do You Use @ Mentions in Cursor?

Type @ in the chat input, start typing, and pick from the suggestions. You can attach files and folders, @Terminals, @Chats, @Browser, and Git diffs such as @Commit (Diff of Working State) and @Branch (Diff with Main). Use mentions when you know what's relevant. If you don't, skip them and let Agent search.

Prompt to copy
Update @[target file] to [change]. Follow the style in @[reference file], and update @[test file].

Don't edit anything else. If you find that another file has to change, name it and ask me first.

For review:
Review the changes on @Branch for bugs and missing error handling. Don't edit anything.
You know the filesuse @
  • @auth.ts
  • @auth.test.ts
  • Direct and exact
You don't knowskip it
  • Describe the behavior
  • Agent searches
  • Faster than guessing
Cursor's own guidance: mention when you know what's relevant, and otherwise let Agent search.

Try it now

  1. 1Open Agent with Cmd+I (Ctrl+I), type @, and start typing a filename. Pick it from the suggestions.
  2. 2Type @ again and choose a folder, then type / to navigate deeper into it.
  3. 3Run a failing command in the terminal and attach it with @Terminals. It worked if Agent quotes your real output instead of asking you for it.

Use it when

When a change touches known files, such as a component and its test. Also use @Branch to review your work, @Terminals for command output, and @Chats to continue a previous conversation.

Skip it when

When you're exploring and don't know where the code is. Guessing at files can steer Agent wrong. Cursor's help says that if you're not sure which files matter, skip it, and Agent will find them through its own search.

Why it works

A mention saves Agent a search and removes the chance of it picking the wrong file, such as one of three config.ts files. It's also the simplest way to bring in things search won't find, such as your terminal output or your uncommitted diff. Cursor's course says the latest models are good at finding context themselves, so naming a file isn't always needed. It's most useful when the target is known or ambiguous. Each mention also adds to the context, so naming a whole folder isn't free.

Example

Say you need to expire sessions after 30 days. You write: "Update @src/auth/session.ts to expire sessions after 30 days. Match the style in @src/auth/token.ts and update @src/auth/session.test.ts. Don't touch anything else." The agent has its target, its model and its check. Without the mention, it might also find a second session.ts in an old admin folder.

Going further

Old guides list @Codebase, @Docs and @Web, but Cursor's current @ lists don't include them. Agent searches the code and the web with its own tools, so ask in plain words: "search the web for the current API". Copying also has a choice: paste with Cmd+V to add copied code as a reference, or Cmd+Shift+V to add it as plain text. In a rule, a mention like @template.ts isn't inlined, because Agent reads it only when needed. Side chats can be mentioned too, to pull in what they found.

Common mistakes

  • Mentioning a whole folder "to be safe" when two files would do.
  • Leaving out the test file, so behavior changes without its check.
  • Mentioning files you only suspect are relevant, which anchors the agent on your guess.
  • Typing @Codebase from an old tutorial and finding nothing. Just ask the question.

Sources

Checked 6 November 2026. Products change often, so confirm details with the vendor.

Related

Beyond the course