Multi-File Context

The @ symbol in Cursor's chat is your tool for giving the AI precise context. Instead of the AI guessing which files matter, you tell it explicitly.

Referencing a file:

In the Chat input, type @ and start typing a filename:

@src/utils/helpers.js Can you explain the debounce function in this file?

As you type after @, Cursor shows an autocomplete dropdown listing matching files from your project. Select the file you want and it appears as a context chip above the input.

Referencing a symbol (function, class, variable):

You can reference specific code symbols directly:

@calculateShipping I need to add international shipping rates to this function.
What parameters should I add?

Cursor will find the calculateShipping function across your codebase and attach it as context.

Multiple references in one message:

@src/models/Order.js @src/services/payment.js @src/routes/checkout.js
I want to add a discount code feature. Show me how these files need to change.

Each referenced file gets its full content included in the AI's context.

What the context bar shows:

Above the Chat input, you'll see pills/chips for each attached context item:

• File names with their path
• Symbol names with their location
• An X button to remove each item

Auto-detected context:

Beyond explicit @-mentions, Cursor also includes:

• The currently active file in the editor
• Any code you've selected before opening Chat
• Recent error messages from the terminal (if relevant)

When you use Agent mode, Cursor automatically finds relevant code across your project — you don't need to manually attach context. Just ask your question naturally.

How it works:

How is user authentication implemented across this project?

When you ask Agent a question, Cursor:

1. Automatically searches your project for relevant files and code sections
2. Identifies the most relevant snippets using semantic search
3. Reads files it needs for deeper understanding
4. Answers based on this project-wide context

Good project-wide questions for Agent:

Automatic context vs explicit @file — when to add manually:

When Agent might miss context:

• Very large monorepos may have some files missed
• If your question is ambiguous, Agent may find the wrong files — be specific
• For full file content (not snippets), explicitly attach with @filename
• Newly created files may not yet be discoverable

Cursor can reference external documentation to help with framework-specific questions.

Using @docs:

@docs Next.js How do I set up API routes with the App Router?

The @docs prefix tells Cursor to pull in documentation from known sources for the specified technology.

Supported documentation sources:

Cursor maintains indexes of popular framework and library documentation. Common examples:

• @docs React — React documentation
• @docs Next.js — Next.js framework docs
• @docs Python — Python standard library
• @docs TypeScript — TypeScript handbook
• @docs Tailwind — Tailwind CSS utilities

Adding custom documentation sources:

You can add your own documentation URLs in Cursor Settings:

Practical examples:

@docs Express @src/routes/api.js
How do I add middleware that validates JWT tokens before these routes?

This combines documentation context (Express best practices) with your actual code for a highly relevant answer.

@docs PostgreSQL @src/db/schema.sql
I need to add a full-text search index for the articles table. What's the best approach?

Other @ context sources:

Every piece of context you provide to the AI consumes space in the model's context window. Managing this budget effectively is crucial for good answers.

Understanding the context window:

Figures current at August 2026, and Cursor's model list changes often — check the picker rather than this table. Note the gap between the two columns: the practical limit is well under the advertised one, because recall across a long context degrades before the context is full. Treat the window as storage, not as dependable working memory.

A "token" is roughly 3-4 characters of code. A typical 100-line code file uses about 1,000-2,000 tokens.

What consumes context:

Signs you've exceeded useful context:

• AI responses become vague or generic
• The AI "forgets" something you mentioned earlier in the conversation
• Responses focus on only one of the files you referenced
• You see a warning about context limits in the chat

Context management strategies:

1. Start specific, broaden if needed — begin with 1-2 @file references, add more only if the AI needs them

2. Start fresh for new topics — click the + button for a new chat instead of continuing an unrelated conversation

3. Remove unnecessary context — click X on context chips you no longer need

4. Use Agent's context search for exploration, then @file for action — ask Agent's context search to find the right files, then start a new chat with those specific files

5. Reference small sections — select just the relevant function before pressing Cmd+L, rather than attaching the entire file

Different tasks require different context strategies. Here's a framework for choosing:

Task: Understanding unfamiliar code

Context: Agent's context search (broad exploration)
Prompt: "How does the payment processing flow work in this project?"

Follow up with specific files once you know where to look:

Context: @src/services/stripe.js @src/routes/payment.js
Prompt: "Walk me through the checkout flow step by step"

Task: Adding a new feature

Context: @file with similar feature + @file where you'll add it
Prompt: "@src/routes/users.js @src/routes/orders.js
I want to add a new route for managing wishlists.
Follow the same pattern as the orders route."

Task: Fixing a bug

Context: The file with the bug + related files
Prompt: "@src/utils/dateFormat.js @src/components/Calendar.jsx
The calendar shows dates one day off. The issue seems to be
in the date formatting utility. Can you spot the timezone bug?"

Task: Refactoring across multiple files

Context: All affected files (but keep it under 5-6 files)
Prompt: "@src/api/v1/routes.js @src/api/v1/controllers.js
@src/api/v1/middleware.js
I want to refactor from Express to Fastify. What changes are needed?"

Task: Writing documentation

Context: The code + any existing docs
Prompt: "@src/lib/cache.js @README.md
Add JSDoc comments to all exported functions in cache.js
and update the README's API section."

The "minimum effective context" principle:

Always ask yourself: "What's the minimum context the AI needs to answer this well?" More context isn't always better — it can dilute focus and slow responses.

The Agent's context search feature relies on Cursor's code index. Understanding what's indexed helps you get better results.

What gets indexed:

• All source code files in your workspace (.js, .ts, .py, .java, etc.)
• Configuration files (package.json, tsconfig.json, etc.)
• Markdown files and documentation
• Test files
• Scripts and build files

What does NOT get indexed:

• Files in .gitignore (by default)
• Binary files (images, compiled code, archives)
• node_modules/ and other dependency directories
• Very large generated files (e.g., bundled output, minified code)
• Files exceeding the individual file size limit

Checking indexing status:

Controlling what's indexed:

You can create a .cursorignore file in your project root (similar to .gitignore) to exclude files from indexing:

# .cursorignore
build/
dist/
coverage/
*.min.js
*.generated.ts
vendor/

This is useful when:

• Generated files confuse the AI (it references outdated generated code)
• Large data files slow down indexing
• You have folders that aren't relevant to your AI queries

Re-indexing:

If you've made significant structural changes to your project (renamed folders, added many files), you may want to force a re-index:

1. Open Command Palette
2. Run "Cursor: Reindex Codebase"
3. Wait for the status bar indicator to show completion

Index freshness:

Cursor re-indexes files automatically when:

• You save a modified file
• New files are created
• Files are deleted or renamed
• You pull new changes from git

The index stays up-to-date for most workflows without manual intervention.