Codebase-Wide Chat with @codebase

When you need to ask a question that 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 do not want to guess which file to reference. You want to ask the whole codebase.

That is what @codebase does. Instead of you specifying which files are relevant, Cursor searches your indexed project, identifies the most relevant code, and includes it automatically. It is the closest thing to having an AI assistant that has actually read your entire repository.

What You'll Learn

• What @codebase does and how it differs from other context mentions
• How Cursor's codebase indexing works
• When to use @codebase versus targeted @Files or @Code mentions
• Asking architectural questions with @codebase
• Finding where things are implemented across a large project
• Understanding unfamiliar codebases quickly
• Limitations of @codebase and when it falls short
• How to re-index after major changes

What @codebase Actually Does

When you type @codebase in a chat message, Cursor does not dump your entire project into the prompt. Instead, it performs a semantic search over a pre-built index of your codebase, retrieves the most relevant code snippets, and injects those into the context. The retrieval is driven by the content of your question — Cursor figures out what to look for based on what you asked.

This is different from all the other @-mentions:

Mention	How context is gathered
@Files	You specify the file; Cursor reads it in full
@Folders	You specify the directory; Cursor reads its contents
@Code	You specify the symbol; Cursor extracts it
@codebase	Cursor searches the index; it decides what is relevant

The practical implication: @codebase is best for discovery and exploration, while targeted mentions are best when you already know what is relevant.

How Codebase Indexing Works

Before @codebase can search your project, Cursor needs to build an index. Here is what happens under the hood:

1. File scanning: Cursor reads all files in your project directory, respecting .gitignore and its own ignore patterns. Binary files, lock files, and other non-code files are typically excluded.
2. Chunking: Each file is split into overlapping chunks of code.
3. Embedding: Each chunk is converted into a vector embedding — a numerical representation that captures semantic meaning.
4. Storage: The embeddings are stored locally (on your machine) in a vector database.

When you use @codebase, Cursor converts your question into an embedding and finds the chunks whose embeddings are most similar — a process called semantic search or vector similarity search.

Checking Index Status

You can see the indexing status in Cursor Settings → Features → Codebase Indexing. The panel shows:

• Whether indexing is complete or in progress
• How many files have been indexed
• A button to force a re-index

A freshly opened project will start indexing automatically. Large projects may take a few minutes on the first index.

What Gets Excluded

Cursor's indexer respects .gitignore by default. It also has its own exclusion patterns for things like node_modules, build output directories, and binary assets. You can add custom exclusion patterns in the settings if there are large generated files that should not be indexed.

When to Use @codebase vs. @Files

The key distinction is whether you know where to look.

Use @codebase when:

• You do not know which files are relevant to your question
• Your question is architectural or spans many parts of the project
• You are exploring an unfamiliar codebase
• You want to find every place something is implemented, called, or configured
• You want to understand patterns and conventions that appear throughout the project

Use @Files (or @Code) when:

• You know exactly which file or function is relevant
• You want to make a specific change to a specific file
• You are asking a focused question about a particular piece of code
• You need the AI to see the complete contents of a file (not just the relevant chunks)

A common workflow: use @codebase to discover where something is, then switch to @Files once you know which files to reference.

# First: discover
@codebase Where is payment processing implemented?

# Cursor responds: "It's primarily in src/services/PaymentService.ts
# and src/api/webhooks/stripe.ts"

# Then: work with the specific files
@src/services/PaymentService.ts Add support for Apple Pay. The
current implementation handles cards via Stripe. Follow the
same pattern for the new payment method.

Asking Architectural Questions

@codebase shines for architectural questions — questions about how the whole system is organized, not just how one function works.

Understanding the Overall Structure

@codebase How is this application organized? What are the main
layers and how do they interact?

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

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

Understanding Design Patterns

@codebase What pattern is used for state management? Is it
context, Redux, Zustand, or something else?

@codebase How does this codebase handle errors? Is there a
centralized error handler or are errors handled per-module?

@codebase What testing approach does this project use? Are
there unit tests, integration tests, or end-to-end tests?
Where are they located?

Understanding Data Flow

@codebase How does data flow from the API response to the
rendered UI for the products listing page?

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

These questions require the AI to read and synthesize information from many files simultaneously — exactly what @codebase is designed for.

Finding Where Things Are Implemented

One of the most practical uses of @codebase is finding where specific functionality lives, especially in a large or unfamiliar project.

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

@codebase Where are environment variables validated or
documented? I want to add a new required variable.

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

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

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

In each case, you do not know the answer before asking. @codebase searches for you and surfaces the relevant code.

Understanding Unfamiliar Codebases

When you join a new team or open an open-source project for the first time, @codebase is your fastest path to orientation.

A Getting-Started Workflow

Start with a broad overview:

@codebase 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 to understand:

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

@codebase What is the deployment setup? How does a change get
from a PR to production?

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

Then investigate the area you will be working in:

@codebase I'll be working on the reporting feature. What files
are involved, and what external services does it depend on?

This approach — broad to narrow, discovery to specifics — lets you build a mental model of a codebase in an hour rather than a week.

Limitations of @codebase

@codebase is powerful but not infallible. Understanding its limitations helps you know when to reach for alternative approaches.

Retrieval is Not Always Perfect

The semantic search finds chunks that are semantically similar to your query, but it can miss relevant code if the terminology in your question does not match the terminology in the code. For example, if you ask about "logging" and the codebase uses "telemetry", the search might not surface the relevant files.

Workaround: Try rephrasing with different terminology, or use @Files once you have a hypothesis about which files matter.

The AI Only Sees Chunks, Not Whole Files

@codebase injects snippets — it does not inject entire files. If understanding something requires reading a complete file from top to bottom, the chunked retrieval may miss nuance. For example, if the answer to your question depends on imports at the top of a file and a function 400 lines later, the chunks may not be retrieved together.

Workaround: Once @codebase tells you which files are relevant, follow up with @Files to read them in full.

Very New Files May Not Be Indexed

If you added files recently and have not re-indexed, those files will not appear in @codebase search results.

Workaround: Use @Files for files you know are new, or trigger a re-index.

Large Monorepos Can Have Gaps

In very large projects, Cursor may only index a portion of the codebase due to size constraints. Check the indexing panel to see what percentage of files are covered.

Re-Indexing After Major Changes

Cursor indexes your codebase automatically in the background as you work. In most cases, you do not need to think about it. However, there are situations where triggering a manual re-index helps:

• After a large merge that added or moved many files
• After running a code generation step that creates many new files
• After refactoring that changed file names and locations significantly
• After pulling a branch you have not worked on in a while

To re-index: Cursor Settings → Features → Codebase Indexing → Re-index.

The re-index runs in the background and does not interrupt your work. You can check progress in the same settings panel.

When @codebase Gives Stale Answers

If @codebase seems to be giving answers about code that you recently changed or deleted, it may be working from a stale index. A re-index will resolve this. In the meantime, use @Files to reference the current state of specific files directly.

Combining @codebase with Other Mentions

@codebase and targeted @-mentions can be used together in the same message:

@codebase @src/services/OrderService.ts I know the order
service is the entry point for order processing. Use the
codebase search to find all the downstream services it
calls, and then help me understand the full flow.

@codebase @types/api.ts I want to add a new endpoint. Use
the codebase to find a similar existing endpoint I can
model mine after, and reference the types file so the
response type is consistent.

This pattern combines @codebase's discovery strengths with the precision of targeted mentions.

Key Takeaways

• @codebase performs a semantic search over your indexed project and retrieves the most relevant code chunks automatically — you do not specify which files to look in.
• Cursor builds the index by embedding code chunks as vectors; search works by finding chunks semantically similar to your question.
• Use @codebase for discovery, architectural questions, and exploring unfamiliar projects. Use @Files and @Code when you know exactly what is relevant.
• A productive pattern is to use @codebase to find which files matter, then switch to @Files to work with those files in full.
• @codebase has limitations: retrieval is not perfect, it works with chunks not full files, and newly added files may not yet be indexed.
• Re-index manually after large merges, file renames, or code generation steps to keep search results fresh.
• @codebase and targeted @-mentions can be combined in the same message for maximum effectiveness.