codedb

---

Status

Alpha software — API is stabilizing but may change

codedb works and is used daily in production AI workflows, but:

• Parser support — Zig, C/C++, Python, TypeScript/JavaScript, Rust, Go, PHP, Ruby, HCL, R, Dart/Flutter
• Lightweight outline support — Java, Kotlin, Svelte, Vue, Astro, shell, CSS/SCSS, SQL, protobuf, Fortran, LLVM IR, MLIR, and TableGen
• No auth — HTTP server binds to localhost only
• Snapshot format may change between versions
• MCP protocol is JSON-RPC 2.0 over stdio (stable)

What works today	What's in progress
21 MCP tools for full codebase intelligence	Deeper parser coverage and edge-case handling
Trigram v2: integer doc IDs, batch-accumulate, merge intersect	Incremental segment-based indexing
538x faster than ripgrep on pre-indexed queries	WASM target for Cloudflare Workers
O(1) inverted word index for identifier lookup	Multi-project support
Structural outlines (functions, structs, imports)	mmap-backed trigram index
Reverse dependency graph
Fallback editor: atomic line-range edits + version tracking
Auto-registration in Claude, Codex, Gemini, Cursor, Windsurf, Devin
Polling file watcher with filtered directory walker
Portable snapshot for instant MCP startup
Singleton MCP with PID lock + 1h idle timeout
Sensitive file blocking (.env, credentials, keys)
Codesigned macOS ARM64 binary; Intel slice temporarily unsigned
SHA256 checksum verification in installer
Cross-platform: macOS (ARM/x86), Linux (ARM/x86)

---

⚡ Install

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

Downloads the binary for your platform and auto-registers codedb as an MCP server in Claude Code, Codex, Gemini CLI, Cursor, Windsurf, and Devin — each written directly and additively into that tool's config (only when the tool is present). The installer prints the exact codedb mcp command it registered plus hook setup pointers for Codex and Claude Code.

Or via npm/npx (zero-install for MCP clients)

npx -y codedeebee mcp

Or install globally:

npm install -g codedeebee
codedb mcp

The npm package is named codedeebee (the bare codedb name is restricted on npm); it ships a thin launcher that downloads the matching native binary from GitHub Releases on postinstall and verifies the SHA256 checksum. The installed CLI is still called codedb.

Useful for MCP clients (Claude Code, Cursor, opencode, Claude Desktop) that already use npx:

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

Updating or repairing an older install

If codedb update fails on an older release, rerun the installer:

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

This replaces the codedb binary with the latest GitHub Release and keeps your existing MCP registrations, config, caches, and snapshots. Use this path for any release whose built-in updater cannot fetch release checksums.

Documentation

• MCP setup — per-client configurations (Claude Desktop, Cursor, VS Code, Claude Code, Codex CLI, Gemini CLI), root resolution, troubleshooting
• Skill base & context files — agents.md / CLAUDE.md / GEMINI.md, .codedbrc, per-developer memory
• CLI reference — every command, every flag
• Architecture — engine internals, index layout
• Benchmarks — micro-benchmarks + agentic-eval results vs codegraph, FTS5, lean-ctx
• Raspberry Pi 4 — full-performance ARM64 setup, Cortex-A72 build, and on-device benchmark
• Zig 0.17.0-dev migration guide — repeatable zigup workflow and API change recipes

Platform	Binary	Signed
macOS ARM64 (Apple Silicon)	codedb-darwin-arm64	✅ codesigned + notarized
macOS x86_64 (Intel)	codedb-darwin-x86_64	temporarily unsigned
Linux ARM64	codedb-linux-arm64	—
Linux x86_64	codedb-linux-x86_64	—

Or install manually from GitHub Releases.

---

⚡ Quick Start

As an MCP server (recommended)

After installing, codedb is automatically registered. Just open a project and the 21 MCP tools are available to your AI agent.

# Manual MCP start (auto-configured by install script)
codedb mcp /path/to/your/project

As an HTTP server

codedb serve /path/to/your/project
# listening on localhost:7719

CLI

codedb tree /path/to/project          # file tree with symbol counts
codedb outline src/main.zig           # symbols in a file
codedb find AgentRegistry             # find symbol definitions
codedb search "handleAuth"            # full-text search (trigram-accelerated)
codedb word Store                     # exact word lookup (inverted index, O(1))
codedb hot                            # recently modified files

---

🔧 MCP Tools

21 tools over the Model Context Protocol (JSON-RPC 2.0 over stdio). codedb's job is to give agents context — fast structural search, symbols, callers, dependencies, and outlines — not to be your editor. Editing is intentionally a fallback (codedb_edit); prefer your client's native edit tools.

Tool	Description
codedb_tree	Full file tree with language, line counts, symbol counts
codedb_outline	Symbols in a file: functions, structs, imports, with line numbers
codedb_symbol	Find where a symbol is defined across the codebase
codedb_search	Trigram-accelerated full-text search (supports regex, scoped results)
codedb_word	O(1) inverted index word lookup
codedb_callers	Every call site of a symbol — word index ∩ outline scope, in one round-trip
codedb_context	Task-shaped composer — pass a NL task, get keywords + symbol defs + ranked files + top snippets in one block (replaces 3–5 sequential calls)
codedb_hot	Most recently modified files
codedb_deps	Dependency graph: imported_by (default) or depends_on; transitive=true for full BFS
codedb_read	Read file content (line ranges, if_hash skip-unchanged, compact mode)
codedb_edit	Fallback editor — str_replace/replace/insert/delete/create (atomic writes, optional if_hash guard). Prefer your client's native edit tool; codedb is for context, not editing
codedb_changes	Changed files since a sequence number
codedb_status	Index status (file count, current sequence, scan phase)
codedb_snapshot	Full pre-rendered JSON snapshot of the codebase
codedb_remote	Query indexed public repos via api.wiki.codes — no local clone needed
codedb_projects	List all locally indexed projects on this machine
codedb_index	Index a local folder and write codedb.snapshot

codedb_remote — Cloud Intelligence

Query any indexed public GitHub repo without cloning it. codedb_remote always uses api.wiki.codes; the old codegraff backend name is no longer a supported route. Omit backend, or keep backend="wiki" only for older prompts.

# Check what the remote slug supports
codedb_remote repo="vercel/next.js" action="actions"

# Get a compact directory summary instead of dumping a huge file list
codedb_remote repo="vercel/next.js" action="tree" expand=false

# Page a file tree by prefix and limit
codedb_remote repo="vercel/next.js" action="tree" prefix="packages/" limit=100

# Search for code in a dependency
codedb_remote repo="justrach/merjs" action="search" query="handleRequest"

# Read a small file slice
codedb_remote repo="openai/codex" action="read" path="codex-rs/core/src/codex.rs" lines="1-80"

# Exact symbol lookup
codedb_remote repo="justrach/codedb" action="symbol" query="buildSnapshot"

# Check dependency CVE evidence; scope can be runtime or all
codedb_remote repo="axios/axios" action="cves" scope="runtime"

# Raw wiki slugs are accepted for repos that are indexed that way
codedb_remote repo="chromium" action="policy"

Remote actions: actions, tree, outline, search, read, symbol, policy, deps, score, cves, commits, branches, dep-history

For Codex and Claude Code hook examples around codedb_remote, see docs/hooks-labs.md.

Note: This tool calls https://api.wiki.codes. No API key required. The repo must already be indexed by the public service.

CLI Commands

Command	Description
codedb tree	Show file tree with language and symbol counts
codedb outline <path>	List a