> ## 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.

# Code Index

> Semantic search over your codebase using local AMD-accelerated embeddings.

<Info>
  **Source Code:** [`src/gaia/code_index/`](https://github.com/amd/gaia/blob/main/src/gaia/code_index/) and [`src/gaia/agents/code_index/tools/mixin.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/code_index/tools/mixin.py)
</Info>

<Note>
  **Looking for the API?** See the [Code Index SDK Reference](/sdk/sdks/code-index) for `CodeIndexSDK`, `CodeIndexConfig`, and `CodeIndexToolsMixin`.
</Note>

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 (`nomic-embed-text-v2-moe-GGUF` 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):

```bash theme={null}
uv pip install -e '.[rag]'
```

Start Lemonade Server so embeddings can be generated:

```bash theme={null}
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

```bash theme={null}
# 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):

| 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

```bash theme={null}
# 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:

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
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`](https://github.com/amd/gaia/blob/main/src/gaia/agents/registry.py)) for dynamic resolution. For SDK-level composition see the [SDK reference](/sdk/sdks/code-index).

### 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:

```bash theme={null}
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](https://github.com/amd/gaia/issues/868).

## Real-world benchmark

Indexing the gaia repo itself against Lemonade Server's `nomic-embed-text-v2-moe-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            | `nomic-embed-text-v2-moe-GGUF` (via Lemonade Server)  |
| Wall-clock (remote, ngrok) | \~51 min                                              |

```bash theme={null}
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](https://github.com/amd/gaia/issues/868).

## Roadmap

* [#869](https://github.com/amd/gaia/issues/869) — MCP server wrapper, so external code assistants can drive the index.
* [#870](https://github.com/amd/gaia/issues/870) — Multi-repo indexing in a single namespace.
* [#871](https://github.com/amd/gaia/issues/871) — Verilog / VHDL parsers for hardware-design codebases.