Index & embed first

Do this before anything else

Every intelligence and governance command — query, search, map, similar, check, score, hotspots, duplicates, smart — reads a prebuilt index. Run ctx index once before you use them. Semantic features (semantic, smart, similar) additionally need ctx embed.

1. Build the index

ctx index

This parses your code with tree-sitter and writes a single SQLite file at .ctx/codebase.sqlite — every symbol, call/import/inheritance edge, and complexity metric. Re-running is incremental: it only re-parses files that changed.

Flag	What it does
-w, --watch	Keep running and reindex automatically as files change
-j, --parallel	Parse in parallel across CPU cores (faster on large repos)
--force	Full rebuild — clears the database and re-parses everything
-p, --pattern <GLOB>	Only index matching files (repeatable)
-i, --ignore <GLOB>	Extra ignore patterns (repeatable)
-v, --verbose	Print each file as it's indexed

ctx index -j                       # parallel parse
ctx index --force                  # rebuild from scratch after big changes
ctx index -p "src/**/*.rs"         # index only Rust sources

2. Generate embeddings (for semantic search)

ctx embed

semantic, smart, and similar rank code by meaning, which needs vector embeddings. The first run downloads a local model (~90 MB) and embeds every indexed symbol; later runs only embed what's new. It runs fully locally — no API key required.

Flag	What it does
-w, --watch	Auto-embed new symbols as the index changes
--force	Re-embed every symbol from scratch
--batch-size <N>	Symbols per batch (default 50)
--openai	Use the OpenAI API instead of the local model (needs OPENAI_API_KEY)

Run them as background watchers

For an always-fresh model while you (or your agent) work, run the watchers in the background — the index and embeddings stay current without you re-running anything:

ctx index --watch &     # reindex on every file change
ctx embed --watch &     # embed new symbols as they're indexed

Run these in a spare terminal or as background jobs. The index --watch process debounces rapid edits; embed --watch reacts to index updates. Stop them with kill %1 %2 (or close the terminal).

With an AI agent, let the harness do it

ctx harness init --target claude wires indexing straight into Claude Code: it reindexes on every Edit/Write via a PostToolUse hook, so the agent is always working against a current model. See Using ctx with agents.

What needs what

You want to run	Requires
query, search, map, check, score, hotspots, duplicates, graph	ctx index
semantic, smart, similar	ctx index + ctx embed
context generation (bare ctx, ctx diff)	nothing — works without an index

Next steps

• Code intelligence — querying the index you just built.
• Using ctx with agents — the full index → embed → govern loop.