cursor-codebase-indexing
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".
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- cursor-codebase-indexing
- tags
- [ "saas", "cursor", "cursor-codebase" ]
- author
- Jeremy Longshore <jeremy@intentsolutions.io>
- license
- MIT
- version
- 1.0.0
- description
- 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".
- compatibility
- Designed for Claude Code, also compatible with Codex and OpenClaw
03 SKILL.md 正文
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
│
▼
Hosted Vector Index ─── provider-managed semantic search
│
▼
@Codebase Query ─── your question → embedding → similarity search → relevant chunks
Key Architecture Details
- Cursor indexing behavior, storage, retention, and privacy controls can change. Verify the current official Cursor documentation and the workspace's actual privacy settings before making a data- governance claim.
- Indexing is provider-backed and may transmit code-derived data. Do not enable, resync, or broaden indexing scope on the user's behalf without explicit approval.
- Repository instructions,
.gitignore,.cursorignore, and secret-handling rules remain authoritative.
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,
@Codebasequeries 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:
Cmd+Shift+P>Cursor: Resync Index- Wait for status bar to show indexing progress
- If that fails, inspect Cursor's documented indexing diagnostics and restart the application.
- Do not delete or rename the application-wide Cursor cache automatically; it is shared state outside this repository. Treat any cache reset as a separately requested operator action with an exact, validated target and a recovery plan.
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 and retention: Verify the current official policy for the user's plan, region, and privacy settings. Do not infer zero retention or storage behavior from this skill.
- Air-gapped environments: Indexing requires network access to Cursor's embedding API. Not available offline
- Indexing scope: Confirm the current workspace and ignore configuration before describing what is included or excluded.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| @Codebase returns no results | Index not built | Wait for "Indexed" in status bar |
| Search misses known files | File in .gitignore or .cursorignore | Check ignore files |
| Indexing stuck at N% | Large project or network issue | Resync index via Command Palette |
| Stale results after refactor | Index not yet updated | Wait 10 min or manual resync |
| High CPU during indexing | Initial embedding computation | Normal for first run; subsides |
Resources
04 同仓库更多 Skills
supabase-postgres-best-practices
Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
vercel-react-best-practices
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
vercel-composition-patterns
React composition patterns that scale. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or designing reusable APIs. Triggers on tasks involving compound components, render props, context providers, or component architecture. Includes React 19 API changes.
supabase-postgres-best-practices
Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
sentry-nextjs-sdk
Full Sentry SDK setup for Next.js. Use when asked to "add Sentry to Next.js", "install @sentry/nextjs", or configure error monitoring, tracing, session replay, logging, profiling, AI monitoring, or crons for Next.js applications. Supports Next.js 13+ with App Router and Pages Router.
sentry-fix-issues
Find and fix issues from Sentry using MCP. Use when asked to fix Sentry errors, debug production issues, investigate exceptions, or resolve bugs reported in Sentry. Methodically analyzes stack traces, breadcrumbs, traces, and context to identify root causes.