Context Mentions: @files, @folders, and @code

One of the features that separates Cursor from a plain code editor with an AI chatbot bolted on is its rich context system. Instead of copying and pasting code into a chat window and hoping the AI understands what you mean, Cursor lets you point directly at things — files, functions, folders, documentation pages, web URLs, and even git commits — using the @ symbol. The AI then reads exactly what you referenced before generating its response.

This lesson covers everything you need to know about context mentions: what each one does, when to use it, and how the right context transforms vague AI responses into precise, actionable answers.

What You'll Learn

• How the @-mention system works in Cursor chat
• Using @Files to reference specific source files
• Using @Folders to include entire directory context
• Using @Code to target specific symbols and functions
• Using @Web to pull in live web search results
• Using @Docs to reference indexed documentation
• Using @Git to include commit and diff history
• How context affects the quality of AI responses
• Tips for choosing the right context mention
• Understanding context window limits

How the @-Mention System Works

When you type @ in Cursor's chat panel, a popup appears listing everything you can reference. Cursor resolves each mention before sending your message to the AI model. The referenced content — the full text of a file, the contents of a folder, a function's source code, or a documentation excerpt — is injected into the prompt that the model sees.

This matters because language models are stateless. They have no memory of your project from a previous session, and they cannot open files on their own inside the chat panel. Every piece of context they need must arrive in the prompt. Context mentions are Cursor's mechanism for doing that injection automatically and accurately.

To trigger a mention, type @ followed by the type of thing you want to reference:

@Files        → reference a specific file by name
@Folders      → include all files in a directory
@Code         → reference a specific symbol, function, or class
@Web          → trigger a web search and include results
@Docs         → reference indexed documentation for a library
@Git          → include git history, diffs, or commit messages
@Codebase     → search your entire indexed project (covered in the next lesson)

After typing @, you can continue typing to filter the results. Cursor's fuzzy search makes it fast to find the right file even in large projects.

@Files: Referencing Specific Files

@Files is the most commonly used mention. It tells Cursor to read a specific file and include its full contents in the context window.

When to Use @Files

Use @Files when:

• You want the AI to understand or modify a specific source file
• You are asking about a bug in a particular component
• You want to discuss the structure of a specific module
• You want to generate code that is consistent with 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 simultaneously?

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

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

When you reference a file, Cursor reads it in full. This means the AI sees the actual imports, type definitions, logic, and exports — not just a filename. The difference in response quality compared to describing the file in words is substantial.

Referencing Multiple Files

You can include multiple @Files mentions in a single 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?

Including both files lets the AI see the exact shape of the form data and the exact validation the API applies, making it far more likely to identify the real problem.

@Folders: Including Directory Context

@Folders includes the file tree of a directory and, depending on the folder size, the contents of files within it. This is useful when your question spans multiple related files.

When to Use @Folders

Use @Folders when:

• You want the AI to understand the structure of a module or feature area
• You are asking about conventions used across a set of files
• You want to generate a new file that fits the patterns of an existing directory
• You are asking an architectural question about one layer of your application

Practical Examples

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

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

@utils/ Are there any utility functions I could reuse for string
formatting, or should I write a new one?

@Folders vs. @Files

Use @Files when you know exactly which file is relevant. Use @Folders when the question spans multiple files in a directory and you are not sure which ones matter most, or when you want to communicate the overall structure of an area.

Be aware that large directories can consume significant context window space. If a folder has dozens of large files, consider narrowing down to @Files for the most relevant ones.

@Code: Referencing Specific Symbols

@Code lets you reference a specific function, class, interface, type, or variable by name. Cursor extracts just that symbol from the file, rather than including the entire file.

When to Use @Code

Use @Code when:

• You want to discuss one specific function without loading the entire file
• The file is large and only one part of it is relevant
• You want to ask about a type or interface definition
• You are asking the AI to write code that calls or implements a specific function

Practical Examples

@fetchUserById Explain what this function does and write a unit
test for it covering the error case where the user is not found.

@UserSchema I want to add an optional `phoneNumber` field to this
Zod schema. What is the correct way to add it without breaking
existing validations?

@calculateDiscount This function has an off-by-one error when the
discount rate is exactly 100%. Fix it.

The advantage of @Code over @Files is precision. If you have a 500-line service file with dozens of functions, referencing just the one function keeps the context focused and leaves room in the context window for other relevant information.

@Web: Including Live Web Search Results

@Web triggers a web search using your query and includes the results in the context. This is useful for questions that require up-to-date information that the AI's training data may not include.

When to Use @Web

Use @Web when:

• You are asking about a recently released library or API
• You want to know about a known issue or bug in a dependency
• You want the AI to reference current documentation rather than potentially outdated training data
• You are debugging an error message and want to see what the community says about it

Practical Examples

@Web What are the breaking changes in React 19 that affect
class components?

@Web Prisma error: "Can't reach database server" in a Docker
environment — what are the common causes?

@Web Next.js 15 server actions — what changed in the caching
behavior compared to version 14?

@Web adds latency because Cursor performs the search before responding. Use it selectively for questions where current information genuinely matters.

@Docs: Referencing Indexed Documentation

@Docs lets you reference official documentation that Cursor has indexed. You can add documentation sources in Cursor's settings, and they become searchable with @Docs. Many popular libraries — Next.js, React, Tailwind, Prisma, and others — are available out of the box.

When to Use @Docs

Use @Docs when:

• You want the AI to follow the official API rather than guessing
• You are working with a library you are less familiar with
• You want to verify that the generated code uses current, recommended patterns
• The library has changed significantly in a recent version

Practical Examples

@Next.js How do I configure rewrites in the new App Router?
Show me an example using next.config.js.

@Tailwind CSS What is the correct way to define a custom color
in Tailwind 4 using the @theme directive?

@Prisma Generate a query that finds all users who have made a
purchase in the last 30 days, using Prisma's fluent API.

To add custom documentation sources, go to Cursor Settings → Features → Docs and add the URL of the documentation site. Cursor will crawl and index it.

@Git: Including Git History and Diffs

@Git gives the AI access to your repository's git history. You can reference commits, branches, and diffs to give the AI historical context.

When to Use @Git

Use @Git when:

• You want to understand what changed in a recent commit
• You are debugging a regression and want the AI to see what recently changed
• You want to write a commit message that describes the diff accurately
• You want the AI to compare the current state with a previous version

Practical Examples

@Git last commit What changed in the most recent commit? Are there
any obvious issues introduced?

@Git diff HEAD~5 The tests started failing 5 commits ago. Can you
identify which change likely introduced the regression?

@Git We just merged a feature branch. Summarize the changes in
plain English for the release notes.

This mention is particularly useful when debugging because it narrows the search space — rather than asking the AI to audit the entire codebase, you are directing it to the specific changes that could have caused a problem.

How Context Affects AI Response Quality

The single most impactful thing you can do to improve AI responses in Cursor is to provide precise context. Consider the difference between these two messages:

Without context:

Why is my form not submitting?

With context:

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

In the first case, the AI has to guess at the structure of your form, what framework you are using, how you handle submission, and what the API expects. In the second case, it can read the exact code and often identify the problem in a single response.

A good rule of thumb: if you would need to paste code into the chat to describe what you mean, use a context mention instead.

Tips for Choosing the Right Context Mention

• Specific question about one function → @Code
• Question that spans a whole file → @Files
• Question about conventions in a feature area → @Folders
• Question requiring current information → @Web
• Question about a library API → @Docs
• Debugging a regression → @Git
• Broad architectural question → @Codebase (covered in the next lesson)

When in doubt, reference more context rather than less. Extra context is rarely harmful; insufficient context consistently produces generic responses.

Understanding Context Window Limits

Every AI model has a context window — a maximum amount of text it can process in a single request. Cursor's models have generous context windows (often 128,000 tokens or more), but it is still possible to hit the limit if you reference very large files or many files at once.

Signs that you may be hitting context limits:

• Responses that seem to miss obvious information from a file you referenced
• Truncated responses that cut off mid-sentence
• The AI acknowledging it could not read part of the context

To stay within limits:

• Prefer @Code over @Files for large files when only one function matters
• Prefer @Files over @Folders when only a few files are relevant
• Break complex multi-file questions into smaller, focused conversations
• Use @Codebase (which performs targeted search rather than including everything) for broad questions

Cursor displays a token usage indicator in the chat panel. If you see it approaching the limit, consider starting a new conversation and being more selective about context.

Key Takeaways

• The @-mention system lets you inject precise context into every AI request, replacing the need to copy-paste code manually.
• @Files includes an entire file's contents — best for file-level questions and modifications.
• @Folders includes a directory's structure and files — best for understanding a feature area or following existing conventions.
• @Code targets a specific symbol — best for function-level questions in large files.
• @Web adds live search results — best for current information, recent changes, and community-known bugs.
• @Docs references indexed library documentation — best for ensuring generated code follows official APIs.
• @Git includes commit and diff history — best for debugging regressions and summarizing changes.
• More precise context consistently produces more accurate, actionable AI responses.
• Context window limits are real but manageable: prefer targeted mentions over broad ones for large codebases.