codedb (Justrach)

codedb

Code intelligence server for AI agents. Zig core. MCP native. Zero dependencies.

Structural indexing · Trigram search · Word index · Dependency graph · File watching · MCP + HTTP

Status · Install · Quick Start · MCP Tools · Benchmarks · Architecture · Data & Privacy · Building

______________________________________________________________________

状态

Alpha软件-API正在稳定，但可能会发生变化 codedb在生产AI工作流程中每天都在工作和使用，但是： - 解析器支持 --Zig、C/C++、Python、TypeScript/JavaScript、Rust、Go、PHP、Ruby、HCL、R、Dart/Flutter - 轻质轮廓支撑 --Java、Kotlin、Svelte、Vue、Astro、shell、CSS/SCSS、SQL、protobuf、Fortran、LLVM IR、MLIR和TableGen - 无需认证 --HTTP服务器仅绑定到本地主机 - 快照格式 版本之间可能会发生变化 - MCP协议 JSON-RPC 2.0是否优于stdio（稳定）

______________________________________________________________________

⚡ 安装

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

下载适用于您平台的二进制文件，并将codedb自动注册为MCP服务器 克劳德代码, 法典, Gemini CLI，以及 光标。安装程序会打印出确切的 codedb mcp 命令它为Codex和Claude Code注册了钩子设置指针。

更新或修复旧安装

如果 codedb update 在旧版本上失败，请重新运行安装程序：

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

这取代了 codedb 使用最新GitHub版本的二进制文件，并保留您现有的MCP注册、配置、缓存和快照。对于其内置更新程序无法获取版本校验和的任何版本，请使用此路径。

v0.2.579 MCP修补程序和发布校验和

本说明适用于 v0.2.579 只有。早些时候 v0.2.579 二进制文件已重建 并于2026年5月2日重新上传，因为它们通过了正常的Zig测试套件，但 错过了MCP端到端回归：之后 codedb_index 报告成功， 后续的MCP查询仍然可以看到一个空的内存项目(files: 0, scan: loading_snapshot，空 tree/find/search，或 file not indexed).

固定 v0.2.579 从源代码提交重建了发布资产 1b634f0ba5cd1072e9ca54cabf442b573e034f53。以下值为SHA256 上传的二进制文件的校验和，而不是Git提交SHA：

如果您已安装 v0.2.579 在此修补程序之前，请重新运行上面的安装程序，以便 二进制文件与您平台的最终上传校验和相匹配。

或从以下位置手动安装 .

______________________________________________________________________

⚡ 快速开始

作为MCP服务器（推荐）

安装后，codedb会自动注册。只需打开一个项目，您的AI代理就可以使用16个MCP工具。

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

作为HTTP服务器

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

______________________________________________________________________

🔧 MCP工具

基于模型上下文协议的16个工具（基于stdio的JSON-RPC 2.0）：

codedb_remote --云智能

查询任何索引的公共GitHub仓库，而无需克隆它。 codedb_remote 始终使用 api.wiki.codes；老人 codegraff 后端名称不再是受支持的路由。省略 backend，或保持 backend="wiki" 仅适用于较旧的提示。

# 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"

远程操作： actions, tree, outline, search, read, symbol, policy, deps, score, cves, commits, branches, dep-history

有关Codex和Claude Code的示例 codedb_remote，请参阅 docs/hooks-labs.md.

注： 此工具调用 https://api.wiki.codes。不需要API密钥。该仓库必须已被公共服务索引。

CLI命令

选项： --no-telemetry （或设置 CODEDB_NO_TELEMETRY 任何人）

示例：代理探索代码库

# 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"

______________________________________________________________________

📊 基准测试

在苹果M4 Pro上测量，48GB RAM。MCP=预索引热查询（平均20次迭代）。CLI/外部工具包括进程启动（平均3次迭代）。根据Python参考实现验证了基本事实。

延迟——codedb MCP vs codedb CLI vs ast grep vs ripgrep vs grep

codedb仓库 （20个文件，12.6k行）：

merjs仓库 （100个文件，17.3k行）：

rtk ai/rtk回购 （329个文件）--codedb vs rtk vs ripgrep vs grep：

令牌效率

codedb返回结构化的相关结果，而不是原始行转储。对于AI代理来说，这意味着每次查询的令牌要少得多：

索引速度

codedb v0.2.57使用带有确定性合并的worker本地并行扫描——每个worker构建自己的部分索引，然后在主线程上合并结果：

索引在启动时构建一次。之后，文件观察器会逐步更新它们（单个文件重新索引： **\1000个文件，文件内容在索引后发布，可节省约300-500MB。

后台资源使用情况(openclaw，6315个文件，苹果M4 Pro）

观察者现在统计 .git/HEAD 分叉前的时间 git rev-parse HEAD在空闲的仓库中，子流程从不启动。

为什么codedb很快

• MCP服务器 启动时索引一次→ 所有查询都命中内存中的数据结构（O（1）哈希查找）
• 命令行界面 每次调用时支付~55ms的进程启动+完整的文件系统扫描
• ast grep 每次调用时都会通过树状图重新解析所有文件（约3ms）
• ripgrep/grep 每次调用时暴力扫描每个文件（~5-7ms）
• MCP优势： 索引一次，查询数千次，延迟低于毫秒

特征矩阵

codedb=树形图+搜索索引+依赖图+代理运行时。 零外部依赖。纯粹的Zig。单二进制。

______________________________________________________________________

🏗️ 建筑

┌─────────────┐     ┌─────────────┐
│  HTTP :7719 │     │  MCP stdio  │
│  server.zig │     │  mcp.zig    │
└──────┬──────┘     └──────┬──────┘
       │                   │
       └───────┬───────────┘
               │
    ┌──────────▼──────────┐
    │     Explorer        │
    │   explore.zig       │
    │  ┌───────────────┐  │
    │  │ WordIndex      │  │
    │  │ TrigramIndex   │  │
    │  │ Outlines       │  │
    │  │ Contents       │  │
    │  │ DepGraph       │  │
    │  └───────────────┘  │
    └──────────┬──────────┘
               │
    ┌──────────▼──────────┐
    │      Store          │──── data.log
    │    store.zig        │
    └──────────┬──────────┘
               │
    ┌──────────▼──────────┐
    │     Watcher         │ ← polls every 2s
    │   watcher.zig       │
    │  (FilteredWalker)   │
    └─────────────────────┘

没有SQLite。没有依赖关系。 专门构建的数据模型：

• 探索者 --结构索引引擎。解析Zig、Python、Types/JavaScript、Rust、Go、PHP、Ruby、HCL、R和Dart。维护单个互斥体后面的大纲、三元组索引、倒排词索引、内容缓存和依赖关系图。
• 商店 --仅附加版本日志。每个突变（快照、编辑、删除）都会得到一个单调递增的序列号。版本历史记录限制为每个文件100个。
• 观察者 --轮询文件监视器（间隔2秒）。 FilteredWalker 西梅干 .git, node_modules, zig-cache, __pycache__在下降之前。
• 代理 --具有游标、心跳和独占文件锁的一级结构。30多岁后，老特工们收获颇丰。

线程模型

所有线程共享一个 shutdown: atomic.Value(bool) 以优雅的方式结束。

______________________________________________________________________

🔒 数据和隐私

codedb收集匿名使用遥测数据以改进该工具。遥测是 默认开启 --写信给 ~/.codedb/telemetry.ndjson 并定期同步到codedb分析端点。 不收集源代码、文件内容、文件路径或搜索查询 --仅聚合工具调用计数、延迟和启动统计信息。

未存储： 源代码不会发送到任何地方。遥测中不会收集文件内容、文件路径或搜索查询。自动排除敏感文件(.env*, credentials.json, secrets.*, .pem, .keySSH密钥、AWS配置）。

要禁用遥测：设置 CODEDB_NO_TELEMETRY=1 或通过 --no-telemetry.

要将本地NDJSON文件同步到Postgres进行分析或仪表板，请使用 scripts/sync-telemetry.py 模式在 docs/telemetry/postgres-schema.sql数据流记录在 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

______________________________________________________________________

🔨 从源代码构建

要求： Zig 0.15+

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

二元的： 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

释放

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

______________________________________________________________________

许可证

看 许可证 了解详情。