justrach/codedb

Code intelligence for your coding agent. Built in Zig. Connected over MCP.

Install · Quick start · Tools · Benchmarks · Data & privacy · Harness · Meet the family ↗

Your agent has a task. Somewhere in your repository are the definition it needs, the caller that explains it, and the test that keeps it honest. codedb draws the map: focused source context, symbols, callers, outlines, and dependencies. Your coding client uses its own native tools to make the edit.

A context engine, not an editor. codedb has no edit capability. Use it with Graff, Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Devin, oh-my-pi, Hermes, Qwen Code, ZCode, Trae, Cline, Copilot CLI, Antigravity, Kiro, OpenCode, or another MCP client.

Structural search runs locally. Default hybrid retrieval also uses hosted embeddings; choose semantic=local for local-only retrieval. See Data & Privacy for what each mode sends and stores.

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, Devin, oh-my-pi, Hermes, Qwen Code, ZCode, Trae, Cline, Copilot CLI, Antigravity, Kiro, and OpenCode — 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.

On Windows, run this command inside WSL only if you want the Linux binary inside WSL. For the native Windows binary, use PowerShell below.

Run in PowerShell:

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

Run the same command again to update codedb.

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.

The launcher already knows how to fetch codedb-windows-x86_64.exe, but the currently published codedeebee predates that release asset, so npx -y codedeebee mcp does not work on Windows yet — it becomes available with the next published release. Use the PowerShell installer above until then.

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
  }
}

On macOS or Linux, 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.

Self-update works on native Windows from 0.2.5833 onward (codedb update). On older builds, rerun the PowerShell installer above to update or repair the binary.

Harness is a free desktop app for macOS and Windows that runs Graff, Claude Code, Codex, Cursor, and your other coding agents in one window, with each session's files, browser, and terminal beside it. The agents you run there use their usual MCP configuration, so the codedb registration from the installer carries over: install codedb once, and every agent in Harness can use the map.

An iPhone and iPad app for following and steering those sessions is in development. Join the waitlist.

Alpha: APIs and snapshot formats can change. The core speaks JSON-RPC 2.0 over stdio, with an optional localhost HTTP server.

• Parsers: Zig, C/C++, Python, TypeScript/JavaScript, Rust, Go, PHP, Ruby, HCL, R, Dart/Flutter, and OCaml; more languages have lightweight outlines.
• Navigation: task context, symbol definitions, callers, dependency graphs, trigram search, and portable snapshots.
• Live updates: bounded OS watches with periodic content verification for overflow. Each MCP process owns its watcher; multiple clients can multiply background work.
• Distribution: macOS, Linux, and Windows binaries; SHA256-verified downloads. macOS releases are signed and notarized.

• MCP setup — per-client configurations (Claude Desktop, Cursor, VS Code, Claude Code, Codex CLI, Gemini CLI, oh-my-pi, Hermes, Qwen Code, ZCode, Trae, Cline, Copilot CLI, Antigravity, Kiro, OpenCode), 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

Or install manually from GitHub Releases. Always verify the binary against the attached checksums.sha256 before running it.

The macOS/Linux shell installer registers codedb automatically. For npm/npx installs on macOS/Linux and manual Windows installs, use the MCP configuration above or the client-specific examples in docs/mcp.md. Then open a project and codedb’s tools are available to your AI agent.

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

For clients that open many unused MCP sessions (for example, one per worktree), try experimental lazy MCP startup with CODEDB_LAZY_MCP=1. Indexing starts on the first code request; eager startup remains the default.

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

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

Tools over the Model Context Protocol (JSON-RPC 2.0 over stdio). Agents see five one-shots by default (context, explain, callpath, list_dir, status). codedb's job is to give agents context — not to be your editor. codedb has no edit tool; use your client's native edit tools.

codedb_context accepts max_tokens as a conservative approximate response budget. Compact evidence is admitted progressively; when the remaining evidence does not fit, the response reports the omission once instead of overflowing the request with lower-priority sections.

MCP responses are plain text by default, without ANSI styling. Set CODEDB_MCP_ANSI=1 in the MCP server environment to opt into ANSI-colored summary and guidance blocks for clients that render terminal colors.

Tool profile: agent harnesses default to mini — five one-shot tools (context, explain, callpath, list_dir, status). Hop tools stay callable; they are not advertised. CODEDB_TOOLS_PROFILE=core is the older 10-tool navigation set; slim is the terse hop six; full advertises everything. GUI clients that emit rich blocks still get full unless the env var is set.

codedb indexes your checked-out code. For questions about public GitHub repos, the installer registers DeepWiki (https://mcp.deepwiki.com/mcp — free, no auth) as a separate remote MCP server in each detected client, with tools read_wiki_structure, read_wiki_contents, and ask_question. Opt out at install time with CODEDB_INSTALL_DEEPWIKI=0. (The old codedb_remote tool backed by api.wiki.codes was removed; DeepWiki replaces that role.)

Options: --no-telemetry (or set CODEDB_NO_TELEMETRY env var)

Claude Code hook opt-out: the installer registers a PreToolUse hook that nudges agents from grep/cat to codedb inside indexed repos. CODEDB_NO_HOOKS=1 skips it for that run only (it is never persisted from the environment, so a transient export can't be promoted to a permanent opt-out by the background auto-updater). To make it permanent, run the installer with CODEDB_PERSIST_NO_HOOKS=1 or touch ~/.codedb/no-hooks; rm ~/.codedb/no-hooks re-enables it. Deleting the hook entry from ~/.claude/settings.json is also permanent — the installer records its registrations and treats a missing entry as a deliberate removal (it writes ~/.codedb/no-hooks for you, so rm that file to undo).

# 1. Get the file tree
curl localhost:7719/tree
# → src/main.zig      (zig, 55L, 4 symbols)
#   src/store.zig     (zig, 156L, 12 symbols)
#   src/agent.zig     (zig, 135L, 8 symbols)

# 2. Drill into a file
curl "localhost:7719/outline?path=src/store.zig"
# → L20: struct_def Store
#   L30: function init
#   L55: function recordSnapshot

# 3. Find a symbol across the codebase
curl "localhost:7719/symbol?name=AgentRegistry"
# → {"path":"src/agent.zig","line":30,"kind":"struct_def"}

# 4. Full-text search
curl "localhost:7719/search?q=handleAuth&max=10"

# 5. Check what changed
curl "localhost:7719/changes?since=42"

Measured on Apple M4 Pro, 48GB RAM. MCP = pre-indexed warm queries (20 iterations avg). CLI/external tools include process startup (3 iterations avg). Ground truth verified against Python reference implementation.

codedb repo (20 files, 12.6k lines):

merjs repo (100 files, 17.3k lines):

rtk-ai/rtk repo (329 files) — codedb vs rtk vs ripgrep vs grep:

codedb returns structured, relevant results — not raw line dumps. For AI agents, this means dramatically fewer tokens per query:

codedb v0.2.57 uses worker-local parallel scan with deterministic merge — each worker builds its own partial index, then results are merged on the main thread:

Indexes are built on startup and the watcher keeps them updated. The historical single-file indexing time above excludes event coalescing, polling delay, and queueing. Indexed queries reuse the index; live listing and fallback reads may access the filesystem. For repos >1000 files, file contents are released after indexing to save ~300-500MB.

The watcher stats .git/HEAD mtime before forking git rev-parse HEAD. These historical measurements do not bound watcher CPU under filesystem churn; see the issue #748 reproduction.

• MCP server indexes once on startup → all queries hit in-memory data structures (O(1) hash lookups)
• CLI pays ~55ms process startup + full filesystem scan on every invocation
• ast-grep re-parses all files through tree-sitter on every call (~3ms)
• ripgrep/grep brute-force scan every file on every call (~5-7ms)
• The MCP advantage: index once, query thousands of times at sub-millisecond latency

A map for the next step: structural parsers, search indexes, and a dependency graph in one Zig binary.

┌─────────────┐     ┌─────────────┐
│  HTTP :7719 │     │  MCP stdio  │
│  server.zig │     │  mcp.zig    │
└──────┬──────┘     └──────┬──────┘
       │                   │
       └───────┬───────────┘
               │
    ┌──────────▼──────────┐
    │     Explorer        │
    │   explore.zig       │
    │  ┌───────────────┐  │
    │  │ WordIndex      │  │
    │  │ TrigramIndex   │  │
    │  │ Outlines       │  │
    │  │ Contents       │  │
    │  │ DepGraph       │  │
    │  └───────────────┘  │
    └──────────┬──────────┘
               │
    ┌──────────▼──────────┐
    │      Store          │──── data.log
    │    store.zig        │
    └──────────┬──────────┘
               │
    ┌──────────▼──────────┐
    │     Watcher         │ ← OS events + overflow polling
    │   watcher.zig       │
    │  (FilteredWalker)   │
    └─────────────────────┘

No SQLite. No dependencies. Purpose-built data model:

• Explorer — structural index engine. Parses Zig, Python, TypeScript/JavaScript, Rust, Go, PHP, Ruby, HCL, R, and Dart. Maintains outlines, trigram index, inverted word index, content cache, and dependency graph behind a single mutex.
• Store — append-only version log. Every recorded file change (snapshot, modification, deletion) gets a monotonically increasing sequence number. Version history capped at 100 per file.
• Watcher — bounded OS watches, 100ms event coalescing, and content verification for overflow about every 2s. FilteredWalker prunes .git, node_modules, zig-cache, __pycache__, etc. before descending.
• Agents — first-class structs with cursors, heartbeats, and exclusive file locks. Stale agents reaped after 30s.

All threads share a shutdown: atomic.Value(bool) for graceful termination.

codedb collects anonymous usage telemetry to improve the tool. Telemetry is on by default — written to ~/.codedb/telemetry.ndjson and periodically synced to the codedb analytics endpoint. No source code, file contents, file paths, or search queries are collected — only aggregate tool call counts, latency, and startup stats.

codedb_context uses Pareto-frontier hybrid retrieval by default. Local BM25, trigram, symbol, and graph retrieval always runs first. Pass semantic=local for an entirely on-device call that sends no query or source text to an embedding service. In the default hybrid mode:

• local BM25/symbol retrieval still runs first and remains the failure-safe result;
• when a fresh local OpenPuffer sidecar exists, codedb sends the task plus a fixed public calibration string in one embedding request, verifies that the provider still represents the same vector space, and searches the stored code chunks locally through a validated mmap-backed graph;
• without a sidecar, codedb sends the task plus at most 24 locally selected relative paths and bounded snippets, capped at 2 KiB per path+snippet item / 8 KiB candidate text total, in one exact-rerank batch;
• the hosted codedb embedding service performs transient inference and does not retain request bodies, candidate paths, source snippets, or vectors;
• no repository archive or server-side repository/vector index is created;
• provider/network failure keeps the local result and never invokes a CPU embedding fallback.

Build a new local ANN explicitly with:

codedb /path/to/repo semantic-index

The managed default is now codedb-hosted-v1 at 512 dimensions. Clients through 0.2.5850 requested Qwen 0.6B; versions 0.2.5851–0.2.5856 requested Jina v2 code. The hosted service keeps those identifiers separate for existing clients. Old Qwen and Jina ANN sidecars fail the new model/vector-space check. For an exact former hosted-default sidecar, the first hybrid query uses bounded exact hosted reranking and schedules a single background rebuild. The old OpenPuffer generation stays intact until its replacement passes source, Git, metadata, and vector-space validation and commits atomically. Custom endpoints/model overrides and new repositories are never auto-built; set CODEDB_NO_AUTO_SEMANTIC_MIGRATION=1 to disable even this migration. CodeDB never mixes vectors from different models.

It splits already-indexable files into bounded 832-byte source chunks, uses eight concurrent 100-item requests by default (explicitly configurable from one to eight), and writes a small semantic-chunks-v3.meta mapping plus a generation-named .hmls mmap slab only in codedb's per-project local data directory. The directory and files use private permissions (0700/0600 on POSIX). On lookup, codedb checks model/vector-space identity, Git/content freshness, and the bounded metadata before opening the slab. Metadata heap use is capped at 64 MiB and graph-validation reads at 128 MiB; vector slabs remain demand-paged rather than being copied into the query process. It never scans or uploads .env, .env.*, .envrc, credentials, private keys, or other paths on the sensitive-file denylist. Ordinary lexical indexing does not build this sidecar.

The default managed semantic lane is free to call and requires no API token or manual setup. On first use, CodeDB creates a local Ed25519 installation key, enrolls its public key, and receives a short-lived server-signed certificate. Every request proves possession of the installation key; renewal is automatic. The private seed stays in a global ~/.codedb/credentials.json file written atomically with mode 0600 on POSIX and is never part of an embedding request. The public route exposes only the managed CodeDB lane, forwards bounded text to the managed embedding lane under CodeDB's zero-retention service policy, and enforces enrollment, installation, and aggregate network limits. General provider APIs remain authenticated.

format=json exposes this boundary in the retrieval object, including vector dimensions, bounded byte/document counts, retention policy, and failure policy. If CODEDB_EMBEDDINGS_URL points to a custom provider, codedb labels its retention as custom_endpoint_unverified because the client cannot prove another operator's storage policy.

Not stored: In explicit semantic=local mode, no source code is sent anywhere. In the default hybrid and explicit index-build modes, only the bounded transient batches above leave the machine; the hosted service does not store them and never creates a repository index. The optional ANN vectors and graph remain in the local codedb data directory. No file contents, file paths, or search queries are collected in telemetry. Sensitive files are auto-excluded from indexing and therefore cannot become hybrid candidates (.env, .env.*, .envrc, credentials.json, secrets.*, .pem, .key, SSH keys, AWS configs). The hybrid request builder repeats the canonical safe-path check immediately before serialization, so those paths remain blocked even if a stale or hand-built in-memory index contains one. Structured provenance reports only the aggregate sensitive_paths_blocked count, never the rejected path.

Optional custom-provider overrides (the managed lane needs none):

CODEDB_EMBEDDINGS_URL=https://provider.example/v1/embeddings
CODEDB_EMBEDDINGS_MODEL=your-deployment-id
CODEDB_EMBEDDINGS_DIMENSIONS=512
CODEDB_EMBEDDINGS_TOKEN='optional bearer token for a protected/custom endpoint'
CODEDB_EMBEDDINGS_TIMEOUT_MS=15000
CODEDB_SEMANTIC_INDEX_CONCURRENCY=4

To disable telemetry: set CODEDB_NO_TELEMETRY=1 or pass --no-telemetry.

To sync the local NDJSON file into Postgres for analysis or dashboards, use scripts/sync-telemetry.py with the schema in docs/telemetry/postgres-schema.sql. The data flow is documented in docs/telemetry.md.

codedb nuke                # uninstall binary, clear caches/snapshots, remove MCP registrations
rm -rf ~/.codedb/          # cache-only cleanup if you want to keep the binary installed
rm -f codedb.snapshot      # remove snapshot from current project only

Requirements: Zig 0.17.0-dev.813+2153f8143 (the exact tested development snapshot). See the migration guide for reproducible zigup setup.

git clone https://github.com/justrach/codedb.git
cd codedb
zig build                              # debug build
zig build -Doptimize=ReleaseFast       # release build
zig build test                         # run tests
zig build bench                        # run benchmarks

Binary: zig-out/bin/codedb

zig build -Doptimize=ReleaseFast -Dtarget=x86_64-linux
zig build -Doptimize=ReleaseFast -Dtarget=aarch64-linux
zig build -Doptimize=ReleaseFast -Dtarget=x86_64-macos
zig build -Doptimize=ReleaseFast -Dtarget=x86_64-windows

./release.sh 0.2.0              # build, codesign, notarize, upload to GitHub Releases
./release.sh 0.2.0 --dry-run    # preview without executing

See LICENSE for details.