How .cursorignore Shrinks What Cursor Indexes

.cursorignore lives at the project root and uses .gitignore pattern syntax. Cursor blocks listed paths from Agent, Tab, Inline Edit, and @ mentions. In monorepos or repos full of generated files, excluding noise thins the index and reduces the chance secrets land in AI context.

This post covers ignore patterns, build artifacts, and symptoms when the agent cannot read a file. No plan pricing or personal anecdotes. Grounded in the Cursor Ignore file reference and the Ignore files help article.

How does it differ from .gitignore?

One-line answer: .gitignore controls what Git tracks; .cursorignore controls what Cursor’s AI can access. Cursor already honors .gitignore plus a default ignore list, so .cursorignore is for extra exclusions on top.

FilePrimary jobRelation to Cursor
.gitignoreKeep paths out of commitsAuto-respected → gitignored files stay out of AI context too
.cursorignoreBlock Agent / Tab / Inline / @Track in Git but hide from AI, or exclude paths not in .gitignore
Default ignore listBuilt into Cursornode_modules/, .next/, .env*, lockfiles, binaries/media, and more (see docs)

When .cursorignore still earns its keep:

  1. Tracked in Git, unwanted in AI — large fixtures, internal dumps, sample datasets that must stay in the repo.
  2. Secrets and credentials — .env*, credentials.json, *.pem may already be covered by defaults or global ignore; spelling them out documents team intent. Docs cite both security and performance.
  3. Parent directories — enable Hierarchical Cursor Ignore under Cursor Settings → Indexing → Ignore Files so Cursor also searches ancestor .cursorignore files.
  4. Global ignore — user settings can hold cross-project patterns (empty by default). Docs suggest patterns such as **/.env, **/.env.*, **/credentials.json, **/*.pem.

Syntax matches .gitignore (*, **, ?, ! negation, # comments). You cannot re-include a nested file if a parent directory was excluded with a broad * pattern—excluded directories are not traversed. Prefer the docs’ stepwise exclude/re-include patterns. Debug with git check-ignore -v [file].

Hard limit: terminal and MCP tools used by Agent are outside .cursorignore file controls. Ignored paths may still be readable via shell or MCP. Docs also note ignore is not a guarantee of complete protection.

What about build artifacts?

One-line answer: Drop reproducible, low-value outputs first—dist/, build/, .next/, caches, generated trees. Many are already on the default list; strengthen .cursorignore (or .gitignore) only for team-specific artifact paths.

Example priorities:

# App / framework outputs (tune to your stack)
dist/
build/
out/
.turbo/
coverage/

# Toolchain caches
__pycache__/
*.egg-info/
.gradle/
target/          # e.g. Java/Rust build output (match repo convention)

# Noise / bulk
*.min.js
**/generated/
**/fixtures/large/

Practical notes:

  • Already default-ignored — node_modules/, .next/, .nuxt/, .cache/, .venv/, lockfiles, many binary/media extensions appear in the Default ignore list. Repeating them is optional documentation of intent.
  • Committed artifacts — checked-in dist/ or vendor snapshots: keep Git tracking, add paths only to .cursorignore to shrink AI context.
  • Do not mix secrets and outputs carelessly — if you need shape-only files (e.g. .env.example), use ! carefully and avoid excluding a whole parent with * before re-including nested paths.
  • Monorepos — broadly ignore other packages’ dist/ trees; leave the package you are editing’s sources visible.

Help docs give the same rationale: large generated files, binaries, and third-party trees slow indexing and add noise.

Symptoms when the agent cannot read a file?

One-line answer: Ignored paths drop out of editor-side AI tools (file reads, @, Tab/Inline context). If the agent says it cannot find or open a path, returns empty content, or patches the wrong place while assuming that file, check ignore first.

Observation checklist:

  1. @ mentions / codebase references — ignored files are hard or impossible to pull in; docs state .cursorignore blocks @ mention access.
  2. Agent / Tab / Inline Edit — access to that code is blocked. Phrases like “no permission,” “cannot read,” or fabricated code for a path that exists locally often mean the path is ignored.
  3. Terminal / MCP exception — the same Agent reading the file via cat/rg or MCP does not contradict ignore; docs call out this bypass. For secrets, ignore alone is not enough—use env/permission/secret stores separately.
  4. Over-ignore — blocking src/ or schema files makes the agent propose unrelated edits. Symptoms pair “cannot read” with “wrong patch.” Keep needed sources and examples (e.g. .env.example) visible.
  5. Pattern debug — git check-ignore -v path/to/file. With Hierarchical ignore on, also inspect ancestor .cursorignore files.

Triage order: (1) which layer matches—.gitignore / defaults / .cursorignore / global → (2) whether ! conflicts with a parent exclude → (3) readable only via terminal (tool block vs missing file).

Wrap-up

To shrink indexing, know what .gitignore + defaults already drop, then put Git-tracked but AI-unwanted paths and team-specific build/bulk artifacts in .cursorignore. When the agent cannot read a file, suspect ignore first; separate terminal/MCP bypass from over-blocking. Security does not end at ignore.

Sources