code_index

Automatic semantic code index for Agent Zero projects, and the code_search tool.

What it does

• Automatic project indexing: every git repository detected in the active Agent Zero project folder gets its own index (a project with no repos indexes the whole project folder). Indexes start on boot (staggered per project), refresh incrementally on file changes, and recover automatically on search when stale.
• code_search tool: natural-language and symbol search across every indexed repository of the active project — hybrid retrieval (embeddings
  • tree-sitter symbols + BM25-style lexical) with reranking. Pass repository to narrow to one repo; omit it to search all of them.
• Zero embedding configuration: embeddings use the embedding model configured in Agent Zero model settings (the same one used elsewhere); changing the model triggers a re-index automatically.

Worktrees and other nested checkouts are skipped during discovery. Index data defaults to usr/.local/share/agent-zero/code-indexes/, resolved through Agent Zero's framework path helper so it remains inside the standard persistent volume. Set AGENT_HOME only when a deployment intentionally presents usr through another stable path. Additional disposable-checkout directory names can be excluded with the path-separated A0_CODE_INDEX_SKIP_PATH_MARKERS environment variable.

Settings

None. Indexing follows project activation automatically.

Requirements

See requirements.txt (tree-sitter, watchdog, pathspec).

The Plugin Hub lifecycle hooks install these packages into Agent Zero's framework environment. A startup hook also repairs them after a stock container replacement, because /opt/venv-a0 is not part of the persistent usr volume. No custom Dockerfile is required; the first start on a fresh image needs package-network access and may take longer while uv or pip installs the packages. Install this directory as /a0/usr/plugins/code_index/, enable it, and restart the UI.

Removal

Disable or remove the plugin to stop indexing and hide code_search. The uninstall hook keeps shared Python dependencies and index data. Remove usr/.local/share/agent-zero/code-indexes/ manually after confirming the indexes are no longer useful.