keel

keel

AI コーディングエージェント向けの、可観測な自律性ハーネスです。 — TokenDrift による提供

keel は MCP サーバーです。コーディングエージェント（Claude Code、Cline など）に、逸脱したり、不正をしたり、作業を失ったりすることなく、タスクを最初から最後まで進めるツールを提供し、実行内容をすべて記録して、コストと品質を管理できるようにします。

タスクを開始するのはあなたです。エージェントは自らを律します。戻ってくると、マイルストーンのレポートが確認できます。

名前の由来：キールは、船の水面下にある、目には見えない部分です。船の背骨のような役割を果たし、風に吹き流されないようにします。それが keel の役目です。

---

課題

長いタスクをエージェントに任せきりにすると、手遅れになるまで気付けない問題が4つ起こりがちです。

• 作業の筋道を見失います。 コンテキストが圧縮され、以前の決定が忘れられ、作業がやり直されたり、矛盾したりします。
• 不正をします。 「テストを通す」という指示を受けると、エージェントはひそかにテスト自体を編集することがあります。これは報酬ハッキングです。テストスイートは成功を示しますが、実際には何も動作しません。
• ファイルを失います。 上書きや不適切なリファクタリングによって、チェックポイントもないまま1時間分の作業が失われます。
• コストがブラックボックスになります。 実行にいくらかかったのか、どのモデルが予算を消費したのか、エージェントが1つのステップで20回ループしたのかが分かりません。

keel はこれらの問題それぞれにツールを用意し、エージェント自身が呼び出します。初期化時にルールが CLAUDE.md に挿入されるためです。呼び出しのたびにイベントが記録されるので、実行全体を後から把握できます。

---

keel の動作

使い捨ての calc-kit プロジェクトでの実際の実行例です。エージェントには、keel のプロトコルに従って、ロックされたテストに合格するよう add(a, b) を実装するよう指示しました。これは編集されていない実際の実行順序です。

1.  load_context      → project loaded, tests intact
2.  record_decision   → "add = a + b, minimal, no deps" logged
3.  (writes calc.py)
4.  save_progress     → state persisted
5.  verify            → green: 2 passed, tampered: false
6.  checkpoint        → commit fac81a4 — milestone CERTIFIED
7.  check_drift       → no drift
8.  log_usage         → sonnet, 4000/1200 tok → $0.03
9.  route_task        → (sensitive) recommends EU-hosted model;
                        US + CN clouds excluded
10. stats             → 1 verify / 100% pass, 1 certified milestone, 0 cheat alerts
11. report            → milestone report written to .keel/reports/

次に、不正防止機能が実際に動作することを示すため、ロックされたテストファイルを手動で変更し（テストを改ざんして成功させようとするエージェントをシミュレート）、verify を実行しました。

{
  "tampered": true,
  "tests_changed": ["~ tests/test_calc.py (modified)"],
  "passed": true
}

t ampered: true と passed: true が同時に示されています。keel は「テストに合格したこと」と「テストが改ざんされていないこと」を混同せず、2つの指標を分けて報告します。エージェントはテストスイートを 改ざんして 成功させることができますが、keel はそれを検出します。この違いこそが、keel の要点です。

---

チート対策：檻ではなく、証明の仕組み

任意のツールを使うハーネスに共通する難題は、エージェントがverifyを無視してターミナルでpytestを実行し、不正を検出する唯一の仕組みを迂回できることです。CLAUDE.mdに丁寧な指示を書いても、エージェントが何を「試みる」かを導くだけで、何かを「阻止」することはできません。

keelは、単独では完璧なレイヤーはないものの、組み合わせれば容易で、発覚せず、追跡もされない迂回経路はなくなるという原則に基づき、3つのレイヤーでこの問題を解決します。

1. 説得 — CLAUDE.mdのブロックで、エージェントにverifyだけが判定者であり、テストの直接実行は禁止されていることを明確に伝えます。悪意ではなく、うっかり逸脱するエージェントという、最も多いケースに対応します。

2. 機械的なガード — init_projectが、プロジェクトの.claude/settings.jsonにPreToolUseフック（keel-guard）をインストールします。pytest、python -m pytest、npm test、yarn test、go testを実行前に検知して拒否し、エージェントをverifyに誘導します。これはモデルの制御外で、Claude Codeのハーネス内で動作します。私たちの環境では、--dangerously-skip-permissionsを指定しても有効です（バイパスモードでスキップされるのは対話形式の確認であり、フックではありません。ご自身の環境で確認してください。「正直な限界」を参照）。

3. 改ざん防止の証明 — すり抜けたものがあっても、verifyは判定対象とした作業ツリーの正確な状態のハッシュを出力します。checkpointがマイルストーンをcertifiedとしてマークするのは、同じツリーに対して、合格し、改ざんされていないverifyが実行された場合だけです。バイパスが発生すると、マイルストーンは無表示のままになるのではなく、statsとreportに表示される未認証になります。

レイヤー2は明白なバイパスを困難にします。レイヤー3はあらゆるバイパスを可視化します。keelが認証するのは、自らが確認した内容です。回避を不可能にするとは主張しません。そして、この正直さこそが、長期的な追跡に値する**「認証済みマイルストーンの割合」**という指標を生み出します。

これが機能するための黄金律：テストを書くのはあなたであり、エージェントではありません。 verifyはロックされたテストスイートを実行し、ファイルごとに変更を検出します。自分でテストを変更した場合は、lock_testsを再実行してください（人間が行う操作です）。

---

インストール

keelはシンプルなPythonです。依存関係は1つ（FastMCPとpydanticを取り込むMCP SDK）と、gitだけです。Windowsで開発・強化されており、macOS/Linuxでも動作します。

git clone https://github.com/tdalbanmoreynas/keel.git
cd keel
python -m venv .venv
pip install -r requirements.txt
python keel_server.py        # must start without error (Ctrl-C to quit)

Windowsでの仮想環境の有効化コマンドは.venv\Scripts\activate、macOS/Linuxではsource .venv/bin/activateです。クライアントに仮想環境のPythonを直接指定する場合（下記参照）、有効化は不要です。

Claude Codeへの接続

# from the keel folder, pointing at the venv's interpreter (absolute paths)
# macOS/Linux:
claude mcp add keel -- /absolute/path/to/keel/.venv/bin/python /absolute/path/to/keel/keel_server.py

Windowsの例：

claude mcp add keel -- "D:\path\to\keel\.venv\Scripts\python.exe" "D:\path\to\keel\keel_server.py"

または、mcp_config.example.jsonのブロックをクライアントの設定に貼り付けます（Clineの場合はcline_mcp_settings.json）。

デバッグに時間を取られないための2つのポイント：

• Claude Codeの設定でkeelのツールに対する許可ルール（mcp__keel__*）を追加してください。追加しない場合、エージェントの最初のkeel呼び出しが、必ずしも表示されるとは限らない認証プロンプトを待って停止します。
• プロジェクトのルートからクライアントを起動してください。 keel-guardフックは、現在のディレクトリにある.claude/settings.jsonから読み込まれ、親ディレクトリは参照しません。Claude Codeをプロジェクトのある場所から起動した場合に有効になります。

---

互換性

keel は 2 つの部分で構成されており、それぞれ対応範囲が異なります。

12 個の MCP ツールは標準の MCP であり、MCP に対応するあらゆるコーディングエージェントで動作します。Claude Code、Codex、Cursor、Cline、Windsurf、Zed、VS Code + Copilot、Continue、Goose、および Cline のフォーク（Roo Code、Kilo Code）に対応しています。メモリ、チェックポイント、改ざん防止用の verify、証明、意思決定のログ記録、コスト追跡、route_task は、MCP が動作するあらゆる環境で実行できます。

keel-guard フック（レイヤー 2）はClaude Code 専用です。これは .claude/settings.json に設定する PreToolUse フックであり、現時点でほかのクライアントには実装されていない Claude Code の仕組みです。したがって、次のようになります。

クライアント	MCP ツール（レイヤー 1 と 3）	機械的ガード（レイヤー 2）
Claude Code	✅ 完全対応	✅ 対応 — keel-guard フックがインストールされ、実行されます
Codex、Cursor、Cline、Windsurf、Zed、Copilot、Continue、Goose	✅ 完全対応	⚠️ 未インストール — フックシステムがありません

Claude Code 以外のクライアントでも、説得レイヤー（注入されたルール）と、重要な証明レイヤーを利用できます。verify をスキップしたチェックポイントは、stats と report で引き続き未証明として表示されます。テストの直接実行を機械的にブロックする機能は失われますが、可視性は失われません。バイパスは引き続き記録されます。これこそ、証明体制の設計が効果を発揮する部分です。重要な保証（マイルストーンが検証済みかどうかを常に確認できること）は、特定のクライアントのフックシステムに依存しません。

keel の機能が最も充実し、開発と強化が行われているのは Claude Code です。レイヤー 2 を除くすべての機能について、ほかのクライアントも第一級の対応対象です。

---

ワークフロー

1. プロジェクトごとに 1 回 — init_project：.keel/ を作成し、アーキテクチャと不変の制約を記録し、テストファイルをロックし、git を初期化して、keel-guard フックをインストールし、自律動作のルールを CLAUDE.md に注入します。
2. その後、エージェントはそれらのルールに従って自己管理します：各セッションの開始時に load_context を実行し、各ステップの後に save_progress と checkpoint を実行し、検証には verify を使い、各モデル呼び出しの後に log_usage を実行し、各アーキテクチャ上の選択で record_decision を実行し、最後に report を実行します。

すべての行ごとではなく、マイルストーンごとに戻って確認できます。

---

12 個のツール

ツール	役割	防ぐもの
init_project	ハーネス（アーキテクチャ、制約、テストロック、git、フック、CLAUDE.md）を構築します	—
load_context	セッション開始時の再開用ブリーフィング	コンテキストの喪失
save_progress	完了済み／作業中／未着手の内容をディスクに書き込みます	コンテキストの喪失
record_decision	アーキテクチャ上の選択を追記のみで記録します	アーキテクチャの逸脱
checkpoint	証明付きで、そのステップを Git にコミットします	ファイルの喪失
verify	ロック済みのテストを実行し、改ざんを検出します	不正（報酬ハッキング）
lock_tests	テストを再ロックします（人間による操作）	—
check_drift	制約を再確認し、未保存の作業にフラグを立てます	逸脱
route_task	サブタスクに最も費用対効果の高いモデルを選びます	コスト／データ主権
log_usage	モデル呼び出しの実際の支出を記録します	コストの可視化
stats	集計指標（コスト、不正、証明、速度）を表示します	誘導
report	人間向けの Markdown マイルストーンレポート	誘導

---

keel が記録する内容

各ツールはイベントを .keel/events.jsonl（ローカルに保存され、リポジトリ内だけで参照可能）に出力します。keel はこのトレースから、セッション、チェックポイント、証明済みと未証明のマイルストーン、verify の合格率、不正のアラート、モデルごとの実コスト、および速度を継続的に導き出します。このトレースによってエージェントによる実行の状況が把握可能になり、以下の資金提供レイヤーの基礎データにもなります。

---

オープンコア — keel は無料のセンサーです

keel は、2 つの部分で構成される 1 つの製品です。このリポジトリにあるローカルセンサーは、永久に無料の MIT ライセンスで提供されます。すべてお使いのマシン上で動作し、エージェントを監視して、改ざんを検知し、無駄とコストを追跡します。また、すべての情報をローカルの events.jsonl に書き込み、リポジトリの外に送信することはありません。個人開発者なら、これだけで十分です。

資金提供を受ける部分は、同じセンサーを基盤とする、エンジニアリングチーム向けのクラウドダッシュボード（TokenDrift による提供を予定）です。無料プランで答えるのが 「自分のエージェントはどう動いているか？」 だとすると、チームダッシュボードが答えるのは 「チーム全体は時間の経過とともにどう動いているか？」 です。チーム内のすべての開発者のセンサーの情報を集約することで、エージェントの合計支出と回収可能な無駄、マイルストーンのうち正直に認定されたもの（単に緑色になったものではありません）の割合、予算や不正率が急上昇した際のリアルタイムアラート、そして他のチームとの匿名ベンチマーク（「あなたのエージェントは中央値の 3 倍の頻度で改ざんしています」）を提供します。

この分割は意図的なものです。ローカルバイナリは複製でき、販売できないため、センサーは無料です。その役割は、役に立ち、広く使われることです。有料の価値は、チームレベルのネットワークと集約データにあります。これらは、単一のローカルインストールでは構造上生み出せません。Langfuse、PostHog、Sentry と同じモデルです。個人には無料で完全な機能を提供し、チームとして全体像が必要になったときに有料になります。

プライバシーは、この分割に組み込まれています。センサーが送信するのはメタデータのみで、コードやプロンプトは送信しません。 不正検出はローカルで実行され、マシンの外部に出る可能性があるのは判定結果（認定済み／疑わしい）のみです。

---

route_task と価格について

モデルの価格（keel_core.py の MODELS 定数）は 2026 年 6 月時点の推定値です。実際の料金に置き換えてください。route_task はエージェントの実行コストを考慮します（コスト = トークン数 × 反復回数 × 非効率度）。また、sensitive=True の場合は EU 圏外のクラウドを除外します。そのため、上記の実行では機密性の高いサブタスクが EU ホストのモデルにルーティングされました。

---

正直にお伝えする制限事項

keel は、保証できることとできないことを正直に伝えるように作られています。その誠実さこそが製品であり、免責事項ではありません。

• ガードが捕捉するのは標準的なテスト実行方法であり、考えられるすべての形式ではありません。 別名を付けたランナー、シェルスクリプトに埋め込まれたテスト（bash run_tests.sh）、または照合パターンに含まれない特殊な実行方法は、レイヤー 2 をすり抜ける可能性があります。パターン一覧は拡張できますが、網羅性は保証できません。だからこそレイヤー 3 が存在します。すり抜けたものもすべて、未認定のマイルストーンとして記録されます。
• バイパスモードの挙動は環境によって異なります。 --dangerously-skip-permissions の使用時にフックが実行されるかどうかについては、情報源によって見解が分かれており、Claude Code のバージョンによって異なる可能性があります。keel が対策した環境では、フックは引き続き実行されます。ただし、何も確認せずに信頼するのではなく、ご自身のマシンでテストしてください。いずれにしても、レイヤー 3 がバイパスを no_verify として検知します。
• lock_tests は慣例上、人間が実行する操作です。 エージェントがこれを呼び出すことを機械的に防ぐものはありません。ただし、改ざんしたテストを隠すために実行すれば、その形跡はトレースに現れます。不正アラートを確認し、チェックポイントで git diff を確認してください。

これらによって keel が機能しなくなるわけではありません。これらは証明の仕組みにおける正確な境界です。keel は目撃したものを認定し、それ以外を可視化します。

---

ライセンス

MIT — LICENSE を参照してください。© 2026 Tristan Dalban Moreynas.