@ Mentions in Cursor: Attaching Context to a Chat

It attaches specific context to the conversation so Agent focuses on the right files and information. You hand over the material instead of leaving the agent to go and find it.

Cursor's agent searches your repository on its own, which is why a chat with no mentions in it can still land on the right file. What a mention changes is certainty. For the files you can name, the search step stops being a step, and for every other file the agent carries on exactly as before.

Everything you attach lands in the same context window as the rest of the conversation, so a mention costs something as well as buying something. A folder mention attaches the folder's contents, which makes @src/components/ a far heavier attachment than @auth.ts even though both take the same two seconds to type. Folder mentions are, I suspect, the most over-used of the lot for exactly that reason.

People read that the other way round fairly often, and then get surprised by an edit to a file they never mentioned.

Six kinds of context. Files and folders are the ones everyone uses, and four of the others reach material that does not live in a file you could open. Terminal output, an earlier conversation, a branch diff and the built-in browser all attach without being pasted into the prompt.

The two git rows are the ones I would learn first. @Commit (Diff of Working State) puts your uncommitted changes into the conversation and @Branch (Diff with Main) puts the full branch diff there. Either one asks the agent about the change rather than about the code the change happens to sit in, and for a review question that framing is usually the one you wanted.

Terminal output probably saves the most typing of the six. @Terminals includes it as context, so a stack trace never has to go through your clipboard. Copying one by hand out of a scrolling pane is how the top frame goes missing.

Folders have a navigation shortcut that is easy to miss. After selecting a folder, type / to go deeper instead of backing out and starting the mention over.

Past Chats is the row whose wording hides a detail. What crosses into the new chat is a compressed version of the old thread, and compaction sheds the tool calls it considers finished, so file reads and command output the agent already acted on do not come across with it. Which matters when the thing you needed from that conversation was a version number somebody read out of a lockfile. Put the number in the prompt yourself, and see what compaction drops for the rest of it.

Cursor's guidance is narrower than attaching everything. Use mentions when you already know which files are relevant. The example in the docs is updating a component and its tests: mention both files, because you know both have to change.

The other half of that guidance is the half that gets skipped. If you are not sure which files matter, Cursor says to skip the mention, because Agent finds relevant files through its own search.

What happens if you mention the wrong file?

Guessing is where this costs you. A mention is a claim that the file is relevant, and my read is that the agent takes the claim at face value. It starts there, and getting it off the wrong file burns a turn or two. Padding the list to cover the guess costs more again, because everything attached shares one window, and a Cursor field engineer's rule of thumb puts the first slip in quality at around 50 to 60% of a full window.

Does team size change when to mention?

Team size moves this more than seniority does. On a four-person team where everyone has touched every file, the guess is usually right and mentioning is close to free. The rule I used to hand new joiners on a large codebase was the same one (mention the files you are about to change), and that rule is wrong for their first fortnight, when their guess is unreliable and the search is not. Have them describe the task, let the agent find the files, then mention what it surfaced once the diff has shown it was the right file.

That is also why the docs example picks a component and its tests. The dependency between those two files is something you hold before you type anything, so the mention is carrying real information into the chat.

Check whether the path sits in an ignore file. .cursorignore works like .gitignore but governs what Cursor can reach, and Cursor lists context selection among the things it excludes, next to semantic search and agent file reading.

The reason this catches people is that the ignore file was usually written for something else. Somebody adds dist/ and a secrets path during onboarding, a generated API client turns out to sit under one of those globs, and months later a mention of that client comes back thin. Cursor is direct about what the mechanism is worth, calling .cursorignore a convenience feature rather than a security boundary, but as an explanation for a mention going quiet it is the cheapest thing to rule out. Codebase indexing has the fuller version.

The second thing I would check is how long the thread has been running. An attachment from forty messages back is sharing the window with every file the agent has opened since and with the output of everything it ran, which is a different problem from the mention never landing.

A fresh chat with the same mention in it takes ten seconds and tells you which of the two you are looking at.

Yes. Type @ as many times as you need and each one gets added to the conversation, whether it is a file, a folder or one of the other context types. Repeating the mention is the documented way to do it, and you do not have to finish one before starting the next.

What nobody counts is the total. Six files and a folder is a large attachment even when every one of them is relevant, and the folder is quietly the largest part of it. The context meter at the bottom of the chat is the number I would actually watch, since it shows what fraction of the window is in use.

If you find yourself attaching the same guidance in every chat, that is a rule rather than a mention. Cursor documents them at cursor.com/docs/rules, and one of the apply modes is a manual rule you pull in with @, which keeps guidance that only sometimes applies out of every other prompt.

How often it comes up decides whether that is worth setting up. Twice a week and retyping it is fine; every chat and it is probably worth the five minutes.