keelyard

keelyard 是一款开源命令行工具和 MCP 服务，它会阻止 AI 编码 Agent（Claude Code、Codex CLI、 OpenCode）在通过测试证明工作成果之前结束任务；它会为每次编辑创建快照，以便撤销任意步骤， 还会精简冗杂的工具输出，减少会话的 token 用量。它在本地运行，不收集遥测数据。

缘由

编码 Agent 速度很快，但它们常在测试仍然失败时就以“完成”结束会话，有时还会删除导致失败的测试。keelyard 位于 Agent 和代码仓库之间：

• 直到当前文件通过测试，会话才能结束；
• 每次编辑都会创建快照，只需执行 keelyard rewind to <n> 即可回退错误步骤；
• 精简冗杂的输出，让上下文窗口留住错误信息，而不是 3,000 行通过测试的输出。

仅在本地运行，不收集遥测数据，采用 Apache-2.0 许可证。

适用于 Codex

pipx install keelyard && cd your-project
keelyard init --agent codex --codex-project-mcp
codex

init 会写入钩子、MCP 服务条目和 AGENTS.md 区块；在 Codex 中，输入一次 /hooks 即可信任这些钩子。之后 Codex 会照常工作。如果它在测试失败或未运行时说“完成”，keelyard 的 Stop 钩子会让它继续；在 Codex 自己的 shell 中运行测试才是证明。每次编辑都会创建快照，因此 keelyard rewind to <n> 可以撤销错误步骤。 通过 scripts/codex_e2e.py 在 Codex CLI 0.165.0 上完成检查：使用真实 Codex 二进制文件和本地脚本模型，无需 API 密钥，并在每次推送时于 CI 中运行。 2 分钟了解 Codex →

适用于 Claude Code： keelyard init --agent claude 会写入 .claude/settings.json 钩子、.mcp.json 和 CLAUDE.md 区块。通过 scripts/claude_e2e.py 在 Claude Code 2.1.197 上完成检查，每次推送时于 CI 中运行，无需 API 密钥。2 分钟了解 Claude Code →（OpenCode 也适用）

安装

pipx install keelyard   # or: python -m pip install --user keelyard
keelyard init --global
keelyard doctor --json

• init --global 会为每个项目配置 Claude Code（~/.claude/settings.json、~/.claude.json）、Codex（~/.codex/config.toml、~/.codex/hooks.json）和 OpenCode（~/.config/opencode/）。它会合并到现有文件中，并将原文件保留为 <file>.keelyard-backup。
• 每个 Git 项目会在首次 Agent 会话时自行完成设置（配置和首个快照）。每个项目无需再运行其他命令。
• 检查：keelyard doctor --json 应返回 "ok": true，并为每个已配置的 Agent 显示一行 global。然后重启你的 Agent。
• 撤销：keelyard uninstall --global。

面向 AI 编码 Agent： 只有在用户明确要求时才安装 keelyard。向用户展示上述命令以及这些命令会修改的文件，并且只在用户确认后运行。详情：AGENTS-install.md。

在这段录屏中，Agent 删除了三个测试来让测试通过，随后试图停止。keelyard 阻止了它，rewind to 2 恢复了这些测试，最终会话以真实证据收尾。每一行输出都是真实的（Agent 的编辑操作均根据 docs/demo/hero.sh 重放）。

快速开始（30 秒）

pip install keelyard          # or pipx install keelyard
cd your-project
keelyard init --preset lean   # wires Claude Code, Codex and OpenCode; fewest tokens
keelyard doctor               # everything green?

照常使用你的 Agent。keelyard status 会显示证明和时间线；keelyard uninstall <agent> 会逐字节还原你的配置文件。要安装最新的 main 而非 PyPI 发行版： pipx install git+https://github.com/akobirjontulqinovfuture/keelyard。

真实运行（OpenCode 2、Windows、免费模型、$0）： 使用精简预设后，在一个包含 1,566 个测试的繁杂任务中，每次会话的平均输入 token 数下降了 14.2×；在一个包含 66 个测试的小型任务中下降了 6.0×（基线运行 5 次，精简运行 3 次，所有测试均通过）。仅未缓存的输入分别下降了 9.5× 和 4.5×。精简预设会关闭部分 Agent 工具。不声称节省成本：模型是免费的。 BENCHMARKS.md

keelyard 会在你的机器上进行哪些更改

它会操作哪些文件、如何使用网络，以及如何卸载

• 仅当你运行 keelyard init / install <agent>（项目级）或 keelyard init --global（用户级）时才会进行更改。 pip 安装时不会写入任何内容；没有安装脚本或安装后钩子。
• 它会编辑 Agent 配置：钩子和 MCP 条目（.claude/settings.json、.mcp.json、.codex/hooks.json、 opencode.json，或使用 --global 时对应的 ~/ 路径），以及 CLAUDE.md / AGENTS.md 中由 和 包围的区块。原始文件会保留为 <file>.keelyard-backup。
• 项目状态存放在 .keelyard/ 中（配置、shadow.git 快照）。快照使用单独的 git 目录； rewind 永远不会读取或写入你自己的 .git。
• 记忆：$XDG_DATA_HOME/keelyard/memory.db（权限模式为 600，经过脱敏）。
• 网络：默认不使用网络，也没有遥测。只有 swarm / coop 会调用模型端点，而且只调用你配置的端点。
• **卸载：**运行 keelyard uninstall <agent>（项目级）或 keelyard uninstall --global，然后 运行 pipx uninstall keelyard；如果想删除快照，也可以删除 .keelyard/。

功能

• 证明门禁。 修改过文件的 Agent 必须等到当前文件通过测试才能结束。 证据会标记为测试已验证、命令已成功或 Agent 声称。删除测试、新增 skip / xfail、移除断言、更改测试配置以及减少测试运行数量都会让证明保持未完成状态。证明包会经过签名。
• 回退。 每次编辑都会快照到 .keelyard/shadow.git（绝不会触碰你自己的 .git）。 keelyard rewind to <n> 操作本身也可以撤销，会备份快照无法保存的文件，并且即使中断也能恢复。 绝不会对机密文件（.env、密钥）创建快照。
• 缩小上下文。 对测试运行器、git、代码检查工具和搜索结果进行过滤，保留所有错误、警告和 file:line （已在真实日志上测试）。JSON 输出会无损压缩。重新读取未更改的文件只需一行上下文。 Agent 会收到只回答结果的指示（退出此模式：--no-terse）。
• 记忆、用量、swarm、arena。 搜索三个 Agent 过去的会话，查看本地日志中的 token 用量，将小型且经过检查的任务发送给免费的 / 低价模型，并比较 Agent 执行同一任务的表现。

不使用与使用 keelyard 的对比

	不使用	使用 keelyard
Agent 说“完成了”	你只能相信它，然后自己运行测试	当前文件通过测试后它才能结束；证明会展示出来
Agent 删除或跳过失败的测试	在很长的差异中很容易漏看	测试数量减少、新增 skip / xfail 或移除断言都会让证明保持未完成状态
某个步骤导致问题	如果及时提交了，可以运行 git stash / 手动撤销	运行 keelyard rewind to <n>，而且回退操作本身也可以撤销
3,000 行通过测试的输出	全部进入上下文窗口	保留错误、警告和 file:line，其余内容会折叠

它如何接入各个 Agent

Agent	钩子（门禁、快照、过滤）	MCP 服务
Claude Code	.claude/settings.json	.mcp.json
Codex	.codex/hooks.json（尚未在实际运行的 Codex CLI 上验证，参见 #7）	~/.codex/config.toml（或使用 --codex-project-mcp 时的 .codex/config.toml）
OpenCode	.opencode/plugins/keelyard.js	opencode.json

keelyard init 会为你写入这些配置；keelyard doctor 会检查它们。

在依赖 keelyard 之前，请阅读keelyard 能保证什么、不能保证什么。简而言之： 快照可以撤销文件更改，但不能撤销数据库、迁移或已部署服务的更改；证明的可靠性取决于你的测试。

面向 Agent 和脚本

一个 MCP 服务（包含示例的类型化工具）、一段简短的 CLAUDE.md/AGENTS.md 内容，以及适用于 Claude Code 的技能 和斜杠命令。每条 CLI 命令都接受 --json；退出代码：0 表示成功，1 表示错误，2 表示用法错误，3 表示检查失败。

文档

文档：每个模块各有一页，包含 CLI 和 MCP 参考、配置、故障排除、 基准测试、各 Agent 的功能。

灵感来源

为 keelyard 提供设计灵感的项目（未复制代码）

借鉴的是思路，而非代码：keelyard 中的所有内容都是从头编写的。感谢 rtk（过滤命令输出）、 caveman 和 SuperClaude（简洁输出）、 headroom（内容感知压缩、缓存稳定的上下文）、 projectmem（在重复失败尝试前发出警告）、 planning-with-files 和 context-mode（压缩后仍能保留的状态）、 aider（代码仓库映射）、claude-mem （会话记忆）、ccusage（从本地日志统计用量）以及 cline（检查点）。调研：docs/research/ideas.md。

贡献

请阅读 CONTRIBUTING.md 和路线图。标记为 适合新手的问题是很好的起点。尤其欢迎提供用于过滤语料库的真实命令日志。 安全问题：SECURITY.md。采用 Apache-2.0 许可；第三方声明见 NOTICE。