What this covers
A well-tuned Cursor index is what separates “Cursor understands my code” from “Cursor keeps referencing files that do not exist.” This walkthrough is the actual tuning loop — what to ignore, when to re-index, how to use @File / @Folder / @Symbol for precision, and how to diagnose the slow-or-broken index that bites larger codebases.
Who this is for
Cursor users in larger codebases — anything past a small starter project. Especially useful for monorepos, codebases with heavy build output, and projects where Cursor has started missing or mis-referencing files. If you have not done the basic onboarding yet, run Cursor for beginners — 30 minutes to a working loop before tuning the index.
When to reach for it
When you have noticed Cursor mis-referencing files, suggesting symbols that do not exist, repeatedly missing files that obviously do exist, or slowing down dramatically. Also worth doing proactively right after any major repository change (large merge, branch switch, dependency upgrade).
Before you start
- Open the Cursor settings panel and find the indexing status. Note current state (“Indexing…,” “Synced,” or “Failed”).
- Identify what is bloating the index: build output, large data files, generated code, vendored libraries, git history files.
- Decide which folders contain the real signal — usually
src/,lib/,app/,pages/— and which are noise. - Know your project conventions for what is generated vs hand-written. Generated code rarely needs indexing.
Step by step
- Maintain a strict
.cursorignorein the repo root. Start from this baseline and add as needed:
node_modules/
dist/
build/
.next/
.astro/
.cache/
coverage/
*.log
*.map
public/assets/ # if these are generated
data/large/ # large data files- Re-index after big repo changes — large merges, dependency upgrades, branch switches with significant divergence. Cursor settings → “Re-index repo.” A stale index causes wrong-file references that look like model failures but are actually search failures.
- Use
@File/@Folder/@Symbolexplicitly when ambiguity exists. Instead of “fix the auth bug,” say “fix the bug in@File:src/auth/login.ts.” The mention pins context and bypasses index ambiguity. - Avoid indexing build artifacts. Anything that is regenerated by a build step does not belong in the index. Add it to
.cursorignorebefore the first index, not after. - For monorepos, scope by workspace folder. Open the specific workspace (
packages/web) in Cursor rather than the repo root when working in one package. - When an index is stuck or slow, check the indexing log (Cursor settings → developer/diagnostics). Common culprits: a single huge file, a deep symlink, or an encrypted folder.
A diagnostic checklist for slow indexing
- Is
node_modulesignored? If not, indexing time is dominated by node_modules. - Are any files over 10MB? Cursor struggles with single huge files; gzip or split them.
- Are there symlinks pointing outside the repo? Cursor may follow them and try to index your home directory.
- Are there generated files in source paths? Move them or ignore.
- Is the git repo healthy (
git fsck)? Index uses git metadata.
First-run exercise
- Check current index status. If “Synced,” skip to step 3.
- Open
.cursorignore. Add the baseline above. Re-index. Time it. A modest project should index in under 2 minutes. - Open Composer. Reference a file with
@File. Confirm the file content appears in the context. If not, your ignore rules accidentally excluded it. - Run a small Inline edit referencing a non-trivial symbol. Cursor should find it without guessing.
Quality check
- Indexing finishes in a reasonable time (under 5 minutes for medium projects, under 15 for monorepos). Longer is suspicious.
@Filereferences resolve to the file you expected.- Composer suggestions reference real symbols. Hallucinated symbol names mean the index is missing the file.
- No private data, secrets, or build output appears in indexed context. Spot-check by asking Cursor to “list the files you can see in
src/.”
How to reuse this workflow
- Commit
.cursorignoreto the repo so teammates inherit the tuning. - Re-tune after major refactors that move files around. Old paths in the index cause wrong references.
- Build a list of “always pin with @” symbols and files — central configs, key types, the main entrypoint. Mention them explicitly in any non-trivial prompt.
- Re-test the index quarterly. Cursor’s indexing strategy evolves and a stale
.cursorignoremay now over- or under-exclude.
Recommended workflow
Add .cursorignore → trigger re-index → reference files explicitly with @ → review what Cursor sees → repeat after any major repo change.
Common mistakes
- Indexing
node_modules. Slow, noisy, and pollutes context with library code. - Never re-indexing after major changes. The index drifts and references go stale.
- Letting the index sit at “Indexing…” for hours and assuming it just needs more time (why indexing never completes).
- Relying on implicit context for cross-file edits. Use
@mentions; the index is good but not telepathic. - Having competing rules across project, workspace, and user
.cursorrulesfiles — symptoms show up as ignored instructions, not as an error (Cursor config conflict). - Indexing private secrets. Add
.env,secrets/, and similar to.cursorignoreimmediately.
FAQ
- Does Cursor’s index leave my machine?: Embeddings are computed remotely on Cursor’s infrastructure; file content is hashed and chunked. Check the latest privacy docs before indexing sensitive code.
- How big a repo can Cursor index?: Tens of thousands of files is fine with a clean
.cursorignore. Million-file monorepos need workspace-scoped opens. - Why does Cursor still miss files after indexing?: Either the file was ignored, the index is stale, or your prompt did not pin enough context. Use
@Fileto verify. - Should I re-index after every commit?: No. Cursor watches the file system and updates incrementally. Manually re-index only after large changes.
Related
Tags: #AI coding #Tutorial #Cursor