justrach/codedb: a Zig code intelligence server for AI agents, MCP native

The problem codedb solves: giving agents structure instead of file reads

An agent working in a large repository has two blunt options. It can read files until it happens to find the relevant function, or it can run a text search and sift the hits. Both spend context on material the agent does not need. codedb takes a different position: build the structural index once, keep it current, and let the agent query it. The README describes the project as a context engine rather than an editor, and states plainly that codedb has no edit capability. Search, symbols, callers, dependencies and outlines are the surface it offers; editing is handed back to whatever tool you already use.

The audience is narrow and specific. The topics list names agentic-ai, agents, anthropic, cursor, gemini, mcp, openai and zig, and the installer registers the server directly into Claude Code, Codex, Gemini CLI, Cursor, Windsurf and Devin. If you do not run an MCP client, most of the value is unreachable. The repository also ships a CLI, documented in docs/cli.md, so the index is usable from a terminal, but the design centre is the agent loop.

The project is alpha. The README carries an explicit status note and says parsers may still change. That matters more than the feature list when you are deciding whether to put it in a workflow you depend on.

How the index is built: trigram, word index, dependency graph, watcher

The README names four structural components: structural indexing, trigram search, a word index, and a dependency graph, plus a polling file watcher with a filtered directory walker. Trigram v2 is described as using integer doc IDs, batch-accumulate and merge intersect. The word index is described as an O(1) inverted index for identifier lookup. The dependency graph is reverse, which is the direction that answers who calls this rather than what does this call. The watcher keeps the index from going stale while an agent session is open.

Parsing is split into two tiers, and the split is the most consequential architectural detail in the README. Full parser support covers Zig, C/C++, Python, TypeScript/JavaScript, Rust, Go, PHP, Ruby, HCL, R, Dart/Flutter and OCaml. Lightweight outline support covers Java, Kotlin, Svelte, Vue, Astro, shell, CSS/SCSS, SQL, protobuf, Fortran, LLVM IR, MLIR and TableGen. If your work is in Java or Kotlin, you get outlines, not the full structural treatment. That is a real difference in what an agent can ask about.

The transport layer is JSON-RPC 2.0 over stdio, which the README calls stable, with an HTTP server that binds to localhost only and has no auth. There is a portable snapshot for instant MCP startup, and the server runs as a singleton MCP with a PID lock and a one-hour idle timeout. Sensitive file blocking covers .env, credentials and keys. The README also lists an incremental segment-based indexing effort and an mmap-backed trigram index as in progress, so the current index is not yet the one the roadmap describes.

Installing codedb and running a first MCP session

The macOS and Linux path is a shell installer that downloads the binary for your platform and registers codedb as an MCP server in whichever supported clients it finds on the machine. Registration is described as additive and per-tool, written only when that tool is present.

curl -fsSL https://codedb.codegraff.com/install.sh | bash

After it finishes, the installer prints the exact codedb mcp command it registered, plus hook setup pointers for Codex and Claude Code. That printed command is what you should compare against your client's config file.

On Windows, the README gives a PowerShell one-liner and notes that running the same command again updates codedb. The URL it shows is pinned to a release tag rather than a moving branch.

irm https://raw.githubusercontent.com/justrach/codedb/v0.2.5841/install/install.ps1 | iex

If you prefer npm, the package is named codedeebee because the bare codedb name is restricted on npm. The launcher downloads the matching native binary from GitHub Releases on postinstall and verifies a SHA256 checksum; the installed CLI is still called codedb.

npx -y codedeebee mcp

For MCP clients that already use npx, the README gives this config shape. Note that the command array starts with npx and the args array carries mcp as a separate element.

{
  "codedb": {
    "type": "local",
    "command": ["npx", "-y", "codedeebee"],
    "args": ["mcp"],
    "enabled": true
  }
}

The README is explicit that npx does not work on Windows yet: the published codedeebee predates the codedb-windows-x86_64.exe release asset, so Windows users should stay on the PowerShell installer until the next published release. If codedb update fails on an older release, the repair path on macOS and Linux is to rerun the install script, which replaces the binary and keeps existing MCP registrations, config, caches and snapshots.

Where codedb is the wrong tool

The clearest boundary is editing. The README states codedb has no edit capability and is not an editor. There is a fallback editor listed among working features, described as atomic line-range edits with version tracking, but the project's own framing is that editing belongs to your native tools. If your requirement is an agent that rewrites code through the same server it searches with, codedb is the wrong component.

The second boundary is language coverage. Java, Kotlin, Svelte, Vue, Astro, shell, CSS/SCSS, SQL, protobuf, Fortran, LLVM IR, MLIR and TableGen sit in the lightweight outline tier. An agent asking for callers in a Kotlin codebase will not get what it gets in Rust. The README does not describe how the two tiers differ in output, only that one is full parser support and the other is lightweight outline support, so treat the difference as unquantified until you check your own language.

The third is operational. There is no auth and the HTTP server binds to localhost only, so exposing it beyond the local machine is not a supported configuration. Multi-project support is listed as in progress, which means one index per working context today. And the snapshot format may change between versions, which makes snapshots a cache to regenerate rather than an artifact to commit. The README does not document any rollback or migration path for a snapshot written by an older release.

codedb compared with tree-sitter based indexers

The obvious alternative class is a tree-sitter based indexer wired to an MCP server. The difference is where the work happens. A tree-sitter setup typically parses on demand and returns syntax nodes; the agent then decides what to do with the tree. codedb parses ahead of the query into persistent structures: a trigram index, an inverted word index, and a reverse dependency graph, with a watcher keeping them current. Queries hit those structures rather than a fresh parse.

That trade shows up in startup and in memory. codedb ships a portable snapshot specifically so MCP startup is instant, and the README lists an mmap-backed trigram index as still in progress, which suggests the current index is not memory-mapped. A tree-sitter approach has no persistent index to keep valid and no snapshot format to worry about when versions move, but it pays parse cost per query and gives the agent less precomputed structure.

The second alternative is the text search you already have. The README claims trigram v2 is 538x faster than ripgrep on pre-indexed queries. The qualifier matters: pre-indexed. On a cold repository with no index, that number does not describe your situation. If your workflow is one-off searches across many unfamiliar repositories, an index you build and discard is overhead, and ripgrep is the better fit.

Licence, maintenance and the cost of keeping codedb current

codedb is BSD-3-Clause. That is a permissive licence, and the repository ships the full text in LICENSE. For most teams this means the usual obligations around retaining the copyright notice and licence text in redistributed copies. Nothing here is legal advice; read LICENSE and your own policy if you plan to redistribute the binary or the npm launcher.

On maintenance, the last push to the default branch was on 2026-09-05, and the most recent release is v0.2.5854 from the same day, described as a retrieval accuracy update. The two releases before it, v0.2.5853 and v0.2.5852, are also from early September 2026 and cover hybrid retrieval accuracy and a semantic index compatibility hotfix. The release cadence is dense, and the version numbers move in the thousands, which tells you the project is iterating quickly rather than settling.

That cadence is also the upgrade cost. A semantic index compatibility hotfix implies index compatibility has already broken at least once. Combined with the README's statement that the snapshot format may change between versions, the practical routine is to expect regeneration after upgrades rather than in-place migration. Self-update via codedb update works on native Windows from 0.2.5833 onward; on older builds you rerun the PowerShell installer. On macOS and Linux, rerunning the install script is the documented repair path when the built-in updater cannot fetch release checksums.

Editorial conclusion

Adopt codedb if you drive Claude Code, Codex, Gemini CLI, Cursor, Windsurf or Devin and you want structural search, symbol lookup and dependency queries served from a local index instead of repeated filesystem scans. Skip it if you need a stable wire format, multi-project indexing, or anything that writes code: the README states the snapshot format may change between versions, multi-project support is listed as in progress, and codedb has no edit capability. Verify first that your client is one the installer registers, that your language falls under the parser list rather than the lighter outline list, and whether your build needs the self-update path at all, since releases before 0.2.5833 cannot run codedb update on native Windows.

Frequently asked questions

Official sources

1. justrach/codedb on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases