Cursor Context Providers

Context providers are the ways you add information to a Cursor AI prompt. Every time you type @ in Chat, Composer, or Cmd+K, a menu opens with every provider Cursor supports: files, folders, the indexed codebase, docs, web search, terminal output, git history, and saved notepads. This page walks through each one with an example and a rule of thumb for when to reach for it.

The @ menu

Type @ in any prompt box. A searchable menu appears with every provider. Keep typing to filter. Press Enter to attach.

Attached context shows above the input as a chip. Click the chip to remove. You can attach any number of items to a single prompt, up to the model context window. Sonnet 4.5 is 200k tokens, so for most practical cases you will not hit the limit.

@Files - attach a specific file

@Navbar.tsx How does this component handle the dark mode toggle?

Cursor includes the full file content in the prompt. Token cost is the file size. Use this when you know exactly which file the AI should read.

For very large files (more than 2000 lines), Cursor truncates the attachment with a warning. Split the file or attach a relevant section with the file range feature.

@Folders - attach a directory

@src/components Summarize every component in this folder and how they relate.

Cursor includes every file in the folder, recursively, up to the token budget. For folders with hundreds of files, the model sees a truncated sample rather than the whole tree.

Rule of thumb: attach folders when you want the AI to infer a pattern across siblings, not when you want an exhaustive read. For exhaustive work use Composer agent mode and let the agent open files one at a time.

@Code - attach a function or class by name

@useAuth Does this hook handle token refresh?

Cursor searches the codebase for symbols matching the name and attaches the definition. If multiple matches exist, you pick from a submenu.

This is the precision tool. Attaching the whole file pulls in hundreds of lines of unrelated code; attaching the function by name pulls in just what you need.

@Docs - pull documentation

@Next.js How do I add a server action that returns a stream?

@Docs lets you reference docs Cursor has indexed. Out of the box it includes major frameworks: React, Next.js, Vue, Svelte, Tailwind, Django, FastAPI, PyTorch, and a few dozen more.

You can add custom docs under Settings > Features > Docs. Paste a URL and Cursor crawls and indexes the site. Crawl time varies from a minute for a small reference to an hour for a full framework site.

The indexed docs are versioned to when you added them. Re-crawl when the upstream docs update; Cursor does not do this automatically.

@Web - real-time web search

@Web What is the current rate limit for the GitHub API?

@Web runs a live web search and includes the top results in the prompt. Costs 1 premium request extra because the search and the model call are separate.

Use @Web for facts that change: pricing, API quotas, current library versions, recent security advisories. Do not use it for how-to content that is better served by indexed docs.

@Git - commit and diff context

@Git Summarize the changes in the last 5 commits on this branch.

@Git pulls recent commits and their diffs into context. You can scope to the current branch, a specific commit, or the diff against main.

Good uses: writing PR descriptions, generating changelogs, investigating why a test started failing at a specific commit. The agent mode version of this can run git log and git diff directly as terminal commands; @Git is the lighter way to get the same data into Chat.

@Codebase - semantic search

@Codebase Where is the logic that determines if a user is on the Pro plan?

@Codebase runs a semantic search across the indexed project and attaches the top matches. This is the heavy hitter. It works when you do not know the file name or function name, only the concept.

The quality of @Codebase depends on the codebase index. More on that below.

@Terminal - last terminal output

@Terminal Why did this test fail?

@Terminal attaches the output of the most recent terminal command. Handy for debugging errors, stack traces, build failures, and test output without copy-pasting.

@Notepads - saved prompt scratchpads

@DesignSystem Apply these tokens to the Button component.

@Notepad attaches a named notepad. See the Notepads page for how notepads work and when to use them. Rule of thumb: notepad for reusable context, file for project-specific context.

Codebase indexing

For @Codebase to work, Cursor must index the project. The first index runs automatically on project open and takes 30 seconds for small projects, up to 10 minutes for monorepos with 100k+ files.

The index is built by:

1. Walking the workspace tree
2. Splitting files into chunks of about 500 tokens
3. Generating embeddings for each chunk via Cursor's embedding endpoint
4. Storing embeddings locally and syncing a copy to Cursor servers

The local copy enables fast search. The server copy lets Cursor merge embeddings across your team if you are on the Business plan.

Index privacy

Cursor has three privacy modes under Settings > Features > Codebase Indexing:

• Default: code chunks are sent to Cursor's embedding API but not stored after the embedding is returned.
• Privacy Mode: chunks are not sent to Cursor servers. Indexing runs locally via a smaller embedding model.
• Team indexing: shared across the organization; requires Business plan.

Business customers get audit logs of every chunk that was sent for embedding. Individual Pro users cannot audit the pipeline at that level.

Re-indexing

The index updates incrementally as you edit files. A full re-index is rare but sometimes needed after large refactors, branch switches, or git merges. Trigger a re-index under Settings > Features > Codebase Indexing > Re-index.

Re-indexing runs in the background. You can keep working; queries fall back to the previous index until the new one is ready.

Precision vs recall - @Files vs @Codebase

The common confusion is when to attach a specific file vs let @Codebase find it for you.

Attach @Files when:

• You know the exact file name
• The question is about one file
• You want the full file content, not just the top-matching chunks

Attach @Codebase when:

• You do not know where the relevant code lives
• The question spans multiple files you cannot name up front
• You want the top 3-5 most relevant chunks across the whole project

For ambiguous cases, start with @Codebase, see what it returns, then escalate to @Files if you need the full content of a specific match.

Context window limits

The current Cursor model lineup has these windows:

• Cursor Small: 32k tokens
• GPT-4o: 128k tokens
• Claude Sonnet 4.5: 200k tokens
• Claude Opus 4: 200k tokens
• Gemini 2.5 Pro: 1M tokens

Attaching context eats the window. A 1000-line TypeScript file is around 8000 tokens. Five files is 40k. Fifteen files starts to crowd Sonnet out.

Practical cap: 5-8 file attachments per prompt, or one folder attachment. Past that, rely on agent mode to read files as needed.

When context is not enough

Some questions need active exploration, not static context. Signs you should use Composer agent mode instead of adding more @ attachments:

• You need to run a test and react to the output
• The answer depends on the output of a shell command
• You want the AI to browse the codebase rather than read what you picked
• You are iterating across many files and the attachment list keeps growing

In agent mode the model picks its own context on each step, which scales better than manual attachments past a certain point.

Composing providers in a single prompt

The providers are designed to stack. A realistic debugging prompt might combine four of them at once: @Terminal for the failing test output, @Code for the function under test, @Files for the test file itself, and @Docs for the relevant framework reference. The AI then has the error, the source, the test, and the authoritative docs in one request, and can reason about all four together without you needing to paste anything. That composition is where Cursor context providers pay off the most, because the model answer quality jumps sharply when you give it the four pieces together versus any single one alone. It takes about ten seconds to build this kind of prompt once you know the provider shortcuts, and it replaces what used to be ten minutes of manual copying from terminal to browser to chat box.

Provider shortcuts worth memorizing

Three shortcuts save the most time day to day. @F then the file name for a file attach; @C for codebase search; @W for web. The menu filters live as you type, so two or three characters plus Enter is usually enough to attach the right provider without taking your hands off the keyboard.