What Are Cursor @ Commands and Why They Matter
When you type @ in Cursor's chat or Composer, you're not just mentioning a file — you're injecting structured context directly into the AI's prompt. The model sees exactly what you point to, nothing more.
This is the core mechanic that separates a focused, accurate edit from a hallucinated one. Getting @ usage right is the fastest way to level up your Cursor workflow.
How Context Injection Works
Every Cursor AI request has a context window — a fixed token budget the model reads before generating a response. By default, Cursor makes educated guesses about what's relevant using its codebase index.
@ commands override that guesswork. You're explicitly saying: "Read this, not whatever you think is related."
Your message + @references → Cursor prompt → LLM → Response
The more precise your @ references, the less the model has to infer — and the fewer tokens get wasted on irrelevant files.
Every @ Command Explained
@Files
Injects the full content of one or more files into context.
@src/lib/auth.ts fix the token refresh logic
Use this when your question is about a specific file. Cursor highlights the file in the context panel so you can verify it loaded.
When to use: Bug fixes, refactors, explaining what a specific file does.
Limit: Large files (>500 lines) eat token budget fast. Prefer @Code for targeting a section.
@Folders
Injects a summary of every file in a folder, with full content for files Cursor deems relevant.
@src/components/ why are these components not reusing the Button primitive
Cursor doesn't blindly dump every file — it uses the folder structure and file names to pick what matters. Full content only loads for the most relevant files.
When to use: Architecture questions, finding patterns across a module, asking "why does this folder work this way."
@Code
Targets a specific function, class, or block — not the whole file.
@Code:parseJWT explain what happens when the token is expired
You can also select code in the editor first, then open chat. Cursor auto-fills the selection as @Code.
When to use: Asking about one function without pulling in 800 lines of surrounding context.
@Docs
Pulls from Cursor's indexed documentation library — official docs for popular libraries, not your local files.
@Docs:Next.js how do I use generateStaticParams with dynamic segments
Cursor ships with pre-indexed docs for React, Next.js, TypeScript, Python, Rust, and dozens more. You can add custom doc sources in Settings → Features → Docs.
When to use: When you need framework-accurate answers, not training-data guesses. Especially useful for APIs that changed recently.
@Web
Triggers a live web search and injects the results as context before answering.
@Web latest Ollama GPU flags for RTX 5090
This is different from @Docs — it searches the open web in real time. Useful for anything that moves fast: changelogs, release notes, community workarounds.
When to use: Cutting-edge library versions, error messages you suspect are recent, anything your @Docs index might not have yet.
@Codebase
Runs a semantic search across your entire indexed codebase and injects the most relevant snippets.
@Codebase where do we handle Stripe webhook verification
Cursor's indexer builds a vector embedding of your repo. @Codebase queries that index — it doesn't read every file linearly. Results depend on how well your code is indexed (see: .cursorignore).
When to use: "Find where X is handled" questions, understanding unfamiliar codebases, cross-cutting concerns like auth or error handling.
@Git
Injects git context — diffs, commit history, or blame data.
@Git what changed in the last 3 commits to the auth module
Useful when debugging regressions. Instead of running git log yourself and pasting the output, @Git does it inline.
When to use: "What broke and when", reviewing a PR diff, understanding why a line exists.
@Terminal
Injects your most recent terminal output into context.
@Terminal why did this build fail
After a failed npm run build or a crashing test run, hit @Terminal and ask. Cursor reads the last N lines of stdout/stderr automatically.
When to use: Debugging build errors, test failures, any time you'd normally copy-paste terminal output into chat.
@Notepads
Injects content from a Cursor Notepad — a persistent scratchpad you can pre-fill with reusable context.
@Notepads:project-conventions use these conventions when refactoring this component
Notepads are defined in the Cursor sidebar. Think of them as named context blocks you can reference repeatedly across sessions.
When to use: Team coding standards, boilerplate patterns, prompt snippets you use every day.
@CursorRules (.cursorrules)
Not technically an @ command, but works alongside them. The .cursorrules file in your project root is always injected into every Cursor request automatically — you don't need to @ it.
Use .cursorrules for project-wide constraints: preferred libraries, naming conventions, style rules. Use @Notepads for context you want to inject selectively.
Combining @ Commands
You can stack multiple @ references in one message. Cursor merges them all into a single context block.
@src/api/users.ts @Docs:Prisma @Codebase refactor this endpoint to use the repository pattern we use elsewhere
This injects:
- The specific file being refactored
- Prisma's official docs
- Relevant snippets from your codebase showing the existing repository pattern
Be intentional. Each @ costs tokens. A bloated context window can push out the code you actually want the model to focus on.
Practical Patterns
Debugging a runtime error
@Terminal @src/server/middleware/rateLimit.ts
The middleware is blocking all requests. What's wrong?
Understanding unfamiliar code
@Codebase how does this project handle database migrations
Staying current with a fast-moving library
@Web Drizzle ORM 0.40 breaking changes
Enforcing code style across a refactor
@Notepads:style-guide @src/components/Modal.tsx
Refactor this to match our conventions
Production Considerations
Token budget. Context has a hard limit. If you inject @Codebase + three large @Files + @Docs, you may hit the ceiling and get truncated responses. Watch the context bar in Composer — it shows how full the window is.
Index freshness. @Codebase depends on Cursor's local index being up to date. After large refactors, force a reindex via Command Palette → Cursor: Rebuild Index.
.cursorignore. Add generated files, node_modules, build artifacts, and large data files to .cursorignore. They pollute @Codebase results and waste token budget.
# .cursorignore
node_modules/
.next/
dist/
*.lock
*.csv
Summary
@Files/@Code/@Folders— reference your local source@Codebase— semantic search across the whole repo@Docs— indexed official documentation@Web— live web search for real-time info@Git— diffs and commit history@Terminal— last terminal output@Notepads— reusable named context blocks
The rule: be as specific as possible. A single well-chosen @Code reference beats a vague @Codebase query every time. Precise context = precise output.
Tested on Cursor 0.48, macOS and Windows 11