justrach/codedb

codedb – a fast code‑intelligence server for AI agents

What it is – codedb is a lightweight, zero‑dependency server written in Zig that builds rich indexes of a local codebase (trigram full‑text, inverted word, symbol outlines, call‑graph, dependency graph, etc.). It exposes these indexes through the Model Context Protocol (MCP) – a JSON‑RPC‑over‑stdio interface that AI‑powered coding assistants (Claude Code, Cursor, Gemini CLI, Codex, etc.) can call to get fast, structured context about the code. It does not edit files; editing is left to the user’s normal editor.

Key capabilities

• Structural indexing for many languages (Zig, C/C++, Python, Rust, Go, …) and lightweight outlines for others.
• Trigram‑accelerated search and O(1) word lookup.
• Symbol lookup, call‑site discovery, and call‑path computation.
• Dependency graph (imports or markdown links) and recent‑change tracking.
• MCP tools (22 built‑in commands) that agents can invoke with a single RPC call.
• HTTP mode (codedb serve) for non‑MCP clients.
• File‑watcher keeps the index up‑to‑date incrementally (sub‑2 ms re‑index of a single file).

Why it matters for AI agents – Agents need concise, token‑efficient context. codedb returns structured JSON (or plain text) with only the relevant symbols, callers, or snippets, cutting token usage by hundreds‑to‑thousands‑fold compared with raw grep/ripgrep output. Benchmarks show sub‑millisecond query latency (≈0.05 ms) versus ~55 ms CLI startup and ~5‑7 ms per‑search for traditional tools.

---

Install

• macOS / Linux – one‑liner script downloads the appropriate signed binary and registers it automatically with supported AI‑coding tools:

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

• Windows – PowerShell installer:

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

• npm – the codedeebee package is a thin launcher that fetches the native binary on install. The CLI remains codedb.
• All binaries are SHA‑256 verified; macOS builds are codesigned and notarized.

---

Quick start

# Start the MCP server (auto‑registered with Claude, Cursor, etc.)
codedb mcp /path/to/project

# Or run as a simple HTTP daemon
codedb serve /path/to/project   # listens on localhost:7719

Typical agent workflow:

1. Tree – codedb_tree → full file tree with symbol counts.
2. Outline – codedb_outline src/main.zig → functions/structs with line numbers.
3. Symbol – codedb_find AgentRegistry → definition location.
4. Search – codedb_search "handleAuth" → trigram‑fast full‑text search.
5. Callers / Call‑path – codedb_callers or codedb_callpath to trace usage.

All of these can be invoked via HTTP (curl localhost:7719/...) or directly through the MCP JSON‑RPC channel used by the AI assistants.

---

Architecture (high‑level)

• Indexer – runs once on startup, parses supported languages, builds:
  • Trigram index (integer doc IDs, batch merge) for fast fuzzy text search.
  • Inverted word index for O(1) identifier lookup.
  • Structural outline (functions, structs, imports) stored per file.
  • Dependency graph linking imports or markdown links.
• Snapshot – the whole index can be serialized to codedb.snapshot for instant daemon restart.
• MCP server – thin JSON‑RPC 2.0 layer over stdio; each tool is a single RPC method that composes the pre‑built indexes.
• File watcher – filtered directory walk updates the in‑memory index incrementally; a single file change costs <2 ms.
• Cross‑platform – native binaries for macOS (ARM & Intel), Linux (ARM & x86_64), and Windows.

---

Data & privacy

• Operates locally only; no network traffic unless you enable the optional DeepWiki remote MCP for public GitHub repos.
• HTTP server binds to localhost by default; no authentication layer is provided.
• Sensitive files (.env, keys, etc.) are automatically blocked from indexing.

---

Who might use it?

• Developers building AI‑coding assistants that need fast, token‑efficient code context.
• Teams running Claude Code, Cursor, Gemini CLI, or similar agents who want a drop‑in local knowledge base.
• Researchers experimenting with retrieval‑augmented generation (RAG) for code.

---

Current status

• Alpha – API is stabilising. Core features (MCP tools, trigram search, word index, structural outlines, dependency graph) are production‑ready and used daily.
• Ongoing work: deeper parser coverage, incremental segment‑based indexing, WASM target, multi‑project support, mmap‑backed trigram index.

---

Bottom line – codedb gives AI agents a fast, structured view of a codebase without pulling in heavyweight tooling. Its sub‑millisecond query times and tiny token footprints make it a practical backbone for any LLM‑driven coding workflow.