codedb 是什么?

codedb 是一个用 Zig 编写的代码检索与 MCP 上下文服务。它在本机建立符号、全文、调用方和依赖索引,让编码 Agent 先拿到与任务相关的片段。它没有代码编辑能力,也不能证明检索到的调用链就是完整的运行时行为。

⭐ 1,193 Stars 🍴 70 Forks Zig BSD-3-Clause 作者: justrach
来源:github.com/justrach/codedb;https://github.com/justrach/codedb/blob/ma… 查看 GitHub 仓库 → 📘 使用教程 →

为什么值得关注

编码 Agent 在大型仓库里反复读整文件,会增加延迟和上下文消耗。codedb 把常用结构查询放进常驻索引,并通过 MCP 提供 context、explain、callpath、list_dir 和 status 等入口。

来源:github.com/justrach/codedb

核心功能

本地结构与全文索引

扫描仓库后维护 outlines、符号、trigram、word index 和依赖关系;文件变化会触发增量更新。

来源:github.com/justrach/codedb;https://github.com/justrach/codedb/blob/ma…
面向 Agent 的组合查询

codedb_context 按任务组合候选片段,codedb_explain 返回定义与调用方,codedb_callpath 查找两个符号间的已解析路径。默认只向客户端展示五个一站式工具,减少工具列表噪声。

来源:github.com/justrach/codedb
MCP、CLI 与本机 HTTP

同一索引可通过 MCP stdio、codedb CLI 或默认 localhost:7719 的可选 HTTP 服务查询。安装器会向检测到的多个客户端增量写入 MCP 配置。

来源:github.com/justrach/codedb;https://github.com/justrach/codedb/blob/ma…
本地或托管语义检索

semantic=local 不发送查询或源码;默认 hybrid 会向托管 embedding 服务发送任务,以及受限的路径和片段候选。JSON 输出会报告检索模式和数据边界。

来源:github.com/justrach/codedb

技术架构

codedb 扫描工作目录,把文件内容、outlines、trigram、倒排词索引和依赖关系放入每项目本地数据目录,并用文件监视器增量更新。MCP stdio、CLI 和可选 HTTP 服务共用检索核心。codedb_context 先做本地 BM25、符号和图检索;默认 hybrid 随后调用托管 embedding 路径,semantic=local 则保持全程本地。项目还会在 ~/.codedb 保存凭据和默认开启的聚合遥测日志。

来源:github.com/justrach/codedb;https://github.com/justrach/codedb/blob/ma…

项目知识图谱

知识图谱:项目核心节点(中心)+ 核心功能(内环六边形)+ 关键技术依赖(外环 chip) Zig 内存索引与本地持久化文件Zig 内存索引与… 可选托管 embedding 服务或本地 semantic 模式可选托管 embedd… MCP 客户端配置与可选 Claude Code hookMCP 客户端配置… 本地结构与全文索引 面向 Agent 的组合查询 MCP、CLI 与本机 HTTP 本地或托管语义检索 codedb 项目本体 核心功能 关键依赖

技术栈

语言Zig;npm 包只提供原生二进制启动器框架本地索引 + 文件监视器 + MCP/JSON-RPC + 可选 localhost HTTP
Zig 内存索引与本地持久化文件可选托管 embedding 服务或本地 semantic 模式MCP 客户端配置与可选 Claude Code hook
macOS、Linux 和 Windows 原生二进制;npm 包名 codedeebee;BSD 3-Clause 许可
来源:github.com/justrach/codedb;https://github.com/justrach/codedb/blob/ma…

快速上手

先从 GitHub Release 下载与平台匹配的 0.2.5856 资产和 checksums.sha256,在隔离目录核对 SHA-256,再运行 codedb --version。不要一开始执行远程脚本或让安装器写所有客户端;先手动给一个测试仓库配置 codedb mcp,并在查询中指定 semantic=local。用 status、outline、explain 和 callpath 抽查几条已知事实后,再决定是否启用默认 hybrid、遥测、hooks 和 DeepWiki。
来源:github.com/justrach/codedb;https://github.com/justrach/codedb/release…

使用场景

适合中大型代码库里的符号定位、调用方查询、依赖浏览、任务上下文压缩和跨客户端 MCP 复用。动态调用、反射、生成代码、运行时配置和未完整解析的语言会限制结构结果;安全审查、最终修改和测试仍需其他工具完成。

来源:github.com/justrach/codedb;https://github.com/justrach/codedb/blob/ma…

优势与局限

优势

  • 结构检索、索引和本地模式都可在设备上完成
  • MCP、CLI 与 HTTP 共用索引,能减少重复扫描
  • 提供符号、调用方、调用路径、全文和依赖等多种证据
  • 发布资产提供校验和,macOS 版本声明签名与公证

局限

  • 项目仍标为 Alpha,API、快照格式和行为可能变化
  • 默认 hybrid 会把任务及受限候选发送到托管 embedding 服务;完全本地需要显式选择 semantic=local
  • 匿名遥测默认开启,可用 CODEDB_NO_TELEMETRY=1 或 --no-telemetry 关闭
  • 安装器可能改写多个 MCP 客户端配置,并可注册 Claude Code hook 和 DeepWiki 远程 MCP
  • 官方速度与上下文 benchmark 来自项目方环境,不能直接外推到其他仓库
来源:github.com/justrach/codedb;https://github.com/justrach/codedb

最新版本

2026-09-23 核对的官方 main 提交与 npm manifest 标记版本 0.2.5856,main 提交日期为 2026-09-19。README 同时保留部分旧版本安装示例,因此实际下载前应以 GitHub Releases 的 Latest 标记和资产校验和交叉确认,不要只复制 main 中的版本字符串。

来源:github.com/justrach/codedb;https://github.com/justrach/codedb/blob/ma…

实测与证据

status: docs_and_source_checked_not_installed  |  checked_at: 2026-09-23  |  environment: 读取 justrach/codedb 官方 README、架构、MCP、benchmark、许可证、npm manifest,并浅克隆 2026-09-19 的官方 main;未执行安装脚本或二进制。  |  limitations: 没有验证二进制校验、索引速度、语言覆盖、调用路径正确率、文件监视、MCP 客户端写入、HTTP 安全、遥测关闭、hosted embedding 声明或 benchmark。  |  observed_output: main 的 npm/package.json 版本为 0.2.5856;README 把项目标为 Alpha,说明默认 hybrid 的托管 embedding 数据边界、默认遥测,以及 semantic=local 的全本地路径。

来源:github.com/justrach/codedb;https://github.com/justrach/codedb/blob/ma…

同类项目对比

相比 code-review-graph,codedb 更偏向常驻的低延迟代码导航和任务片段检索,提供 CLI、MCP 与本机 HTTP;code-review-graph 更强调持久化 SQLite 图、影响半径、执行流、测试关系和 CI 风险评论。要快速找符号与局部上下文可先试 codedb;要审查改动传播和测试缺口可先试 code-review-graph。两者的静态结果都要用测试和运行时证据复核。

来源:github.com/justrach/codedb;https://github.com/tirth8205/code-review-g…

总结评价

codedb 值得用一个非敏感测试仓库评估,但要先固定版本、手工核验资产、关闭不需要的遥测,并从 semantic=local 开始。只有当已知符号、调用方和路径的抽查可靠,且实际上下文确实减少,才适合扩展到主仓库。

来源:github.com/justrach/codedb;https://github.com/justrach/codedb

常见问题

codedb 默认是完全离线的吗?

不是。结构检索在本地,但默认 hybrid 可能把任务以及受限的候选路径和片段发送到托管 embedding 服务。明确使用 semantic=local 才是官方描述的全本地查询路径。

codedb 会收集源码或搜索词吗?

官方称默认遥测只含工具调用次数、延迟和启动统计,不含源码、路径和查询;不过遥测默认开启。需要关闭时设置 CODEDB_NO_TELEMETRY=1 或使用 --no-telemetry,并自行核对网络行为。

为什么不建议直接执行官方 curl 安装命令?

安装器会下载二进制,并可能给多个客户端写 MCP、hook 和远程服务配置。第一次更适合手动下载 release、核对 checksums.sha256,再只配置一个测试客户端。

codedb 的 callpath 能证明真实运行路径吗?

不能。它反映工具成功解析的静态关系;反射、动态导入、依赖注入、配置和外部服务可能不在图里,仍需测试、日志或 tracing 复核。

codedb 和 code-review-graph 怎么选?

主要需求是快速符号、全文和任务上下文检索时先试 codedb;主要需求是影响范围、执行流、测试关系和 CI 评论时先试 code-review-graph。应在同一组真实任务上比较正确率、耗时和数据边界。

资料与核验范围
本文依据项目公开资料整理。版本、安装命令和功能边界可能随上游更新,请以所列来源和项目当前版本为准。 资料核对时间: 2026-09-23 13:55.

参考材料:README、GitHub API、依赖文件