keelyard

keelyardは、AIコーディングエージェント（Claude Code、Codex CLI、 OpenCode）がテストの合格によって作業が証明されるまで完了できないようにする、オープンソースのコマンドラインツール兼MCP サーバーです。編集内容をすべてスナップショットに保存するため、どのステップも取り消せます。また、ノイズの多いツール出力を削減し、セッションで使うトークンを減らします。ローカルで動作し、テレメトリーはありません。

理由

コーディングエージェントは高速ですが、テストがまだ失敗しているのに「完了」としてセッションを終えることがあり、失敗していたテスト自体を削除することもあります。keelyardはエージェントとリポジトリの間に位置します。

• テストが現在のファイルで合格するまで、セッションを終了させません。
• 編集内容をすべてスナップショットに保存するため、問題のあるステップも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 に作業を再開させます。証明となるのは、Codex 自身のシェルで実行したテストです。すべての編集はスナップショットに保存されるため、keelyard rewind to <n> で問題のある手順を元に戻せます。 scripts/codex_e2e.py により Codex CLI 0.165.0 で確認済みです。実際の Codex バイナリとローカルのスクリプトモデルを使い、API キーなしで、プッシュのたびに CI で実行しています。 Codex を 2 分で →

Claude Code でも動作： keelyard init --agent claude は .claude/settings.json のフック、.mcp.json、CLAUDE.md ブロックを書き込みます。scripts/claude_e2e.py により Claude Code 2.1.197 で確認済みです。API キーは不要で、プッシュのたびに CI で実行しています。Claude Code を 2 分で →（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 プロジェクトは、最初のエージェントセッションで自動的にセットアップされます（設定と最初のスナップショット）。プロジェクトごとにほかの作業を実行する必要はありません。
• 確認：keelyard doctor --json が "ok": true を返し、設定済みのエージェントごとに global 行が表示されるはずです。その後、エージェントを再起動してください。
• 取り消し：keelyard uninstall --global。

AI コーディングエージェント向け： ユーザーから明示的に依頼された場合に限り、keelyard をインストールしてください。上記のコマンドと、変更されるファイルをユーザーに示し、ユーザーの確認後にのみ実行してください。詳細：AGENTS-install.md。

録画では、エージェントがテストを 3 つ削除してテストをすべて成功させ、その後停止しようとします。keelyard がこれを阻止し、rewind to 2 でテストが復元され、セッションは実際の証拠を残して終了します。出力のすべての行が実際のものです（エージェントによる編集は 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?

いつもどおりエージェントを使ってください。keelyard status では証拠とタイムラインを確認でき、keelyard uninstall <agent> では設定ファイルをバイト単位で元どおりに戻せます。PyPI リリースではなく最新の main を使う場合： pipx install git+https://github.com/akobirjontulqinovfuture/keelyard。

実際の実行結果（OpenCode 2、Windows、無料モデル、$0）： lean プリセットを使うと、入力トークンのセッションあたり平均数は、ノイズの多い 1,566 テストのタスクで 14.2 倍、小規模な 66 テストのタスクで 6.0 倍 減少しました（ベースライン 5 回、lean 3 回の実行で、すべてのテストに合格）。キャッシュされていない入力だけでは、それぞれ 9.5 倍、4.5 倍です。lean は一部のエージェントツールをオフにします。コストに関する主張ではありません。モデルは無料でした。 BENCHMARKS.md

keelyard がマシン上で変更するもの

変更するファイル、ネットワークの使用状況、アンインストール方法

• keelyard init / install <agent>（プロジェクト）または keelyard init --global（ユーザーレベル）を実行したときのみです。 pip のインストール時には何も書き込まれません。インストールスクリプトやインストール後のフックもありません。
• 編集するエージェント設定：フックと MCP エントリー（.claude/settings.json、.mcp.json、.codex/hooks.json、 opencode.json、または --global を指定した場合は ~/ 内の同等のファイル）と、CLAUDE.md / AGENTS.md の と の間のブロックです。元のファイルは <file>.keelyard-backup として保持されます。
• プロジェクトの状態は .keelyard/（設定、shadow.git スナップショット）に保存されます。スナップショットには別の git ディレクトリを使います。 巻き戻しによって、独自の .git が読み書きされることはありません。
• メモリ：$XDG_DATA_HOME/keelyard/memory.db（モード 600、機密情報は除去されます）。
• ネットワーク：デフォルトでは使用せず、テレメトリもありません。モデルエンドポイントを呼び出すのは swarm / coop のみで、呼び出し先は設定したエンドポイントだけです。
• アンインストール： keelyard uninstall <agent>（プロジェクト）または keelyard uninstall --global を実行し、その後 pipx uninstall keelyard を実行します。スナップショットも削除する場合は .keelyard/ を削除してください。

機能

• 証明ゲート。 ファイルを変更したエージェントは、現在のファイルでテストに合格するまで完了できません。 証拠はテストで検証済み、コマンド成功、エージェント申告のいずれかとして表示されます。テストの削除、新たな skip / xfail、アサーションの削除、テスト設定の変更、実行テスト数の減少があると、証明は完了しません。バンドルには署名が付与されます。
• 巻き戻し。 編集のたびに .keelyard/shadow.git にスナップショットが作成されます（独自の .git は変更されません）。 keelyard rewind to <n> 自体も取り消し可能で、スナップショットに保存できないファイルをバックアップし、中断されても復旧できます。 シークレット（.env、キー）はスナップショットに保存されません。
• コンテキストの縮小。 テストランナー、git、リンター、検索の出力をフィルタリングし、すべてのエラー、警告、file:line を保持します （実際のログでテスト済み）。JSON 出力は情報を失わずに圧縮されます。変更のないファイルを再読込するコストは 1 行です。 エージェントには結果のみを回答するよう指示されます（無効にするには --no-terse を指定）。
• メモリ、使用状況、スウォーム、アリーナ。 3 つのエージェントすべての過去のセッションを検索し、ローカルログからトークン使用量を確認できます。また、無料または安価なモデルに小規模な検証済みタスクを送信したり、1 つのタスクでエージェントを比較したりできます。

keelyard なしの場合とある場合

	keelyard なし	keelyard あり
エージェントが「完了」と報告	それを信じて、あとから自分でテストを実行します	現在のファイルでテストに合格するまで停止できず、証明も表示されます
エージェントが失敗するテストを削除またはスキップ	長い差分の中では見落としやすいです	テスト数の減少、新たな skip / xfail、アサーションの削除があると証明は完了しません
ある手順で何かが壊れる	タイミングよくコミットしていれば、git stash / 手動で元に戻します	keelyard rewind to <n> を実行でき、巻き戻し自体も取り消せます
3,000 行のテスト成功出力	すべてがコンテキストウィンドウに入ります	エラー、警告、file:line は保持され、その他は折りたたまれます

各エージェントとの連携方法

エージェント	フック（ゲート、スナップショット、フィルター）	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 が保証することと、保証しないことをお読みください。要約すると、 スナップショットで元に戻せるのはファイルであり、データベース、マイグレーション、デプロイ済みサービスは対象外です。また、証明の確かさはテストの品質に左右されます。

エージェントとスクリプト向け

MCP サーバー（型付きツールと使用例）、短い CLAUDE.md／AGENTS.md セクション、Claude Code 向けのスキルとスラッシュコマンドを用意しています。すべての CLI コマンドで --json を使用できます。終了コードは、0 が成功、1 がエラー、2 が使い方の誤り、3 がチェックの失敗です。

ドキュメント

ドキュメント：各モジュールのページ、CLI と MCP のリファレンス、設定、トラブルシューティング、 ベンチマーク、エージェントごとの機能。

インスピレーション

keelyard のアイデアの形成に影響したプロジェクト（コードのコピーはありません）

コードではなく、アイデアを参考にしています。keelyard のコードはすべてゼロから書かれています。 rtk（コマンド出力のフィルタリング）、 caveman と SuperClaude（簡潔な出力）、 headroom（コンテンツを考慮した圧縮、キャッシュで安定するコンテキスト）、 projectmem（失敗した試行を繰り返す前の警告）、 planning-with-files と context-mode（コンパクション後も保持される状態）、 aider（リポジトリマップ）、claude-mem （セッションメモリ）、ccusage（ローカルログからの使用状況）、 cline（チェックポイント）に感謝します。調査結果：docs/research/ideas.md。

コントリビューション

CONTRIBUTING.md とロードマップをお読みください。 good first issue ラベルの付いた Issue から始めるのがおすすめです。フィルター用コーパスに使える実際のコマンドログも歓迎します。 セキュリティに関する問題：SECURITY.md。ライセンスは Apache-2.0 です。サードパーティに関する通知はNOTICEにあります。