Cursor Codebase Indexing

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.

How Indexing Works

Your Code Files
      │
      ▼
  Syntax Chunking ─── splits files into meaningful code blocks
      │
      ▼
  Embedding Generation ─── converts chunks to vector representations
      │
      ▼
  Vector Storage (Turbopuffer) ─── cloud-hosted nearest-neighbor search
      │
      ▼
  @Codebase Query ─── your question → embedding → similarity search → relevant chunks

Key Architecture Details

• 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

1. Open your project in Cursor 2. Indexing starts automatically on first open 3. Check status: look at the bottom status bar for "Indexing..." indicator 4. 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

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:

1. Cmd+Shift+P > Cursor: Resync Index 2. Wait for status bar to show indexing progress 3. If that fails, delete the local cache:

• macOS: ~/Library/Application Support/Cursor/Cache/
• Linux: ~/.config/Cursor/Cache/
• Windows: %APPDATA%\Cursor\Cache\

4. Restart Cursor and allow full re-index

File Watcher Limits (Linux)

On Linux, large projects may hit the file watcher limit:

# Check current limit
cat /proc/sys/fs/inotify/max_user_watches

# Increase (temporary)
sudo sysctl fs.inotify.max_user_watches=524288

# Increase (permanent)
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Enterprise Considerations

• Data residency: Embeddings are stored in Turbopuffer (cloud). Obfuscated filenames and no plaintext code, but metadata exists
• Privacy Mode: With Privacy Mode on, embeddings are computed with zero data retention at the provider
• Air-gapped environments: Indexing requires network access to Cursor's embedding API. Not available offline
• Indexing scope: Only files in the currently open workspace are indexed. Closing a project removes its index from active queries

Troubleshooting

Resources

• Codebase Indexing Docs
• Ignore Files
• Secure Codebase Indexing

Configuration

Configuration

.cursorignore File

# .cursorignore - at project root

# Dependencies (large, not your code)
node_modules/
vendor/
.venv/
__pycache__/
*.pyc

# Build outputs (generated)
dist/
build/
out/
.next/
.nuxt/
target/

# Version control
.git/

# Large data files
*.csv
*.json  # Be selective - config jsons may be useful
*.sql
*.sqlite
*.db

# Logs
*.log
logs/

# Assets (binary)
*.png
*.jpg
*.gif
*.ico
*.woff
*.ttf

# IDE/Editor
.idea/
.vscode/
*.swp
*.swo

# OS files
.DS_Store
Thumbs.db

# Test fixtures (if large)
test/fixtures/
__fixtures__/

Selective Indexing

# Index only specific directories
*
!src/
!lib/
!app/

# Include configs
!*.config.js
!*.config.ts
!package.json
!tsconfig.json

Error Handling Reference

--- [Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)

Examples

Example: Setting Up for a Node.js Project Request: "Configure codebase indexing for my Node.js project" Result: Creates .cursorignore excluding node_modules, dist, and build directories; enables indexed search

Example: Monorepo Selective Indexing Request: "Only index the frontend package in my monorepo" Result: Configures exclusions for all packages except frontend, reduces index time and improves relevance

--- [Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)

Index Settings

Index Settings

Performance Settings

// settings.json
{
  // Maximum file size to index (bytes)
  "cursor.index.maxFileSize": 1048576,  // 1MB

  // Number of indexing workers
  "cursor.index.workers": 4,

  // Index on save
  "cursor.index.indexOnSave": true,

  // Background indexing
  "cursor.index.backgroundIndexing": true
}

Language-Specific Settings

{
  // Include/exclude by language
  "cursor.index.includeLanguages": [
    "typescript",
    "javascript",
    "python",
    "go",
    "rust"
  ],

  // Exclude specific patterns
  "cursor.index.excludePatterns": [
    "**/*.min.js",
    "**/*.generated.ts",
    "**/migrations/*.sql"
  ]
}

Maintaining The Index

Maintaining the Index

Manual Operations

Reindex entire codebase:
Cmd+Shift+P > "Cursor: Reindex Codebase"

Refresh index (incremental):
Cmd+Shift+P > "Cursor: Refresh Index"

Clear index:
Cmd+Shift+P > "Cursor: Clear Index"

Auto-Update Triggers

Index updates automatically when:
- Files are saved
- Files are created/deleted
- Git operations complete
- Workspace is opened

Index Health Check

# Check index status
Cursor status bar shows:
- "Indexing..." - In progress
- "Indexed" - Complete
- "Index Error" - Problem

# Check index size
ls -la ~/.cursor/index/

# Verify index works
@codebase find main function

Optimization For Large Projects

Optimization for Large Projects

Monorepo Strategy

Option 1: Open specific package
cd monorepo/packages/my-package
cursor .

Option 2: Selective .cursorignore
# .cursorignore
packages/*/node_modules/
packages/*/dist/
# Only index active packages
!packages/frontend/
!packages/shared/

Performance Tuning

{
  // Reduce workers for slower machines
  "cursor.index.workers": 2,

  // Increase for faster machines
  "cursor.index.workers": 8,

  // Limit concurrent file processing
  "cursor.index.maxConcurrentFiles": 50
}

Incremental Indexing

For very large codebases:
1. Start with essential directories only
2. Add more as needed
3. Use .cursorignore aggressively
4. Consider workspace subsets

Troubleshooting

Troubleshooting

Index Not Updating

Symptoms: Changes not reflected in @codebase

Fixes:
1. Wait for save to trigger update
2. Manual refresh: "Cursor: Refresh Index"
3. Check file isn't in .cursorignore
4. Verify file type is supported

Search Returns Nothing

Symptoms: @codebase queries return empty

Fixes:
1. Verify indexing completed
2. Check file isn't excluded
3. Try simpler query
4. Reindex if corrupt

High Resource Usage

Symptoms: CPU/memory spike during indexing

Fixes:
1. Reduce worker count
2. Add more exclusions
3. Index during off-hours
4. Use smaller workspace

Using The Index

Using the Index

@codebase Queries

Find definitions:
"@codebase where is the User class defined?"
"@codebase find all authentication-related functions"

Understand architecture:
"@codebase how is the database connection handled?"
"@codebase what are the main API routes?"

Find usage:
"@codebase where is handleLogin called?"
"@codebase show examples of using the cache"

Effective Search Patterns

Specific:
"@codebase find the validateEmail function"
"@codebase show ProductService class methods"

Semantic:
"@codebase how do we handle authentication?"
"@codebase what's the error handling pattern?"

Exploratory:
"@codebase summarize the main modules"
"@codebase list all API endpoints"