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.

Long semantic builds

Embedding a large project on a CPU can take hours. From 3.11.1, build-semantic runs until it finishes, saves finished files at least once a minute and when it stops on an error, Ctrl-C or a memory limit. Run the same command again to resume where it stopped; unchanged files are not embedded twice. lean-ctx index status and lean-ctx doctor report an interrupted build as partial with the number of embedded chunks. The MCP action ctx_index build-semantic starts the build in the background and returns at once; check progress with ctx_index status. Only one process builds a project’s semantic index at a time.

In 3.11.0 the CLI stopped waiting after 10 minutes and the process exited before anything was saved, so a long build never completed. Update, or use a GPU runtime, if build-semantic reaches 100% but the index stays not built.

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.

Check the embedding runtime and model

lean-ctx embeddings status

Semantic indexing needs an ONNX Runtime library on the machine; LeanCTX does not install one. It finds onnxruntime in active virtual or conda environments, the usual Python installations (on Windows also every python.exe on PATH, %ProgramFiles%\Python3*, the Python install manager’s %LOCALAPPDATA%\Python\pythoncore-* and the Microsoft Store Python), or the file or directory named by ORT_DYLIB_PATH. pip install onnxruntime is enough for the CPU. The status shows which runtime was found, the execution provider policy, the GPU state and the embedding model.

Choose the embedding model

The status line under Embedding model: says which setting chose it. In order of precedence:

1. LEAN_CTX_EMBEDDING_MODEL in the environment. A value set in an MCP config env block applies only to the MCP server, not to your terminal.
2. [embedding] model in the global config.toml whose path the status prints, for example model = "minilm".
3. The default, minilm (all-MiniLM-L6-v2). nomic selects nomic-embed-text-v1.5; hf:org/repo@revision selects a custom model.

A model change takes effect at the next lean-ctx index build-semantic, which then rebuilds the semantic index from scratch; vectors of different models are never mixed.

Use an NVIDIA GPU

On x86_64 Linux (glibc) and x86_64 Windows:

lean-ctx enable-gpu
pip install "onnxruntime-gpu[cuda,cudnn]"
lean-ctx embeddings status

enable-gpu installs the CUDA build of LeanCTX for the running release; on that build it reports that nothing needs installing, and --force reinstalls it. Install onnxruntime-gpu in the same Python that provides the runtime, and uninstall the CPU package onnxruntime there first. The [cuda,cudnn] extras install the CUDA and cuDNN libraries that match that onnxruntime-gpu (CUDA 13 since 1.27 on PyPI, CUDA 12 before); LeanCTX reads which CUDA major the runtime was built for and preloads the matching libraries, so PATH stays unchanged. A CUDA Toolkit works as well if its major version matches; DLL names differ between majors (cudart64_12.dll vs cudart64_13.dll), so a toolkit of the other major does not help.

CUDA runtime: OK means the CUDA runtime and cuDNN load, so embeddings run on the GPU. Otherwise the status names the missing libraries, lists the searched directories on Windows and says whether the NVIDIA driver is missing; indexing then continues on the CPU. Set LEAN_CTX_ORT_EXECUTION_PROVIDER=cpu to stay on the CPU without the warning.

Up to 3.11.2 on Windows, a second lean-ctx update or lean-ctx enable-gpu stops with stale Windows rollback binary exists, and the CUDA 13 libraries of onnxruntime-gpu 1.27 or later are not found. For the first, run lean-ctx stop, delete the lean-ctx.old.exe named in the error and run the command again; both are fixed in the next release.

Distinguish embeddings from a local model

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 & versions7 references · Reviewed 10 Oct 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
• model_registry.rsrust/src/core/embeddings/model_registry.rsReviewed checkout
• ort_execution_providers.rsrust/src/core/ort_execution_providers.rsReviewed checkout
• platform.rsrust/src/core/updater/platform.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