Context Mentions: Files, Folders, Terminals, and Git

One of the features that separates Cursor from a plain code editor with a chatbot bolted on is its context system. Instead of copying code into a chat window and hoping the AI understands, you can point straight at things using the @ symbol: files, folders, terminal output, past chats, your current git changes, and more. The agent reads exactly what you referenced before it answers.

Cursor's agent can also find context on its own. It searches your codebase, and it can search the web and fetch documentation pages when it needs them. So @-mentions are not the only way context gets in. They are how you say "look here first" when you already know what matters.

This lesson covers each mention type, when to use it, and how the right context turns vague answers into precise ones.

What You'll Learn

• How the @-mention system works in the Agent side panel
• Referencing specific files and whole folders
• Sharing terminal output with @Terminals
• Reusing earlier conversations with @Chats
• Including git changes with @Commit and @Branch
• Using @Browser for front-end work
• Pulling in manual rules by mentioning them
• When to let the agent search the codebase and the web on its own
• Understanding context window limits

How the @-Mention System Works

When you type @ in the chat input of the Agent side panel (open it with Cmd+I or Cmd+L on macOS, Ctrl+I or Ctrl+L on Windows/Linux), a menu appears listing what you can reference. Keep typing to filter it. Cursor's fuzzy search makes it fast to find the right file, even in a large project.

When you send the message, the referenced content is attached to your request. The model sees the real text of the file, the terminal output, or the diff, not just a name.

Here are the main mention types:

@auth.ts          → a specific file
@src/components/  → a folder
@Terminals        → output from your open terminals
@Chats            → an earlier conversation
@Commit           → the diff of your current, uncommitted work
@Branch           → the diff between your branch and main
@Browser          → the built-in browser, for front-end work
@my-rule          → a manual project rule

The exact list can change between Cursor versions, so check the @ menu in your own editor and the Cursor docs.

You can also select code in the editor and press Cmd+Shift+L (Ctrl+Shift+L) to add that selection to the chat. This is handy when only a few lines matter.

Referencing Files

File mentions are the most common kind. They tell the agent to read a specific file before answering.

When to Mention Files

Mention files when:

• You want the agent to understand or change a specific source file
• You are asking about a bug in a particular component
• You want new code to match an existing file's patterns

Practical Examples

@auth.ts How does this handle token refresh? Is there a risk of
race conditions when multiple requests fire at once?

@UserProfile.tsx Refactor this component to use the useUser hook
instead of reading from localStorage directly.

@schema.sql I want to add a `last_login_at` column to the users
table. Write the ALTER TABLE migration.

The agent sees the actual imports, types, logic, and exports, not just a filename. That makes a big difference compared to describing the file in words.

Referencing Multiple Files

You can mention several files in one message:

@api/orders.ts @components/OrderForm.tsx The form submits but the
API returns a 400 error. What is the mismatch between what the
form sends and what the API expects?

With both files, the agent can compare the exact shape of the form data with the exact validation the API applies.

Referencing Folders

Type a path ending in a folder, like @components/forms/, to point the agent at a whole directory. This helps when your question spans several related files.

When to Mention Folders

Mention a folder when:

• You want the agent to understand a module or feature area
• You are asking about conventions used across a set of files
• You want a new file that fits the patterns of an existing directory

Practical Examples

@components/forms/ What patterns do the existing form components
use for validation? I want a new PaymentForm that follows the
same conventions.

@api/routes/ Give me an overview of the API endpoints defined
here and what each one does.

Folders vs. Files

Mention a file when you know exactly which one matters. Mention a folder when the question spans several files and you are not sure which ones matter most. Large folders use more of the context window, so narrow down to specific files when you can.

@Terminals: Sharing Terminal Output

@Terminals attaches the output from your open terminals. This is the fastest way to show the agent a failing build, a stack trace, or a test run without copying and pasting.

@Terminals The test run just failed. What is causing the
TypeError in the checkout tests, and how do I fix it?

@Terminals @next.config.js The dev server crashes on startup.
Is this a config problem?

Keep in mind that in Agent mode, the agent can run terminal commands itself and read the output. @Terminals is most useful for output from commands you ran yourself.

@Chats: Reusing Earlier Conversations

@Chats lets you bring in an earlier conversation. This is useful when you start a fresh chat (to keep the context clean) but want to carry over decisions from a previous one.

@Chats (pick "Auth refactor plan") Continue from that plan.
Start with step 3, updating the session middleware.

Starting a new chat and mentioning the old one is often better than continuing a very long chat, because the agent gets the key points without all the noise.

@Commit and @Branch: Git Changes

Two mentions give the agent your git changes:

• @Commit attaches the diff of your current working state (changes you have not committed yet).
• @Branch attaches the diff between your current branch and main.

When to Use Them

• Reviewing your own work before you commit
• Writing an accurate commit message or PR description
• Debugging a regression that appeared after recent changes

Practical Examples

@Commit Review these changes. Are there any obvious bugs or
missing edge cases before I commit?

@Branch Summarize everything this branch changes in plain
English for the PR description.

@Branch The checkout tests pass on main but fail here. Which
change in this branch most likely broke them?

This narrows the search. Instead of asking the agent to audit the whole codebase, you point it at the exact changes that could have caused the problem.

@Browser: Front-End Work

@Browser connects the agent to Cursor's built-in browser, so it can look at a running page while you work on UI. Use it when the problem is visual or only shows up at runtime.

@Browser Open localhost:3000/pricing. The cards overlap on
narrow screens. Find the cause in the CSS and fix it.

Mentioning Manual Rules

Project rules live in .cursor/rules/. A rule set to Manual only applies when you mention it with @ by name. This is a clean way to keep special instructions (like a migration checklist or a release process) out of everyday chats and pull them in only when needed.

@db-migrations Add a migration that creates the invoices table.

You will learn more about rules later in the course.

Letting the Agent Find Context Itself

You do not have to tag everything. In Agent and Ask modes, the agent searches your codebase on its own to find relevant files. It can also search the web and fetch documentation pages when a question needs current information, such as a recent library release or a known bug in a dependency.

How do I configure rewrites in the Next.js App Router? Check the
official docs and show me an example for this project.

Prisma error: "Can't reach database server" in Docker. Search for
common causes and check our docker-compose setup.

A good rule of thumb:

• You know the relevant files → mention them with @
• You are not sure where to look → just ask, and let the agent search
• The answer depends on recent docs or releases → ask the agent to check the docs or search the web

How Context Affects Response Quality

Compare these two messages:

Without context:

Why is my form not submitting?

With context:

@OrderForm.tsx @api/orders/route.ts @Terminals
The form submission fails silently. No error in the console,
no network request. Why might this be happening?

In the first case, the agent has to search and guess. In the second, it can read the exact code and the exact output and often find the problem in one reply.

If you would need to paste something into the chat to explain what you mean, use a mention instead.

Tips for Choosing the Right Mention

• Question about one file → mention the file
• Conventions in a feature area → mention the folder
• A failing command you ran → @Terminals
• Carrying over an earlier discussion → @Chats
• Reviewing uncommitted work → @Commit
• Debugging a branch or writing a PR summary → @Branch
• A visual or runtime UI bug → @Browser
• A special-purpose instruction set → mention the manual rule
• No idea where to start → just ask; the agent will search

Understanding Context Window Limits

Every model has a context window: a maximum amount of text it can handle in one request. Windows are large, but you can still fill one with very big files, huge folders, or a very long chat.

Signs that you are near the limit:

• Answers that miss obvious information from a file you referenced
• The agent forgetting decisions made early in a long chat

To stay within limits:

• Mention specific files rather than whole folders when only a few matter
• Select just the relevant lines and add them with Cmd+Shift+L
• Start a new chat for a new task, and use @Chats to bring over what matters

Key Takeaways

• The @-mention system attaches precise context to your request, so you don't need to copy and paste code.
• Mention files for file-level questions and folders for questions about a feature area.
• @Terminals shares command output, @Chats brings in earlier conversations, and @Browser helps with front-end work.
• @Commit shows your uncommitted changes; @Branch shows the diff against main. Both are great for reviews, PR summaries, and regressions.
• Manual rules apply only when you mention them by name.
• The agent can search your codebase, search the web, and fetch docs on its own. Use @ when you already know what matters.
• Context windows are large but finite: be targeted, and start fresh chats for new tasks.