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 three ways:

CLI — gaia-code index ... for build, search, status, clear, and chat.
Tool mixin — CodeIndexToolsMixin is composed into the built-in CodeAgent and is available to any custom agent that opts in.
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]'

Start Lemonade Server so embeddings can be generated:

lemonade-server serve

The default embedder is now user.embeddinggemma-300m-GGUF (EmbeddingGemma 300M), replacing nomic-embed-text-v2-moe-GGUF because the current llama.cpp server cannot load the nomic MOE embedder. Both are 768-dim, so retrieval behavior is unchanged. A cached index (under ~/.gaia/code_index/) records the model it was built with: re-running gaia-code index rebuilds every embedding with the new model, and searching a stale index fails loudly with a model-mismatch error until you rebuild.

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

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

CLI usage

Build the index

# Index the current directory
gaia-code index

# Index a specific repository
gaia-code index --repo /path/to/repo

# Cap the file count (default 5000) and pick a different embedding model
gaia-code index --repo /path/to/repo --max-files 2000 --model user.embeddinggemma-300m-GGUF

Common index-level flags (apply to every subcommand):

Flag	Purpose
`--repo PATH`	Repository root (default: cwd)
`--max-files N`	Cap discovery (default 5000)
`--model M`	Lemonade embedding model
`--base-url URL`	Lemonade server URL (default `http://localhost:13305/api/v1`)
`--no-lemonade-check`	Skip the server reachability check
`--use-claude` / `--use-chatgpt`	Cloud LLM for `index chat` (embeddings still local)

Re-running gaia-code index is incremental: unchanged files (matched by SHA-256) reuse their existing embeddings.

Search

# Semantic search across the indexed chunks
gaia-code index search "how does the agent handle errors"

# Restrict to source code (the default `all` is currently equivalent;
# the flag is reserved for forward-compatible scope filtering)
gaia-code index search "auth flow" --scope code --top-k 5

# Larger result set
gaia-code index search "embedding model" --top-k 20

Example queries against a hypothetical service repo:

gaia-code index search "where do we mint JWT tokens"
gaia-code index search "rate limiter implementation"
gaia-code index search "database migration that adds the users table"

Inspect and manage

# Chunk counts, file count, embedding model, cache path
gaia-code index status

# Wipe the on-disk index for this repo (forces full re-index next run)
gaia-code index clear

Interactive Q&A

gaia-code index chat

This launches CodeAgent with the CodeIndexToolsMixin already wired in, so the agent can call index_codebase, search_code_index, get_index_status, and clear_code_index autonomously while answering your questions.

Agent integration

CodeAgent ships with the mixin already composed, so gaia-code chat sessions and any CodeAgent instance can call the four code-index tools:

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

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.

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

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

gaia-code index --repo . --model user.embeddinggemma-300m-GGUF

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

CLI usage

Build the index

Search

Inspect and manage

Interactive Q&A

Agent integration

Example interaction

Cache layout

Privacy

Testing

Real-world benchmark

Roadmap

​Overview

​Setup

​CLI usage

​Build the index

​Search

​Inspect and manage

​Interactive Q&A

​Agent integration

​Example interaction

​Cache layout

​Privacy

​Testing

​Real-world benchmark

​Roadmap

Overview

Setup

CLI usage

Build the index

Search

Inspect and manage

Interactive Q&A

Agent integration

Example interaction

Cache layout

Privacy

Testing

Real-world benchmark

Roadmap