Asking Questions About Your Whole Codebase

Some questions could be answered by any file in your project. "Where is this feature implemented?" "What pattern does this codebase use for error handling?" "How do these two systems talk to each other?" You don't want to guess which file to reference. You want to ask the whole codebase.

In Cursor, you just ask. Older versions had a special @codebase mention for this, but it is gone. Today the agent searches your project by itself whenever a question needs it. In Agent mode it searches and can then make changes. In Ask mode it searches and explains, without editing anything.

What You'll Learn

• How the agent finds relevant code on its own
• How Cursor's codebase indexing works
• When to just ask and when to add @ mentions
• How to phrase good codebase-wide questions
• Asking architectural questions and finding implementations
• Getting oriented in an unfamiliar codebase
• Limits of codebase search and how to work around them

How the Agent Finds Code

When you ask a question in the Agent side panel, the agent decides what it needs to look at. It can run a semantic search over your indexed project (search by meaning, not exact words), run plain text searches for exact names, list folders, and open the files it finds. It may do several rounds of this before answering, and you can watch the files it reads in the chat.

Compare that with @ mentions:

Approach	Who decides what to read
Mention a file or folder	You do. The content is attached up front.
Just ask	The agent does. It searches and reads what looks relevant.

The practical rule: just ask when you are exploring or don't know where to look. Add @ mentions when you already know which files matter.

Ask Mode for Pure Exploration

If you only want answers, switch to Ask mode (press Shift+Tab in the chat input, or use the mode picker). Ask is read-only, so the agent explores and explains without touching your files. It is a safe choice for learning a new codebase.

How Codebase Indexing Works

The semantic search depends on an index of your project. Here is roughly what happens:

1. File scanning: Cursor reads the files in your project, skipping anything in .gitignore. You can also exclude more files with ignore patterns (for example a .cursorignore file).
2. Chunking: Each file is split into smaller pieces of code.
3. Embedding: Each piece is turned into an embedding, a list of numbers that captures what the code means.
4. Search: When the agent searches, your question is turned into an embedding too, and Cursor finds the pieces with the closest meaning.

This is why the agent can find your "telemetry" code when you ask about "logging", at least some of the time.

Checking Index Status

A newly opened project starts indexing automatically, and large projects can take a few minutes the first time. You can see indexing progress, and trigger a re-index, in Cursor Settings (look for the indexing section). Settings layouts change between versions, so check the Cursor docs if you can't find it.

Phrasing Codebase-Wide Questions

The agent's search is driven by your words. A few habits make a big difference:

• Say what you are trying to do, not just what you want to find. "Where is email sending implemented? I need to add a password reset email" gives the agent a goal.
• Use the words the code is likely to use. If you know the project calls users "members", say "members".
• Ask for file paths. "List the files involved" gives you a map you can check.
• Ask one big question at a time. Broad, multi-part questions get shallower answers.

Asking Architectural Questions

Whole-codebase questions shine for architecture: how the system is organized, not just how one function works.

Overall Structure

How is this application organized? What are the main layers,
and how do they interact? List the key folders.

What database ORM or query builder does this project use, and
where is the database configuration?

How does authentication work in this app? Where is the session
managed, and how are protected routes enforced?

Design Patterns

What pattern is used for state management? Context, Redux,
Zustand, or something else?

How does this codebase handle errors? Is there a central error
handler, or is it handled per module?

Data Flow

How does data flow from the API response to the rendered UI on
the products listing page?

When a user submits an order, what sequence of functions and
services handles it?

These questions need information from many files at once. The agent finds and connects those files for you.

Finding Where Things Are Implemented

One of the most practical uses is finding where something lives:

Where is email sending implemented? I need to add a new
transactional email for password resets.

Is there an existing utility for date formatting? I don't want
to write a new one if something already exists.

Where are the TypeScript types for the API responses? I want
to add a new field to the User type.

How are background jobs or scheduled tasks handled? I need to
add a nightly cleanup job.

A productive pattern is to discover first, then work with the files you found:

# First: discover (Ask mode works well here)
Where is payment processing implemented?

# The agent answers: "Mainly in src/services/PaymentService.ts
# and src/api/webhooks/stripe.ts"

# Then: work with the specific files (Agent mode)
@src/services/PaymentService.ts Add support for Apple Pay. The
current code handles cards via Stripe. Follow the same pattern.

Getting Oriented in an Unfamiliar Codebase

When you join a new team or open an open-source project, start broad and narrow down.

Start with an overview:

Give me a high-level overview of this project: what it does,
the tech stack, and the main architectural decisions.

Then drill into the areas you need:

How does the multi-tenancy system work? How does the app know
which tenant a user belongs to?

How are permissions and roles handled? Where is the
authorization logic?

Then focus on where you will work:

I'll be working on the reporting feature. Which files are
involved, and which external services does it depend on?

Going from broad to narrow lets you build a mental model of a codebase in an hour rather than a week.

Limits of Codebase Search

Codebase search is powerful but not perfect.

Search Can Miss Things

Semantic search finds code with a similar meaning, but it can still miss relevant files, especially when the project uses unusual names.

Workaround: Rephrase with different terms, name the exact function or file if you know it, or mention the files you suspect with @.

The Answer May Rest on a Few Files

The agent reads what its searches surface. If it misses a key file, the answer can be confidently incomplete.

Workaround: Ask "Which files did you base this on?" and check them. If one is missing, mention it and ask again.

New or Moved Files May Lag Behind

Cursor keeps the index updated as you work, but right after a large merge, a code generation step, or a big reorganization, the index can briefly be behind.

Workaround: Mention new files directly, or trigger a re-index from settings after very large changes.

Very Large Repositories

In very large monorepos, indexing takes longer and search has more noise to sift through. Point the agent at the right area ("Look only in apps/billing/") to keep answers focused.

Combining Questions with @ Mentions

You can mix both approaches in one message. Mention the files you know, and let the agent search for the rest:

@src/services/OrderService.ts This is the entry point for order
processing. Find all the downstream services it calls and explain
the full flow.

@types/api.ts I want to add a new endpoint. Find a similar
existing endpoint I can model mine on, and keep the response
type consistent with this file.

This gives the agent a strong starting point plus the freedom to discover the rest.

Key Takeaways

• The old @codebase mention is gone. Just ask: the agent searches your project on its own.
• Agent mode searches and can edit. Ask mode searches and explains without changing files.
• Semantic search runs over an index of embeddings, so it can find code by meaning, not just exact words.
• Phrase questions with a goal, use the project's own terms, and ask for file paths.
• Just ask when exploring; add @ mentions when you already know which files matter.
• Search can miss files. Ask which files an answer is based on, and mention missing ones.
• After very large changes, mention new files directly or re-index.