Set up and optimize Cursor codebase indexing for semantic code search and @Codebase queries.
Triggers on "cursor index", "codebase indexing", "index codebase", "cursor semantic search",
"@codebase", "cursor embeddings".
Set up and optimize Cursor codebase indexing for semantic code search and @Codebase queries.
Triggers on "cursor index", "codebase indexing", "index codebase", "cursor semantic search",
"@codebase", "cursor embeddings".
allowed-tools
Read, Write, Edit, Bash(cmd:*)
version
1.18.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
["saas","cursor","cursor-codebase"]
compatibility
Designed for Claude Code, also compatible with Codex and OpenClaw
Cursor Codebase Indexing
Set up and optimize Cursor's codebase indexing system. Indexing creates embeddings of your code, enabling @Codebase semantic search and improving AI context awareness across Chat, Composer, and Agent mode.
Merkle tree for change detection: only modified files are re-indexed (every 10 minutes)
No plaintext storage: code is not stored server-side; only embeddings and obfuscated metadata
Privacy Mode compatible: with Privacy Mode on, embeddings are computed without retaining source code
Indexing runs in the background; small projects complete in seconds, large projects (50K+ files) may take hours initially
Initial Setup
Open your project in Cursor
Indexing starts automatically on first open
Check status: look at the bottom status bar for "Indexing..." indicator
View indexed files: Cursor Settings > Features > Codebase Indexing > View included files
Verify Indexing Status
The status bar shows:
"Indexing..." with progress indicator -- initial indexing in progress
"Indexed" -- indexing complete, @Codebase queries are available
No indicator -- indexing may be disabled or not started
Configuration
.cursorignore
Exclude files from indexing and AI features. Place in project root. Uses .gitignore syntax:
# .cursorignore
# Build artifacts (large, not useful for AI context)
dist/
build/
out/
.next/
target/
# Dependencies
node_modules/
vendor/
venv/
.venv/
# Generated files
*.min.js
*.min.css
*.bundle.js
*.map
*.lock
# Large data files
*.csv
*.sql
*.sqlite
*.parquet
fixtures/
seed-data/
# Secrets (defense in depth -- also use .gitignore)
.env*
**/secrets/
**/credentials/
.cursorindexingignore
Exclude files from indexing only but keep them accessible to AI features when explicitly referenced:
# .cursorindexingignore
# Large test fixtures -- don't index, but allow @Files reference
tests/fixtures/
e2e/recordings/
# Documentation build output
docs/.vitepress/dist/
Difference:.cursorignore hides files from both indexing and AI features. .cursorindexingignore only excludes from the index; files can still be referenced via @Files.
Default Exclusions
Cursor automatically excludes everything in .gitignore. You only need .cursorignore for files tracked by git that you want to exclude from AI.
Using the Index
@Codebase Queries
Ask semantic questions about your entire codebase:
@Codebase where is user authentication handled?
@Codebase show me all API endpoints that accept file uploads
@Codebase how does the payment processing flow work?
@Codebase find all places where we connect to Redis
@Codebase performs a nearest-neighbor search using your question's embedding. It returns the most semantically similar code chunks, even if they do not contain the exact keywords you used.
@Codebase vs @Files vs Text Search
Method
When to Use
Context Cost
@Codebase
Discovery -- you don't know which files
High (many chunks)
@Files
You know exactly which file
Low (one file)
@Folders
You know the directory
Medium-High
Ctrl+Shift+F
Exact text/regex match
N/A (editor search)
Use @Codebase for discovery, then switch to @Files once you know where the code lives.
Optimization for Large Projects
Monorepo Strategy
For monorepos with many packages, open the specific package directory instead of the root:
# Instead of opening the entire monorepo:
cursor /path/to/monorepo # Indexes everything -- slow# Open the specific package:
cursor /path/to/monorepo/packages/api # Indexes only this package -- fast
Or use .cursorignore at the root to exclude packages you are not actively working on:
# .cursorignore -- monorepo, focus on api and shared
packages/web/
packages/mobile/
packages/admin/
# packages/api/ ← not listed, so it IS indexed
# packages/shared/ ← not listed, so it IS indexed
Re-Indexing
If search results are stale or indexing appears stuck:
