codedb

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/images/codedb-map-dark.png" />
    <source media="(prefers-color-scheme: light)" srcset="docs/images/codedb-map-light.png" />
    <img src="docs/images/codedb-map-light.png" alt="A cobalt-coated workshop rat maps a repository: source files become islands linked by symbols, callers, and dependencies." width="960" />
  </picture>
</p>

<h1 align="center">codedb</h1>
<h3 align="center">Big repo. Little map. Find the code that matters.</h3>

<p align="center">
  Code intelligence for your coding agent. Built in Zig. Connected over MCP.
</p>

<p align="center">
  <a href="https://github.com/justrach/codedb/releases/latest"><img src="https://img.shields.io/github/v/release/justrach/codedb?style=flat-square&label=release&color=2654d9" alt="Latest release" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/justrach/codedb?style=flat-square&color=d45a43" alt="License" /></a>
  <img src="https://img.shields.io/badge/built_in-Zig-f7a63b?style=flat-square" alt="Built in Zig" />
  <img src="https://img.shields.io/badge/macOS_·_Linux_·_Windows-1b1714?style=flat-square" alt="macOS, Linux, Windows" />
</p>

<p align="center">
  <a href="https://trendshift.io/repositories/26207?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-26207" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/26207" alt="justrach/codedb | Trendshift" width="250" height="55" /></a>
</p>

<p align="center">
  <a href="#-install">Install</a> ·
  <a href="#-quick-start">Quick start</a> ·
  <a href="#-mcp-tools">Tools</a> ·
  <a href="#-benchmarks">Benchmarks</a> ·
  <a href="#-data--privacy">Data & privacy</a> ·
  <a href="#-use-codedb-in-harness">Harness</a> ·
  <a href="https://codegraff.com/codedb?from=codedb-readme">Meet the family ↗</a>
</p>

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.

## 🧭 Give your agent a compass

| Ask your agent… | codedb helps it… |
| --- | --- |
| “Where does session refresh happen?” | Find relevant files and source excerpts with `codedb_context` |
| “Explain this function and who uses it.” | Read the definition and callers with `codedb_explain` |
| “How does this request reach the database?” | Trace a chain between symbols with `codedb_callpath` |
| “What's in this part of the repo?” | Browse with `codedb_list_dir` and inspect file outlines |

Structural search