Skip to main content

Documentation Index

Fetch the complete documentation index at: https://amd-gaia.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

AspectDetails
Languages parsedPython (AST), JavaScript, TypeScript, Go, Rust, Java, C, C++
EmbeddingsLocal AMD NPU/GPU via Lemonade Server (nomic-embed-text-v2-moe-GGUF by default)
Vector storeFAISS IndexFlatL2
Cache~/.gaia/code_index/<repo-hash>/ (atomic writes; incremental on file-hash)
PrivacyAll 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
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 nomic-embed-text-v2-moe-GGUF
Common index-level flags (apply to every subcommand):
FlagPurpose
--repo PATHRepository root (default: cwd)
--max-files NCap discovery (default 5000)
--model MLemonade embedding model
--base-url URLLemonade server URL (default http://localhost:8000/api/v1)
--no-lemonade-checkSkip the server reachability check
--use-claude / --use-chatgptCloud LLM for index chat (embeddings still local)
Re-running gaia-code index is incremental: unchanged files (matched by SHA-256) reuse their existing embeddings. 
# 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:
ToolDescription
index_codebaseBuild / refresh the FAISS index
search_code_indexSemantic search over indexed chunks
get_index_statusReport current index state
clear_code_indexRemove 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 nomic-embed-text-v2-moe-GGUF embedding model:
MetricValue
Source files discovered973
Semantic chunks indexed23,974
Languages parsedPython, JavaScript, TypeScript, Go, Rust, Java, C/C++
Embedding modelnomic-embed-text-v2-moe-GGUF (via Lemonade Server)
Wall-clock (remote, ngrok)~51 min
gaia-code index --repo . --model nomic-embed-text-v2-moe-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.