agent-semaphore

並列コーディングエージェントのための協調レイヤー。 ワークツリーはマージ競合を解決しません。統合時点に先送りするだけです。agent-semaphore はそのギャップを埋めます。スコープに対する意図を伴うクレーム、書き込み時点での警告、コミット前の競合予測、そして必須テストゲート付きの直列化ランディングキュー。

ローカルファースト：デーモン不要、クラウド不要、アカウント不要。git 共通ディレクトリ内の単一の SQLite ファイルが唯一の合流点であり、リポジトリのすべてのワークツリーが自動的にそれを認識します。設計上クロスベンダー — Claude Code フックと MCP、Codex CLI は MCP 経由、その他は git pre-commit フック経由。

問題

エージェントが作成したプルリクエストの競合率は 27.7% — 人間の 10～20% に対して（AgenticFlict、107K+ エージェント PR）。共活動ペアでは内訳は 19.8% エージェント内 vs 41.7% エージェント間：エージェントは互いに水平方向の認識を持たず、協調を出荷するすべての製品は自社のエージェントのみを調整します。不適切に解決された競合は、通常のコードの最大 ～26倍 のバグ密度をもたらします（EMSE 2020）— 高コストなのは競合そのものではなく、静かに進行する悪い解決です。

分離は解決されコモディティ化されています（エージェントごとにワークツリーまたはコンテナ — 誰もが出荷しています）。予測と統合はそうではありません。誰もライブワークツリー間で git merge-tree を実行せず、スタンドアロンのローカルマージキューは事実上存在しません。

機能

ハードな保証が存在するのは唯一ランディングパスだけです。フックと pre-commit は協調的なアドミッション制御とテレメトリであり、セキュリティ境界ではありません — ASEM_HOOK_OFF=1 と ASEM_OVERRIDE=1 は文書化され、監査されたエスケープハッチです。これは最初に明言されています。なぜなら、サンドボックスを装う協調レイヤーは、ないより悪いからです。

クイックスタート

uv tool install git+https://github.com/alwh1te/agent-semaphore     # asem on PATH
# or, from a clone: uv tool install -e .

cd <your repo>
curl -O https://raw.githubusercontent.com/alwh1te/agent-semaphore/main/.agent-semaphore.toml.example
mv .agent-semaphore.toml.example .agent-semaphore.toml   # set the gate command, hot classes, target branch
asem init                                   # state in .git/agent-semaphore/
asem install --git-hooks                    # Claude Code hooks + .mcp.json + git pre-commit
asem doctor                                 # PASS checklist

asem claim src/api/ -i "refactor auth parsing" --ttl 30m   # exit 3 = held by someone else
asem check src/api/routes.py                               # who holds it, and what for
asem radar                                                 # conflicts between worktrees, before any commit
asem land feature-branch                                   # rebase -> gate -> CAS into the staging branch
asem notices                                               # messages addressed to you
asem status | asem queue status | asem doctor

終了コードは契約の一部です：0 OK/空き、3 保持中/競合/バウンス、2 使用方法、1 内部エラー — スクリプトは「協調が拒否した」と「ツールが壊れた」を区別できます。

測定結果

この分野では、クレームが実際に競合を減らすかどうかを測定した人はいなかったため、このリポジトリは独自の2つのベンチマークを提供しています。

スクリプト化（docs/benchmark.md、60回実行、決定論的エージェント、コンプライアンス = 1 は構造上保証）：統合競合 60% → 0%、人間の介入 9 → 0。

ライブエージェント（docs/bench-llm.md、2つの同時 claude -p エージェントによる40回実行、$17.95）：

スクリプト化ハーネスでは構造上生成できなかった3つの発見：

1. 競合はクレームではなくキャッチアップによって除去される。 エージェントがピアのブランチにリベースした10回の実行すべてがクリーンマージしました。競合した調整済み実行はすべて、両方のエージェントが丁寧にクレームし、どちらもリベースしなかったケースです。クレームは書き込みを直列化します — 相手の結果を手渡すわけではありません。この発見が、「解放は待機者を起動し、ブランチを指定する」機能を生み出しました。

2. フックは40回の実行で一度も発動しなかった。 プロンプトにプロトコルがあるため、エージェントは編集前にクレームし、保持中のスコープに書き込むことはありません。そのため、強制は不要な保険であることが判明しました — 動作レイヤーではありません。

3. 協調は競合を「行われなかった作業」に変換できる。 2回の実行で、ブロックされたエージェントはホルダー、その意図、ブランチを引用し、タスクを放棄しました。did_work 列が ICR の隣になければ、それらの実行はクリーンな成功と読めます — だからこそその列が存在します。

意味的ドリフト（テキスト的にクリーンだが意味的に壊れている）は、両方のベンチマークですべてのアドバイザリーレイヤーを生き延び、キューによる必須ゲートでのみ捕捉されます。

プラグイン方法

• Claude Code — asem install はプロジェクトの .claude/settings.json を書き込み（PreToolUse + PostToolUse）、Bash(asem:*) と mcp__semaphore__* を許可リストに追加し、.mcp.json に MCP サーバーを登録します。コミットされた配線はホスト間で移植可能です（$HOME とベア asem）。そのため、複数のマシン間で共有されるリポジトリは、あるホストのパスを引き継ぎません。

• MCP（asem mcp、サーバーキー semaphore）— claim、release、check、status、extend、report_intent、radar、enqueue_land、land_status。すべての応答は保留中の通知を排出するため、エージェントはポーリングなしで奪取、バウンス、ターゲット移動を学習します。

• Codex CLI — 同じ MCP サーバーを ~/.codex/config.toml 経由で使用し、AGENTS.md 用のプロトコルスニペットも含みます。ヘッドレス Codex はツールが事前承認されていない限り MCP 呼び出しを静かにキャンセルします。docs/integration.md に動作する設定があります。

• その他 — asem install --git-hooks は共有フックディレクトリに pre-commit ゲートを配置します（以前にあったフックをチェーンロードします）。

ドキュメント

• docs/00-research.md — この設計の基盤となる研究資料：測定された問題、ツールの状況、参考になる古典的な先行技術、2024～26年の論文、および市場の3つの確認されたギャップ。

• docs/adr/ADR-001-architecture.md — アーキテクチャ、リスクレジスター、およびブラインドレビューからの10の敵対的攻撃（うち8つが設計を変更）。

• docs/adr/ADR-002-stack-and-state.md — スタック、命名、および状態の所在。

• docs/benchmark.md / docs/bench-llm.md — 両方のベンチマーク：方法、結果、および明記された制限。

• docs/integration.md — インストールと各所の配線。

ステータス

v1 は実装され、ドッグフーディング済み：このリポジトリは自身のエージェントをこれを通じて調整しています。150のテスト、CI での p95 フックレイテンシゲート、両方のベンチマークがリポジトリから再現可能。

既知の制限を率直に述べます：ステージングブランチから main への昇格はまだ手動でゲートなし（asem promote が次の機能）。キューはプッシュしません。シンボルレベルのスコープはなく、テストゲートを超えた意味的競合検出はなく、LLM による自動解決はありません（公表された上限は約55～60%の正確性で、無人実行には十分ではありません）。マルチホストは v2 の設計ですが、スキーマにはすでに host 列があります。

開発

uv run pytest -q                          # 150 tests
uv run ruff check . && uv run ruff format --check .
uv run python bench/hook_latency.py 200   # hook latency gate (p95 < 100 ms)
uv run python bench/runner.py --seeds 3 && uv run python bench/report.py

PreToolUse フックスクリプトはパッケージ外でベンダリングされ、stdlib のみに依存しなければなりません — すべてのエージェントのすべての書き込みで実行されるため、依存関係ではなくレイテンシ予算を持ちます。CONTRIBUTING.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。