codedb: a Zig code intelligence server that indexes a repository and exposes it to agents over MCP

The problem codedb targets: agents that grep instead of reading structure

An agent asked to change a function usually starts by searching for the function name. Text search returns matches, not relationships. It cannot tell the agent which other files call that function, which module imports it, or where the struct is defined. The agent reconstructs that picture by reading files one at a time, spending context on code it will never modify. codedb's answer is to build the structural picture ahead of time and serve it as discrete tool calls. The README frames the scope directly: codedb is "a context engine, not an editor", and it helps agents "find and understand" code before handing editing back to native tools. That boundary is the design decision that matters most. The intended user is someone running an agent loop in Claude Code, Cursor, Codex, Gemini CLI, Windsurf or Devin, who wants the agent to ask for a symbol outline or a reverse dependency list instead of opening twenty files. It is not aimed at a developer who wants a terminal code browser, and it is not aimed at CI static analysis, because nothing in the material describes a CI mode or a non-zero exit on findings.

How the index is built: structural parsing, trigrams and a word index

Three index layers are described in the README. The first is a structural parse that produces outlines: functions, structs and imports. The second is a trigram index, described as "Trigram v2: integer doc IDs, batch-accumulate, merge intersect". The third is an inverted word index, described as O(1) for identifier lookup. Alongside these sits a reverse dependency graph, which is what makes caller and dependency queries possible rather than just symbol lookup. File watching keeps the index current; the README describes it as a "polling file watcher with filtered directory walker", so freshness is bounded by the poll interval rather than by filesystem events. The transport layer is dual: MCP over stdio, which the status table calls JSON-RPC 2.0 and marks stable, and an HTTP server that binds to localhost only. A portable snapshot file lets an MCP session start without re-indexing the whole tree, and a singleton MCP process with a PID lock and a one-hour idle timeout prevents duplicate servers from piling up. Sensitive file blocking (.env, credentials, keys) is applied during indexing, which is a meaningful default given that the index is served to a model.

Installing codedb and registering it as an MCP server

On macOS and Linux the documented path is a single shell command: curl -fsSL https://codedb.codegraff.com/install.sh | bash. The README states that this downloads the platform binary and auto-registers codedb as an MCP server in Claude Code, Codex, Gemini CLI, Cursor, Windsurf and Devin, writing additively into each tool's config and only when that tool is present. The installer prints the exact codedb mcp command it registered. On Windows the documented path is a PowerShell one-liner pinned to a tag: irm https://raw.githubusercontent.com/justrach/codedb/v0.2.5841/install/install.ps1 | iex, and running the same command again updates the binary. There is an npm route as well. The package is named codedeebee because the bare codedb name is restricted on npm; it ships a launcher that downloads the matching native binary on postinstall and verifies a SHA256 checksum. The installed CLI is still called codedb. For clients that already use npx, the README gives this config block: a codedb entry with type "local", command ["npx", "-y", "codedeebee"], args ["mcp"], and enabled true. One caveat is stated plainly: the currently published codedeebee predates the Windows release asset, so npx -y codedeebee mcp does not work on Windows yet. Repairing an older install on macOS or Linux means rerunning the install script, which the README says keeps existing MCP registrations, config, caches and snapshots.

Parser coverage is two tiers, and the gap is the practical risk

The status section splits language support into two lists, and the split is not cosmetic. 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. The README does not define what "lightweight" excludes, so the honest reading is that outline-level results are what you get for the second list, and anything depending on the dependency graph is unverified for those languages. A Java or Kotlin codebase is therefore a partial fit at best. The project labels itself alpha and says the API is stabilizing but may change, with the snapshot format explicitly flagged as possibly changing between versions. The MCP protocol layer is the one component marked stable. That combination means the index is the volatile part and the interface is the settled part, which is the reverse of what most teams plan for when they pin a dependency.

What codedb does not do, and where the README's claims need care

The README states twice that codedb has no edit capability, then lists "Fallback editor: atomic line-range edits + version tracking" among the things that work today. Those two statements sit in the same document and are not reconciled. The most defensible reading is that an editing path exists but is positioned as a fallback rather than a product surface, and that the framing of codedb as a context engine is the intended one. Anyone choosing this tool on the strength of the no-edit boundary should confirm the current behaviour before relying on it. The same care applies to the performance claim. The README says "538x faster than ripgrep on pre-indexed queries". That is a pre-indexed figure, so it excludes the cost of building the index and says nothing about a cold query or a repository that changes faster than the polling watcher notices. No benchmark methodology, corpus or hardware is given in the material. The HTTP server has no authentication and is documented as binding to localhost only, which is fine for a laptop and a problem the moment someone changes the bind address. Multi-project support and incremental segment-based indexing are both listed as in progress, so a monorepo with several roots is ahead of what is described.

How codedb differs from a language server or a plain grep loop

The closest familiar alternative is a language server such as gopls or rust-analyzer. A language server also parses a project and answers symbol, definition and reference queries, and it does so with compiler-grade accuracy for its one language. The difference in approach is the delivery surface and the language count. Language servers speak LSP to an editor and are typically single-language; codedb speaks MCP to an agent and covers many languages at varying depth. An agent cannot call gopls directly without an LSP bridge, whereas codedb's tools are already in the MCP vocabulary the client understands. The other alternative is the status quo: letting the agent run ripgrep and read files. That costs no setup and never goes stale, but it returns text matches with no notion of callers or imports, and the agent pays for the missing structure in tokens. codedb trades a one-time indexing cost and a background process for cheaper structural queries. If your agent already works well with grep on a small repository, the index is overhead you do not need.

Maintenance, release cadence and licence

The release history in the material is dense and recent. v0.2.5854 and v0.2.5853 both landed on 2026-09-05, hours apart, described as retrieval accuracy and hybrid retrieval accuracy updates; v0.2.5852 on 2026-09-01 is described as a semantic index compatibility hotfix. That cadence suggests active iteration on retrieval quality, and it also means the version number moves fast enough that pinning matters. The README notes that self-update works on native Windows from 0.2.5833 onward, and that older builds must rerun the PowerShell installer. On macOS and Linux the install script is the repair path when codedb update cannot fetch release checksums. Release downloads and npm packages are described as SHA256-verified, and macOS binaries as codesigned and notarized from 0.2.5833. The licence is BSD-3-Clause, a permissive licence that permits commercial use and modification with the copyright notice and disclaimer retained; the npm package name codedeebee is a separate branding constraint, not a licensing one. This is not legal advice, and anyone redistributing a modified binary should read the licence text in the repository rather than this summary.

Editorial conclusion

Adopt codedb if your agents already run inside an MCP-capable client and you want structural answers (callers, dependencies, outlines) rather than raw text matches. Do not adopt it if you need a stable snapshot format, a Windows npx path today, or an editing tool: the README states codedb has no edit capability and that the snapshot format may change between versions. Before committing, verify three things on your own repository: that your primary language is on the full-parser list rather than the lightweight-outline list, that the HTTP server is still bound to localhost in your build, and that the version you install matches the release asset your launcher expects.

Official sources

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