codeledger

CodeLedger

在 AI 编码 Agent 开始工作前，为其提供合适的代码库上下文，然后验证 变更内容。

CodeLedger 是一款以本地为先的 AI 编码 Agent 上下文控制工具。它会扫描代码库，筛选出数量有限且与任务相关的文件集，并在 Agent 开始工作前生成一份有证据支持的上下文包。

可与 Claude Code、Codex、Cursor、GitHub Copilot、Gemini CLI 及其他 CLI 或兼容 MCP 的编码 Agent 配合使用。

试用

npm install -g @codeledger/cli
cd your-project
codeledger ready --task "Fix null handling in user service"

如果需要，CodeLedger 会初始化代码库、刷新索引，并在 .codeledger/active-bundle.md 中创建任务专属的上下文包。你的 Agent 会先读取该文件，以便一开始就获取与任务最相关的文件。

默认情况下，运行时分析在本地进行。安装或更新时可能会从 npm 和 GitHub Releases 获取软件包或发布产物；默认情况下，CodeLedger 运行时分析不会通过 CodeLedger 遥测发送你的源代码。

基准测试示例

一个中型 Node.js 服务的示例结果。结果因代码库、任务、Agent 和场景而异。

指标	不使用 CodeLedger	使用 CodeLedger	变化
测试通过率	78%	94%	+16%
迭代次数	4	2	-50%
修改文件数	17	9	-47%
完成时间	6m 12s	3m 40s	-41%
Token 用量	28k	18k	-36%

不要盲目相信基准测试——在你自己的代码库中衡量 CodeLedger 的效果：

codeledger compare \
  --scenario .codeledger/harness/scenarios/auth-rate-limit.json \
  --guided

如果 CodeLedger 改善了你的编码 Agent 工作流，请为代码库点星，以关注最新发布并帮助其他开发者发现它。

从这里开始

• 快速入门
• CLI 参考
• 工作原理
• MCP 服务
• 功能层级
• 安全
• 贡献指南
• 最新版本
• npm 软件包

工作原理

1. CodeLedger 会扫描代码库，获取确定性的本地信号，例如依赖结构、变更频率、测试、契约和任务关键词。
2. 它会为数量有限且与任务相关的文件评分并打包。
3. 它会为你的编码 Agent 生成 .codeledger/active-bundle.md。
4. 工作完成后，验证、记录和会话摘要有助于展示变更内容，以及所选上下文是否有用。

相同的任务和代码库状态会产生相同的文件排名结果。

核心功能

• **为 Agent 提供合适的上下文：**确定性的文件选择、范围推断、预算上限、影响范围提示和协同变更上下文。
• **保持工作连续性：**会话摘要、检查点、会话中途优化，以及交接／恢复命令。
• **让 Agent 专注于任务：**范围契约、意图治理、循环检测和多 Agent 冲突检查。
• **证明工作内容：**审查智能、记录、来源信息、审计导出和发布证据。

完整的命令列表请参阅 CLI 参考。

Agent 集成

在运行 codeledger ready 初始化代码库后，Claude Code 可以使用 CodeLedger 钩子。Cursor、Codex、GitHub Copilot、Gemini CLI、Aider、Windsurf 及其他 Agent 可以读取 CLAUDE.md 和 .codeledger/active-bundle.md，也可以在可用时使用代码库本地包装器。

CodeLedger 还为支持的功能层级提供 MCP 服务：

codeledger mcp start
codeledger mcp status

有关设置和功能层级的详情，请参阅 MCP 服务 和 功能层级。

信任与验证

• 默认情况下，运行时源代码分析在本地进行。
• 默认情况下，源代码不会通过 CodeLedger 遥测发送。
• 使用本地 CLI 流程无需账户。
• 公开版本包含 SHA256SUMS 和发布证据制品。
• codeledger doctor 会检查本地安装、钩子、配置、索引和账本的健康状况。
• 本仓库中的公开封装程序、文档、测试框架和扫描功能均可检查；受保护的强化运行时由 LICENSE-CORE 约束。

安装

npm install -g @codeledger/cli
codeledger --version

也可以使用发布压缩包：

1. 下载最新版本。
2. 解压。
3. 运行 install.sh。

安装程序会使用压缩包中附带的软件包，因此安装的封装程序版本与发布版本一致。随后，封装程序会从 GitHub 发布页面获取匹配的强化二进制文件，除非你的环境已提供该文件。

日常流程

cd your-project
codeledger ready
codeledger ready --task "Fix null handling in user service"

在已初始化的仓库中，也可以使用：

codeledger activate --task "Fix null handling in user service"
codeledger doctor

浏览器、云端和沙盒环境可以在初始化或引入代码后，使用部署在 .codeledger/bin/ 下的仓库本地运行时。

架构

CodeLedger 采用开放的公开功能层和受保护的强化运行时：

PUBLIC:    CLI wrapper, types, repo scanner, harness, reports, docs, hooks
PROTECTED: Scoring engine, selection algorithm, confidence internals

使用 codeledger about、codeledger doctor 和特定命令的 --explain 输出，在不暴露受保护的实现内部细节的情况下检查行为和证据。

隐私

• 安装过程可能会使用 npm 和 GitHub Releases。
• 默认情况下，运行时分析在你的本地计算机上进行。
• 默认情况下，运行时分析不会发起任何源代码遥测调用。
• 使用本地 CLI 流程无需将源代码传出你的计算机。
• 可随时卸载。

许可证

• 公开封装程序、类型、仓库扫描、测试框架、报告、文档和示例：MIT
• 下载的强化二进制文件：CodeLedger Core License

由于仓库同时包含受 MIT 许可约束的公开文件和受单独许可条款约束的运行时保护组件，GitHub 可能会将组合许可结构归类为“Other”。更改许可证文件应由法律专业人员作出决定。

ContextECF 的组成部分

CodeLedger 将 Intelligent Context AI 的上下文控制架构应用于软件工程。如需了解跨应用和 Agent 的企业级受治理上下文，请参阅 ContextECF。

CodeLedger 由 Intelligent Context AI, Inc. 制作。请访问 codeledger.dev。