ControlKeel

ControlKeel

チームの働き方を、AI エージェントが従うべき記憶に変えます。 - @arya_minus

ControlKeel は、日々のエンジニアリングを統制するためのエージェント制御プレーンです。 観察、検出結果、評価を通じて、意図に関するルール、レビューの好み、デリバリーの習慣を学習し、それらを型付きの記憶、ポリシーチェック、証拠バンドルへと変換します。CK は、持ち運び可能な「会社の頭脳」としてコーディングエージェントと本番環境の間に位置し、意図されたデリバリーと実際のデリバリーを比較し、エージェントの生の意図をポリシーで検証されたタスクに変換します。

現在 AI エージェントを使っているなら、どのように振る舞うべきかを伝える *.md ファイルがあるでしょう。しかし、ルールや仕様を記したファイルは、モデルに対する単なる約束にすぎません。ControlKeel は出力を強制します。 バグの検出にとどまらず、CK は「未知の未知」の問題、つまり、セッションのたびにドメイン知識を説明し直さなければならない問題を解決します。

プロダクトのループ

1. 意図とポリシーを取り込む — スコープ、リスク、予算、ドメインパック、人間の好みを CK の状態として保存します。
2. エージェントの出力を検証する — 決定論的なチェックと任意の助言的レビューにより、リスクの高い作業が main に到達する前に検出結果を生成します。
3. 必要な場合のみゲートする — 意図、リスク、ポリシーに応じて、人間が影響の大きいアクションを承認します。
4. 証拠を保持する — 検出結果、レビュー、証明、記憶、コスト、タスクの結果は、ホストを切り替えても保持されます。
5. 評価で改善する — トレースや繰り返し発生する失敗を、特定のスイートと対象に対する範囲を限定した回帰証拠に変換します。

運用ルールはシンプルです。トークンは再発見ではなく、発見に使いましょう。 繰り返し発生する振る舞いは、人間の承認を伴う決定論的な昇格プロセスを通ります。 回帰証拠に合格すると、チェック、API、CLI、またはワークフローが既知のケースを処理し、エージェントは例外や真に新しい不確実性だけを扱います。

ControlKeel は、ドメイン知識を「生の」意図や「活用されない」ドキュメントから、記憶し、強制し、進化する生きたシステムへと変換します。

クイックスタート

エージェント経由でワンライン設定

以下をエージェント（OpenCode、Codex、Claude、またはその他の対応ホスト）にコピーして貼り付けます。

Set up ControlKeel for this repository. Read and follow https://raw.githubusercontent.com/aryaminus/controlkeel/main/README.md, https://raw.githubusercontent.com/aryaminus/controlkeel/main/docs/getting-started.md, https://raw.githubusercontent.com/aryaminus/controlkeel/main/docs/support-matrix.md, and https://raw.githubusercontent.com/aryaminus/controlkeel/main/docs/agent-integrations.md. Install ControlKeel if missing, run `controlkeel setup`, detect this agent host, attach the strongest supported path with `controlkeel attach <host>`, then run `controlkeel attach doctor`, `controlkeel provider doctor`, `controlkeel status`, `controlkeel findings`, and the host-native MCP check. If CK is available only as MCP, call `ck_attach` for this host. Apply only safe local fixes and redact secrets from logs. Pause and ask before continuing if the host needs workspace trust, manual provider configuration, a restart after attach/plugin changes, or a plan-review approval that cannot auto-wait. Ensure the project is trusted and restart the host after attach/plugin changes.

CLI のインストール

CLI をインストールします。

brew tap aryaminus/controlkeel && brew install controlkeel
# or
npm i -g @aryaminus/controlkeel
# or
curl -fsSL https://github.com/aryaminus/controlkeel/releases/latest/download/install.sh | sh

Windows PowerShell：

irm https://github.com/aryaminus/controlkeel/releases/latest/download/install.ps1 | iex

最初の統制された実行：

controlkeel
controlkeel setup
controlkeel attach opencode   # project scope by default; use another supported host as needed
controlkeel attach doctor
controlkeel provider doctor
controlkeel status
controlkeel findings

統制したいリポジトリからセットアップを実行し、接続してください。プロジェクトスコープでは、ホストのファイルはそのリポジトリ内にのみ書き込まれます。--scope user は、ユーザースコープを明示的にサポートする対象に限り、ホストレベルのファイルをユーザー設定の下に書き込みます。プロジェクトのバインドや証明の状態がグローバルになるわけではありません。

最初の実行手順の全体については、docs/getting-started.md を参照してください。ホストの対応状況については、docs/support-matrix.md と docs/agent-integrations.md を参照してください。

ベンチマークに裏付けられた証拠

ControlKeel には、結果を保持するベンチマークエンジンが含まれています。現在ユーザーに提示されている証拠は、以下に示す名前付きのスイート、対象、スコアリング定義に限定されています。完全な表、注意事項、JSON エクスポート、エージェントホストのプロトコルについては、docs/benchmarks.md が正式なリファレンスです。

with-vs-without-CK ベースラインの検証結果（host_comparison_v1、リスクの高い12シナリオ）

ControlKeel 0.3.45 で検証済みです。

• リスクの高いシナリオのスイート host_comparison_v1：null_policy_baseline の検知数は 0/12、controlkeel_validate の検知数は 12/12、ブロック数は 9/12、期待されたルールへの該当数は 9/12 でした。決定論的な検証時間の中央値は 52 ms、プロバイダートークンは 0 でした。
• 対になる無害なシナリオのスイート benign_baseline_v1：controlkeel_validate の検知数は 0/10、ブロック数は 0/10、FPR は 0.000 でした。決定論的な検証時間の中央値は 42 ms、プロバイダートークンは 0 でした。

数値は正確に読み取ってください。決定論的スキャナーによる証拠は、モデルを利用するエージェントホストによる証拠とは異なります。再現コマンドと OpenCode/Copilot/Claude/Codex の比較プロトコルについては、docs/benchmarks.md をご覧ください。

現在提供している機能

• ローカルガバナンス： CLI、ローカルの完全な stdio MCP ツールセット、プロジェクトバインディング、ホストのアタッチ／エクスポートバンドル、スキャナー検証、検出結果、レビュー、証明バンドル、予算、型付きメモリ。
• ホストとランタイムのサポート： 対応ホストへのネイティブなアタッチ、ヘッドレス／外部ループシステム向けのランタイムエクスポート、より限定された OAuth スコープ付きのホスト型 MCP セット、最小限の A2A、フォールバック検証／プロキシ経路。
• チーム／プロジェクト運用： 組織メンバーシップ、招待、ワークスペースの GitHub リポジトリバインディング、サービスアカウント、Webhook、ワークスペースのツールポリシー、ポリシーセット API。
• クラウド証拠経路： オプトインのクラウドテレメトリ、ワークスペースキー、クラウド実行パッケージ、ランタイムコールバック、設定するまで無効な、検出結果、レビュー、ダイジェスト、メモリレコードの双方向同期。
• 可観測性ループ： タイムライン、メモリ品質、コスト、傾向、問題クラスター、評価候補、ベンチマークのドラフト／履歴、昇格アドバイザリー。

ドキュメント一覧

• docs/README.md — 作業別のドキュメント一覧
• docs/getting-started.md — インストールから最初の検出結果まで
• docs/support-matrix.md — ホスト／プロトコルの正式な一覧
• docs/agent-integrations.md — 統合方式とサポートレベル
• docs/benchmarks.md — ベンチマークのスコアリング、メタデータ、主張の適切な扱い
• docs/observability-feedback-loop.md — ローカルの証拠からリグレッションまでのループ
• docs/control-plane-claim-matrix.md — ガバナンス、メモリ、クラウド同期、ヒューマンゲートに関する README の主張とテストの対応表
• docs/api-reference.md と docs/cli-reference.md — コードに準拠したインターフェース
• docs/packages.md — パッケージと配布カタログ
• docs/self-hosting.md — セルフホスト環境へのデプロイガイダンス

開発

mix setup
mix phx.server
mix test
mix precommit

SQLite 上の Phoenix + Ecto を使用しています。HTTP には Req を使用します。単一バイナリのビルドは Burrito と GitHub Releases を通じて配布されます。