Build the index your search needs.

Start from the project root

lean-ctx index status

Inspect the project and index state before rebuilding. Use --root when targeting another directory. Run from the same environment as the agent: Windows and a WSL distribution do not automatically share executable paths, configuration or indexes.

Choose the index

Command	Purpose	Effect
lean-ctx index build	Prepare lexical (BM25) and graph indexes	Builds local index data; larger projects need time and disk space.
lean-ctx index build-graph	Prepare the property graph used for structural analysis	Builds graph relationships from extracted symbols and files.
lean-ctx index build-semantic	Prepare dense retrieval	Builds BM25 first if needed, then attempts the configured embedding path.
lean-ctx index build-full	Rebuild all indexes from current source	Removes existing index artifacts and rebuilds; not a routine first diagnostic step.
lean-ctx index watch	Keep index state updated while working	Runs a watcher until stopped.

Semantic retrieval requires a functioning embedding runtime and model. A failed semantic build does not mean a regex search is unavailable. Read the reported state and error; do not assume a command’s completion means every index is ready.

Bound the corpus

lean-ctx index build --exclude "**/generated/**"
lean-ctx index build-semantic --include "**/*.ts"

The quoted glob reaches LeanCTX unchanged in PowerShell, Bash and zsh. --include and --exclude are repeatable, apply to the current indexing run, and do not grant file-access permission. Ignore rules are respected by default. Persist recurring choices through the corresponding index configuration instead of relying on one terminal invocation.

Keep generated dependencies and unrelated repositories outside the corpus. Review performance limits before increasing file, memory or thread limits.

Distinguish embeddings from a local model

lean-ctx embeddings is a version-sensitive compatibility command. The captured 3.10.2 help advertises provisioning, but the reviewed checkout’s handler explicitly reports it unavailable and points to a locally installed ONNX Runtime through ORT_DYLIB_PATH. It is not a universal install recipe.

lean-ctx model status concerns managed local models, including the optional triage model. Installing a triage model is not the same operation as building a semantic index. Verify the installed build’s model/runtime requirements before downloading or configuring either.

Verify retrieval

1. Check lean-ctx index status after a build.
2. Search for a known symbol or distinctive source phrase.
3. Compare semantic results with an exact regex search when ranking surprises you.
4. Open the returned source to verify relevance before passing it to the model.

For tool inputs and examples, see Search & code intelligence. Static graphs and embeddings are navigation aids, not a complete description of runtime behavior.

Sources & versions4 references · Reviewed 18 Sept 2026

• index_cmd.rsrust/src/cli/index_cmd.rsReviewed checkout
• embeddings_cmd.rsrust/src/cli/embeddings_cmd.rsReviewed checkout
• model_cmd.rsrust/src/cli/model_cmd.rsReviewed checkout
• index_orchestrator.rsrust/src/core/index_orchestrator.rsReviewed checkout

Core checkout

5198ea1867

Installed runtime

3.10.2

SDK release

1.1.0

Separate baselines for source, CLI/configuration and SDK contracts. Review does not certify every platform or integration.

Versions & compatibility