Best practices for indexing large local codebases in Cursor for better context

Indexing a 100k+ line codebase in Cursor often hits a wall where the @Codebase feature starts hallucinating or missing obvious function definitions. After spending a month swapping between different indexing strategies and comparing how Cursor handles embeddings versus standard RAG, I've found that the default "indexing" isn't a magic bullet—it's highly dependent on how you prune your context.

The biggest bottleneck isn't the index size, but the noise. If you index your node_modules, .git, or massive build artifacts, you're poisoning the vector space. I noticed a significant jump in retrieval accuracy (roughly 30% fewer "I can't find that function" responses) after aggressively configuring the .cursorignore file. If you haven't set this up, you're basically asking the model to find a needle in a haystack of dependencies.

The .cursorignore Strategy
Treat this like your .gitignore on steroids. You want to strip out everything that isn't source logic. I use this specific setup to keep the index lean:

# .cursorignore
node_modules/
dist/
build/
*.log
.git/
# Ignore large data files that confuse the embedder
*.json
*.csv
*.sql
# Ignore lock files
package-lock.json
yarn.lock

Comparing Model Performance for Context Retrieval
This is where the model choice actually matters. I've benchmarked Claude 3.5 Sonnet against GPT-4o within Cursor's indexing framework.

Claude 3.5 Sonnet is the clear winner for codebase navigation. It handles the "long-range dependency" problem much better. When I ask about a flow that spans three different files, Sonnet usually identifies the correct call stack on the first try. It feels more "aware" of the project structure.

GPT-4o is faster, but it tends to get lazy with large indices. It often suggests generic implementations instead of referencing the actual existing helper functions in your codebase, even when the index clearly contains them.

Gemini 1.5 Pro (via API) is a wild card. While its massive context window makes indexing technically redundant, using it inside Cursor's RAG system feels disjointed. It's better for "dumping" five whole files into the chat than relying on the @Codebase index.

The "Context Pinning" Workflow
Relying solely on @Codebase is a mistake for complex refactors. The most efficient way to work is a hybrid approach: use @Codebase for discovery, but once you've found the relevant files, explicitly add them to the context via @File or by keeping the tabs open.

I've found that the "Composer" mode (Cmd+I) is significantly more stable when you provide a "map" of the files you're working on. If you just say "Fix the bug in the auth flow," it might miss the middleware config. If you provide:

@auth.ts @middleware.ts @Codebase fix the session timeout bug

The success rate for a one-shot fix jumps from about 40% to 80%.

Measured Performance Trade-offs
Index Size vs. Accuracy: Smaller, curated indices (via .cursorignore) lead to faster retrieval and fewer hallucinations.
Model Latency: Sonnet is slightly slower but reduces the need for follow-up prompts because it actually reads the retrieved context.
Token Burn: Over-relying on @Codebase for every single prompt bloats your token usage without adding proportional value.

The goal is to minimize the distance between the model's prompt and the actual source of truth. Prune your index, use Sonnet for the heavy lifting, and manually pin your core architectural files.