{ "markdown": "# codeix\n\n\n\n**[codeix.dev](https://codeix.dev)** · Fast semantic code search for AI agents — find symbols, references, and callers across any codebase.\n\n```\ncodeix # start MCP server, watch for changes\ncodeix build # parse source files, write .codeindex\ncodeix -r ~/project build # build from a specific directory\n```\n\n## Why\n\nAI 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.\n\n**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.\n\n### What existing tools get wrong\n\n| Problem | What happens today |\n|---|---|\n| **No structure** | `grep` finds text matches, not symbols. The agent can't distinguish a function definition from a comment mentioning it. |\n| **Slow re-parsing** | Python-based indexers re-parse everything on startup. On large codebases, you wait. |\n| **Not shareable** | Indexes are local caches — ephemeral, per-machine. A new developer or CI runner starts from scratch. |\n| **No composition** | Monorepo with 10 packages? Dependencies with useful APIs? No way to query across boundaries. |\n| **Prose is invisible** | TODOs, docstrings, error messages — searchable by grep but not *selectively*. You can't search only comments without also matching code. |\n\n### What codeix does differently\n\n- **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.\n- **Shareable** — library authors can ship `.codeindex` in their npm/PyPI/crates.io package. Consumers get instant navigation of dependencies.\n- **Composable** — the MCP server auto-discovers dependency indexes and mounts them. Query your code and your dependencies in one place.\n- **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.\n- **Prose search** — `search --scope text` 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.\n- **Fast** — builds in seconds, queries in milliseconds. Rust + tree-sitter + in-memory SQLite FTS5 under the hood.\n\n## The `.codeindex` format\n\nAn open, portable format for structured code indexing. Plain JSONL files you commit alongside your code — git-friendly diffs, human-readable with `grep` and `jq`, no binary blobs.\n\n```\n.codeindex/\n index.json # manifest: version, name, languages\n files.jsonl # one line per source file (path, lang, hash, line count)\n symbols.jsonl # one line per symbol (functions, classes, imports, with signatures)\n texts.jsonl # one line per comment, docstring, string literal\n```\n\nAny tool that can parse JSON can consume a `.codeindex`. Codeix builds it using [tree-sitter](https://tree-sitter.github.io/), and AI agents query it through [MCP](https://modelcontextprotocol.io/) (Model Context Protocol).\n\n**Example** — `symbols.jsonl`:\n```jsonl\n{\"file\":\"src/main.py\",\"name\":\"os\",\"kind\":\"import\",\"line\":[1,1]}\n{\"file\":\"src/main.py\",\"name\":\"Config\",\"kind\":\"class\",\"line\":[22,45]}\n{\"file\":\"src/main.py\",\"name\":\"Config.__init__\",\"kind\":\"method\",\"line\":[23,30],\"parent\":\"Config\",\"sig\":\"def __init__(self, path: str, debug: bool = False)\"}\n{\"file\":\"src/main.py\",\"name\":\"main\",\"kind\":\"function\",\"line\":[48,60],\"sig\":\"def main(args: list[str]) -> int\"}\n```\n\n## Ship your index with your package\n\nInclude `.codeindex` in your package and every developer who depends on you gets instant navigation of your API — no setup, no re-indexing.\n\nWorks with Git repos, npm, PyPI, and crates.io.\n\n## MCP tools\n\nSeven tools, zero setup. The agent queries immediately — no init, no config, no refresh.\n\n| Tool | What it does |\n|---|---|\n| `explore` | Explore project structure: metadata, subprojects, files grouped by directory |\n| `search` | Unified full-text search across symbols, files, and texts (FTS5, BM25-ranked) with scope/kind/path/project filters |\n| `get_file_symbols` | List all symbols in a file |\n| `get_children` | Get children of a class/module |\n| `get_callers` | Find all places that call or reference a symbol |\n| `get_callees` | Find all symbols that a function/method calls |\n| `flush_index` | Flush pending index changes to disk |\n\n## Project discovery\n\nLaunch `codeix` from any directory. It walks downward and treats every directory containing `.git/` as a separate project — each gets its own `.codeindex`.\n\nWorks uniformly for single repos, monorepos, sibling repos, and git submodules. No config needed.\n\n## Languages\n\nTree-sitter grammars, feature-gated at compile time:\n\n| Language | Feature flag | Default | Extensions |\n|---|---|---|---|\n| Python | `lang-python` | yes | `.py` `.pyi` `.pyw` |\n| Rust | `lang-rust` | yes | `.rs` |\n| JavaScript | `lang-javascript` | yes | `.js` `.mjs` `.cjs` `.jsx` |\n| TypeScript | `lang-typescript` | yes | `.ts` `.mts` `.cts` `.tsx` |\n| Go | `lang-go` | yes | `.go` |\n| Java | `lang-java` | yes | `.java` |\n| C | `lang-c` | yes | `.c` `.h` |\n| C++ | `lang-cpp` | yes | `.cpp` `.cc` `.cxx` `.hpp` `.hxx` |\n| Ruby | `lang-ruby` | yes | `.rb` `.rake` `.gemspec` |\n| C# | `lang-csharp` | yes | `.cs` |\n| Markdown | `lang-markdown` | yes | `.md` `.markdown` |\n\n### Markdown support\n\nMarkdown files are parsed for **headings** (both ATX `#` and Setext underline styles) which are indexed as `section` symbols with hierarchical parent-child relationships — enabling TOC extraction and document structure navigation.\n\nFenced code blocks are extracted as `code` text entries, parented to their containing section.\n\n### Embedded scripts\n\nHTML, Vue, Svelte, and Astro files are preprocessed to extract embedded `