Español

Index Your Codebase First

You asked Cursor a question about your whole project — “where should this component live?”, “which files touch the cart?” — and it answered like it had never opened your repo. It probably hadn't. Cursor indexes your codebase, and until that index exists, a prompt written in the context of your entire project has nothing to attach itself to.

What the index is for

When you open a project, Cursor starts indexing it. That index is what lets the tool connect the words in your prompt to the actual files on disk. Without it, the model still answers — it just answers from the code you happened to paste, the file currently open, and general programming knowledge. It has no map of your repo.

That's the mechanism behind the failure mode people report as “the AI doesn't know my project.” It isn't a reasoning problem. It's a retrieval problem: nothing is there to retrieve from yet.

Generally, code assistants build this kind of index by chunking your source files and storing a searchable representation of each chunk, so a natural-language phrase like “the checkout total” can be matched against code that never uses those exact words. The specific implementation varies by tool and changes over time — the part that matters for your workflow is simply that the index is built from your files, it takes time to build, and nothing that depends on it works before it's done.

The rule

Until your codebase is indexed, Cursor cannot understand your entire codebase and cannot map it to your prompt. Say something in the context of the whole project before indexing finishes and it will not be able to understand it. Only after indexing can you ask questions at that scope and expect a grounded answer.

This is worth internalizing because the failure is silent. An un-indexed Cursor doesn't say “I don't have your repo yet.” It produces a confident, generic, plausible answer — a component placed in a directory that doesn't exist, an import path invented from convention rather than read from your tree. You find out later, at review time or at runtime.

How to check it

1. Open Settings.
2. Go to Features.
3. Find Codebase Indexing.

That's where you confirm the state of the index, and where you can trigger it yourself rather than waiting to notice it happening on its own. Make it the first thing you check when you open an unfamiliar repo in Cursor, and the first thing you check when an answer comes back suspiciously generic.

What the index unlocks

Once the codebase is indexed, the agent can search your codebase directly. Given a task like “add these product images to the men's clothing section,” it will search the repo, find where the images are and where they need to go, and apply the edit in the right place — instead of asking you to name every file or guessing at a structure.

Index the codebase  →  Agent searches it  →  Edits land in the right files

Break any one of those and the next two are worthless. No index, no search. No search, no idea which file to edit.

When it matters most

• Whole-project questions. “Where does this belong?”, “Which files touch this?”, “What's the pattern we use for X here?” — every one of these is a question about the repo, not about a snippet.
• A codebase you didn't write. The index is doing the orientation work you'd otherwise do by hand with a file tree and grep.
• Multi-file changes. A task that spans several files depends on the agent locating all of them. It can't locate what it hasn't indexed.
• Any freshly opened or freshly cloned project. This is the moment the index doesn't exist yet, and also the moment you're most likely to ask a broad orienting question.

Pitfalls

• Don't judge Cursor by its first answer in a new project. You may be judging an un-indexed tool. Check the index, then re-ask.
• Don't assume it's done because time passed. Look at Settings → Features → Codebase Indexing rather than guessing.
• Don't work around a missing index by pasting more files. That's treating the symptom. Let the index finish and get whole-repo search instead of a bigger paste buffer.

Takeaway

No index, no whole picture. Cursor indexes your codebase, and the tool's most valuable behavior — searching your repo, finding where things live, landing edits in the right files — sits entirely on top of that index. Check Settings → Features → Codebase Indexing, let it finish, then ask.