Code Index

Source Code: src/gaia/code_index/ and src/gaia/agents/code_index/tools/mixin.py

Looking for the API? See the Code Index SDK Reference for CodeIndexSDK, CodeIndexConfig, and CodeIndexToolsMixin.

GAIA’s Code Index gives you fast semantic search over a repository without sending source to the cloud. It parses files into symbol-level chunks, embeds them via Lemonade Server on AMD NPU/GPU hardware, and stores them in a local FAISS index for sub-second queries. The index is exposed two ways:

Tool mixin — CodeIndexToolsMixin powers the flagship GAIA agent’s coding skill and is available to any custom agent that opts in via KNOWN_TOOLS["code_index"].
Python SDK — CodeIndexSDK for direct programmatic use.

gh is not required — the index covers source files only.

Overview

Aspect	Details
Languages parsed	Python (AST), JavaScript, TypeScript, Go, Rust, Java, C, C++
Embeddings	Local AMD NPU/GPU via Lemonade Server (`user.embeddinggemma-300m-GGUF` — EmbeddingGemma 300M, 768-dim — by default)
Vector store	FAISS `IndexFlatL2`
Cache	`~/.gaia/code_index/<repo-hash>/` (atomic writes; incremental on file-hash)
Privacy	All processing local; sensitive files (`.env`, `.pem`, `.key`, …) auto-excluded

Setup

Install the [rag] extras (FAISS + numpy live there):

uv pip install -e '.[rag]'

Embeddings are generated locally by Lemonade. If you haven’t installed it yet, gaia init installs the server and pulls the model — gaia daemon starts and supervises it from there.

The embedder is user.embeddinggemma-300m-GGUF (EmbeddingGemma 300M). A cached index (under ~/.gaia/code_index/) records the model it was built with, so an index built before v0.22.0 with nomic-embed-text-v2-moe-GGUF fails loudly with a model-mismatch error naming both models. Re-index to rebuild it with EmbeddingGemma.

If FAISS or numpy are missing at runtime you’ll see exactly:

code_index dependencies missing. Install with: pip install -e '.[rag]'

Using it from the flagship agent

The coding skill is what puts the code index in front of the flagship GAIA agent — it lists search_code_index among the tools a coding task needs, and directs the agent to run index_codebase once per repo before relying on semantic search. Ask the agent to work on a codebase and it calls these tools autonomously:

Tool	Description
`index_codebase`	Build / refresh the FAISS index
`search_code_index`	Semantic search over indexed chunks
`get_index_status`	Report current index state
`clear_code_index`	Remove the cached index

You don’t have to call index_codebase first: the first search_code_index in a repository with no index builds it, then searches. That first search is slow on a large repository; a task that never searches never pays for the embedding pass. Set GAIA_PROJECT_MAP_AUTO_INDEX=1 to build it in the background at task start instead.

Example interaction

User: Find all the places we handle authentication errors.

Agent: [calls search_code_index with query="authentication error handling"]

Results:
- src/gaia/agents/base/agent.py:145 — handle_error()
- src/gaia/llm/lemonade_client.py:89 — auth retry logic
- tests/unit/test_auth.py:23 — test_auth_error_recovery

Custom agents compose CodeIndexToolsMixin directly in their class declaration; it’s also registered in KNOWN_TOOLS["code_index"] (src/gaia/agents/registry.py) for dynamic resolution. For SDK-level composition see the SDK reference.

Using it from Python

For direct programmatic use (no agent), call CodeIndexSDK yourself:

from gaia.code_index.sdk import CodeIndexConfig, CodeIndexSDK

config = CodeIndexConfig(repo_path="/path/to/repo", max_files=2000)
sdk = CodeIndexSDK(config)

# Build / refresh the index — incremental: unchanged files (matched by
# SHA-256) reuse their existing embeddings
result = sdk.index_repository()
print(f"Files: {result.files_indexed}, Chunks: {result.chunks_created}")

# Semantic search
for r in sdk.search("how does the agent handle errors", top_k=5):
    print(f"[{r.score:.3f}] {r.chunk.file_path}:{r.chunk.start_line}")

# Inspect and manage
print(sdk.get_status())
sdk.clear_index()

See the Code Index SDK Reference for the full CodeIndexConfig, CodeIndexSDK, and data-type reference.

Cache layout

~/.gaia/code_index/
└── <repo-hash>/
    ├── metadata.json    # version, embedding_model, file_hashes, chunk dicts
    └── index.faiss      # FAISS IndexFlatL2 vectors

Both files are written atomically (temp file + rename). The cache is keyed by the resolved repo path. If you switch embedding models the metadata mismatch is detected and search returns empty until you re-index.

Privacy

All processing is local. No source code is sent to external services. Sensitive filenames are skipped automatically: .env, .env.*, .htpasswd, SSH private keys (id_rsa, id_ed25519, …), and any *.pem, *.key, *.pfx, *.p12, *.jks, *.keystore.

Testing

The code-index stack has unit-test coverage in tests/unit/test_code_index*.py — 64 tests spanning the SDK (cache layout, incremental re-index, atomic writes), the parsers (Python AST + the regex backends for JS/TS/Go/Rust/Java/C/C++), and the CodeIndexToolsMixin tool surface. Run them with:

uv run python -m pytest tests/unit/test_code_index.py tests/unit/test_code_index_sdk.py tests/unit/test_code_index_mixin.py tests/unit/test_code_index_parsers.py -xvs

Retrieval-quality benchmarks (precision/recall against curated queries) are tracked under #868.

Real-world benchmark

Indexing the gaia repo itself against Lemonade Server’s user.embeddinggemma-300m-GGUF embedding model:

Metric	Value
Source files discovered	973
Semantic chunks indexed	23,974
Languages parsed	Python, JavaScript, TypeScript, Go, Rust, Java, C/C++
Embedding model	`user.embeddinggemma-300m-GGUF` (via Lemonade Server)
Wall-clock (remote, ngrok)	~51 min

from gaia.code_index.sdk import CodeIndexConfig, CodeIndexSDK

sdk = CodeIndexSDK(CodeIndexConfig(repo_path=".", embedding_model="user.embeddinggemma-300m-GGUF"))
sdk.index_repository()

The 51-minute figure is network-bound (embeddings sent to a remote Lemonade Server over an ngrok tunnel). On a local Ryzen AI setup the embedding step runs on the NPU and is substantially faster. For retrieval-quality metrics see #868.

Roadmap

#869 — MCP server wrapper, so external code assistants can drive the index.
#870 — Multi-repo indexing in a single namespace.
#871 — Verilog / VHDL parsers for hardware-design codebases.

Getting Started

C++ Framework

Python Framework

Overview

Setup

Using it from the flagship agent

Example interaction

Using it from Python

Cache layout

Privacy

Testing

Real-world benchmark

Roadmap

​Overview

​Setup

​Using it from the flagship agent

​Example interaction

​Using it from Python

​Cache layout

​Privacy

​Testing

​Real-world benchmark

​Roadmap

Overview

Setup

Using it from the flagship agent

Example interaction

Using it from Python

Cache layout

Privacy

Testing

Real-world benchmark

Roadmap