codeix

Portable, composable code index. Build once with tree-sitter, query anywhere via MCP.

codeix                 # start MCP server, watch for changes
codeix build           # parse source files, write .codeindex/
codeix serve --no-watch  # serve without file watching

Why

AI coding agents spend most of their token budget finding code before they can work on it. They grep, read files, grep again, backtrack. On a large codebase the agent might burn thousands of tokens just locating the right function — or worse, miss it entirely and hallucinate.

Codeix gives the agent a pre-built map of your codebase. One structured query returns the symbol name, file, line range, signature, and parent — no scanning, no guessing.

What existing tools get wrong

What codeix does differently

• Committed to git — the index is a .codeindex/ directory you commit with your code. Clone the repo, the index is already there. No re-indexing.
• Shareable — library authors can ship .codeindex/ in their npm/PyPI/crates.io package. Consumers get instant navigation of dependencies.
• Composable — the MCP server auto-discovers dependency indexes and mounts them. Query your code and your dependencies in one place.
• Structured for LLMs — symbols have kinds, signatures, parent relationships, and line ranges. The agent gets exactly what it needs in one tool call instead of piecing it together from raw text.
• Prose search — search_texts targets comments, docstrings, and string literals specifically. Find TODOs, find the error message a user reported, find what a function's docstring says — without noise from code.
• Fast — Rust + tree-sitter + in-memory SQLite FTS5. Builds in seconds, queries in milliseconds.

What it does

Codeix scans your source code with tree-sitter, extracts symbols, imports, comments, and docstrings, then writes a .codeindex/ directory you commit alongside your code.

AI agents query it through MCP (Model Context Protocol) to navigate codebases without re-parsing anything.

The index format

.codeindex/
  index.json        # manifest: version, name, languages
  files.jsonl       # one line per source file (path, lang, hash, line count)
  symbols.jsonl     # one line per symbol (functions, classes, imports, with signatures)
  texts.jsonl       # one line per comment, docstring, string literal

Plain JSONL. Git-friendly diffs. Human-readable with grep and jq. No binary blobs.

Example — symbols.jsonl:

{"file":"src/main.py","name":"os","kind":"import","line":[1,1]}
{"file":"src/main.py","name":"Config","kind":"class","line":[22,45]}
{"file":"src/main.py","name":"Config.__init__","kind":"method","line":[23,30],"parent":"Config","sig":"def __init__(self, path: str, debug: bool = False)"}
{"file":"src/main.py","name":"main","kind":"function","line":[48,60],"sig":"def main(args: list[str]) -> int"}

MCP tools

Six tools, zero setup. The agent queries immediately — no init, no config, no refresh.

Project discovery

Launch codeix from any directory. It walks downward and treats every directory containing .git/ as a separate project — each gets its own .codeindex/.

Works uniformly for single repos, monorepos, sibling repos, and git submodules. No config needed.

Languages

Tree-sitter grammars, feature-gated at compile time:

Embedded scripts

HTML, Vue, Svelte, and Astro files are preprocessed to extract embedded <script> blocks, which are then parsed with the JavaScript or TypeScript grammar:

Line numbers in the index point to the original file, not the extracted script block.

Install

# npm / npx — run without installing
npx codeix

# pip / uvx — run without installing
uvx codeix

# Rust
cargo install codeix

# Homebrew
brew install codeix

# Or build from source
git clone https://github.com/montanetech/codeix.git
cd codeix
cargo build --release

All channels install the same single binary. No runtime dependencies.

Usage

# Build the index for the current project
codeix build

# Build from a specific directory (discovers all git repos below)
codeix build ~/projects

# Start MCP server (default command, watches for changes)
codeix

# Or explicitly
codeix serve
codeix serve --no-watch

MCP client configuration

Add to your MCP client config (e.g. Claude Desktop, Cursor):

{
  "mcpServers": {
    "codeix": {
      "command": "codeix"
    }
  }
}

Design principles

• Local only — no network, no API keys, works offline and air-gapped
• Deterministic — same source always produces the same index (clean diffs)
• Composable — dependency indexes are auto-discovered and mounted at query time
• Minimal surface — 6 query tools, zero management plumbing

Architecture

See docs/architecture.md for the full set of architecture decision records.

License

MIT OR Apache-2.0