agentclaim

複数のエージェント。1つの作業ツリー。Gitでは救えない。

並行して動くAIコーディングエージェントのためのファイル所有権管理 — 互いの上書きを静かに防ぎます。

npm i -g agentclaim && agentclaim init

問題

2つ、3つ、5つのコーディングエージェントを同時に実行します。彼らは1つの作業ツリーを共有します。

Gitは、別々のクローンで後でマージする人間のために作られました。同じチェックアウトを同時に編集する2人の書き手をどう扱うか、Gitにはまったくわかりません。競合マーカーも警告もマージもなく、2番目の書き込みが勝ち、最初の書き込みは消えます。

これらは、ある午後に1つのリポジトリで発生した実際の3つのインシデントです。3つとも本番環境にリリースされました。どれもエラーメッセージを1つも生成しませんでした。

1. ステージングの競合

git add は、ファイルをその瞬間の状態でスナップショットします。

 session A            session B
 ─────────            ─────────
                      git add i18n.js Money.jsx   ← snapshots i18n.js v1
 write i18n.js v2
                      git commit                  ← commit contains i18n.js v1

コミットは、古い i18n.js と一緒に新しい Money.jsx を出荷しました。画面は本番環境で生の翻訳キーをレンダリングしました。Gitは成功を報告しました。後続の修正コミットは、まったく同じ競合に陥りました。

2. 破壊的な復元

git checkout HEAD -- i18n.js api.demo.js   # session A tidies its tree
git commit -a                              # session B, two seconds later

セッションBの作業はディスクから元に戻され、そのままコミットされました。静かに。

3. 嘘をついたゲート

デプロイスクリプトにはダーティツリーガードがありました。それはデプロイ時にツリーをチェックし、コミット時の競合はチェックしませんでした。ゲートはグリーンになり、コミットは間違っていて、デプロイは忠実に間違ったコミットを公開しました。

Related MCP server: asynkor

修正

書き込みは賢くなり、コミットは厳格なまま。

2番目の書き手をすべてブロックするのは停止標識であって解決策ではありません。そして、人々が必要とする作業をブロックするツールはオフにされます。1つのファイル内の2つのエージェントが実際に競合するのは、同じ領域に触れたときだけです。

そこでagentclaimは「このファイルを所有しているのは誰か？」とは尋ねません。「最後に見てから何が変わったか？」 と尋ねます — これが、他のエージェントの編集と自分の編集を区別する唯一の質問です。異なる領域なら、両方のエージェントが作業できます。同じ行なら、一方が停止します。

agentclaim: src/checkout.ts is also being edited by another agent — your edits do not overlap theirs.
  their lines: 12-19
  your lines:  84-91
Both edits are kept. You may not commit this file until they are done.

ファイル全体のWriteも競合ではありません — 他のエージェントの作業とgit merge-fileを使って3ウェイマージされるため、両方の編集が反映されます：

agentclaim: src/checkout.ts was merged, not overwritten.
Another agent had edited this file; your write has been combined with
their changes. Re-read the file before continuing — it now contains both.

重複する行も停止標識ではない

ターゲットを絞った編集は外科的です。アンカーテキストが現在のファイルに存在する場合にのみ適用されます。その1つの特性がすべての作業を行います。

• アンカーがまだ存在する → それを置き換えることで他のエージェントの編集が保持されます。なぜなら、彼らの変更は定義上、テキストの別の場所にあるからです。

• アンカーが消えた → ツールは自分で拒否し、エージェントは再読み込みします。

どちらの場合も結果はすでに正しいので、ブロックは往復のコストがかかり、何も得られません。agentclaimは代わりにコンテキストを追加します：

agentclaim: heads up — another agent just changed the same lines of src/checkout.ts.
  their lines: 12-19
  your lines:  14-16

Your edit still applies cleanly on top of their version. This is what
they changed, in case it affects what you were about to do:
  @@ line 12-19 @@
  -  const total = items.length
  +  const total = items.reduce((n, i) => n + i.qty, 0)

Nothing is blocked. You may not commit this file until they are done.

実際にエージェントを停止するもの

4つのこと、そしてこれだけです：

編集パスでは何も停止しません。それがポイントです。通常の作業を中断するツールはオフにされ、その後は何も保護しません。

コミットは厳格な部分

2つのライブセッションがファイルに触れた後は、どちらもステージングまたはコミットできません — それがまさに、あるエージェントが他のエージェントの未完成の作業を出荷する方法だからです。上記のインシデント#1。

その保護は、出口がなければデッドロックになるため、3つの出口があります：

セッションが終了またはクラッシュすると、保持していたすべてを解放するため、ツリーがロックされたままになることはありません。

サーバーなし。デーモンなし。依存関係なし。ストアは.git/内のディレクトリです。

クイックスタート

npm i -g agentclaim
cd your-repo
agentclaim init

グローバルにインストールしたくないですか？ npx agentclaim initも機能します — フックは明日も存在するパスを指す必要があるため、最初に~/.agentclaim/libに自分自身をコピーします。

これだけです。initはClaude Codeフックを配線し、git pre-commitフックをインストールします（既存のものをチェーンします）。いつでも確認できます：

$ agentclaim status
SESSION          FILES  AGE   LAST SEEN
● money screen       3  6m    2s
  ai visibility      2  22m   14s

FILE                    HELD BY        AGE
web/src/Money.jsx       (you)          6m
web/src/i18n.jsx        (you)          6m
web/src/api.demo.js     ai visibility  22m

セッションに読みやすい名前を付けて、他のエージェントのエラーメッセージが意味を持つようにします：

agentclaim label "money screen"

initがマシンに変更するもの

3つのこと。それ以外はありません。

ネットワーク呼び出しなし。テレメトリなし。バックグラウンドプロセスなし。あなたのコードの1行も触れられず、git statusに新しいものは表示されません。

一人のときは何もしない

ツリー内で唯一のライブセッションがあなたの場合、すべてのゲートは許可にショートサーキットします。 クレームは強制されず、コマンドは検査されず、バイパスするものはありません。

これは意図的です。通過できないゲートはゲートがないより悪いです。なぜなら、人々はそれを無効にすることを学び、その後は何も保護しないからです。agentclaimは、それが存在するまさにその状況でのみ歯を持ちます。

$ agentclaim doctor
...
1 live session(s) · 3 claim(s) · TTL 30m · mode block
single session -> gates inactive (no-op)

4つのゲート

ゲート3は、他では何もキャッチしないものです。コミット内のすべてのパスをgit show <sha>:<path>で再読み取りし、ディスク上のファイルとバイト単位で比較します：

agentclaim: ⚠ commit 045d1f7 does NOT match what is on disk:
  web/src/api.demo.js

This is the classic `git add` snapshot race: another session rewrote these
files after you staged them, so the commit captured stale content.
DO NOT DEPLOY. Fix it with:
  git add web/src/api.demo.js && git commit --amend --no-edit

別のセッションが保持するファイルのみを報告するため、通常の部分的なステージング（git add x、xの編集を続ける、コミット）は誤警報を引き起こしません。

任意のエージェントと連携

3つの統合レイヤー、強い順。該当するものをできるだけ使用してください。

Claude Code — フック（最強）

agentclaim init            # project-level  (.claude/settings.json)
agentclaim init --global   # every repo     (~/.claude/settings.json)

ゲートは書き込みまたはコマンドの前に実行されます。エージェントは拒否をフィードバックとして受け取り、自分で別のファイルを選択します。

Cursor · Windsurf · Codex · Zed · Cline · MCP対応のもの

agentclaimはMCPサーバーを同梱しているため、MCPを話す任意のエージェントが同じ所有権プロトコルに参加できます：

{
  "mcpServers": {
    "agentclaim": {
      "command": "agentclaim",
      "args": ["mcp"],
      "env": { "AGENTCLAIM_SESSION": "cursor-1", "AGENTCLAIM_AGENT": "cursor" }
    }
  }
}

公開されるツール：agentclaim_status、agentclaim_claim、agentclaim_release、agentclaim_check、agentclaim_verify_commit。説明はモデルにいつ呼び出すかを伝えます。

その他すべて — gitフック

agentclaim initはpre-commitフックをインストールするため、aider、素のgit commit、IDE、シェルスクリプトはすべて同じチェックにヒットします。設定は不要です。

デプロイスクリプトとCIには、終了コードゲートを使用します：

agentclaim check --staged --quiet || exit 1   # anyone else holding staged files?
agentclaim verify HEAD                        # did the commit capture disk?

コマンド

agentclaim init [--global]    wire up the hooks (Claude Code + git pre-commit)
agentclaim status             who holds what
agentclaim who <path>         owner of a single file
agentclaim claim <path...>    claim files            [--note "..."]
agentclaim release <path...>  "I am done here"       [--all] [--force to take over]
agentclaim check <path...>    gate for scripts, exit 0/1  [--staged] [--quiet]
agentclaim verify [rev]       compare commit content against disk  [--all]
agentclaim label "<name>"     give this session a readable name
agentclaim gc                 collect stale claims
agentclaim doctor             diagnose the installation
agentclaim uninstall          remove the hooks
agentclaim mcp                run as an MCP server

設定

リポジトリルートにオプションの.agentclaim.json：

{
  "ttlMinutes": 30,
  "touchTtlMinutes": 10,
  "mode": "block",
  "ignore": ["node_modules/**", "dist/**", "*.lock", "package-lock.json"]
}

• ttlMinutes — この時間アクティビティがないセッションは消えたと見なされ、そのクレームを引き継ぐことができます。すべてのフック呼び出しがハートビートを更新するため、アクティブなセッションは期限切れになりません。

• touchTtlMinutes — セッションが最後にファイルを編集してから、他のセッションがそのファイルのコミットをブロックし続ける時間。意図的にttlMinutesより短くしています。まだ生きていることは、このファイルでまだ作業していることと同じではありません。この2つを混同すると、保護がデッドロックに変わります。

• mode — block（デフォルト）、warn（報告するが許可）、off。

• ignore — クレームされません。生成されたファイルをここに置きます。ロックファイルやビルド出力がクレームされると、ゲートが常に発火し、人々はバイパスし始めます。

仕組み

.git/agentclaim/
  sessions/<id>.json   { sid, label, pid, started, seen, wt }
  claims/<hash>.json   { path, wt, sid, at, touchers }
  snap/<sid>/<hash>    what that session last saw on disk
  pending/<sid>/<hash> a merge computed before a write, applied right after it
  pass.json            short-lived identity token for the git hook

• 保存場所はgit rev-parse --git-common-dirであり、リポジトリのすべてのワークツリーが1つのレジストリを共有します。

• クレームキーにはワークツリールートが含まれます。2つのワークツリー内の同じ相対パスは、ディスク上では2つの異なるファイルだからです。別々のワークツリーは互いにブロックしません。ワークツリーはこの問題に対する正当な修正手段であり、罰する対象ではありません。

• 原子性はopen(..., 'wx') — O_EXCLです。2つの同時クレームがあっても勝者は1つで、競合状態はありません。

• 生存性はTTLベースです。フックはすべてのツール呼び出しで発火するため、seenは数秒以内に最新の状態に保たれます。クラッシュしたエージェントのクレームは回収可能であり、リポジトリを詰まらせることはありません。

• 領域推論は、セッションのスナップショットとディスク上のファイルをgit diff --no-index -U0で比較し、git merge-fileでマージします。すべてgit自身のセマンティクス — すでに信頼しているもの — であり、依存関係は追加されません。

• マージは我々が適用し、注入はしません。 フック出力スキーマにはupdatedInputフィールドがありますが、それが呼び出しの自動承認なしに適用されることを検証可能な形で示すものはなく、そこで誤った想定をすると他方のエージェントの作業が黙って失われます。そのため、マージはスタッシュされ、ツール実行直後に、我々が制御するメカニズムのみを使って書き込まれます。

• ツール呼び出しあたりのコストは、短命なNodeプロセス1つです。単独動作で約45ms、ゲートが実際に推論する必要がある場合は約83ms（200ファイルのリポジトリで測定）。Nodeの起動が支配的であり、読み取り後のスナップショット取得は約1ms追加されます。

• メンテナンス不要。 gcはセッション開始ごとに実行され、消滅したセッションのクレーム、スナップショット、保留中のマージを削除するため、.git/に何も蓄積されません。

制限事項

誤って信頼するガードはガードがないより悪いため、率直に述べます。

• git commit --no-verifyはgitフック層をスキップします。Claude Code層は依然としてそれを捕捉します。

• フックやMCPを持たないエージェントは書き込み中は見えません。コミット時に捕捉されます。

• コマンド解析は意図的に完全なシェルパーサーではありません。gitに触れるeval / sh -c / バッククォートの場合、agentclaimは別のセッションが生存している間のみ拒否します。

• 領域共存はセッションが最後に見たものを把握する必要があるため、エージェントがツールを通じて読み書きしたファイルにのみ適用されます。他の経路（シェルのsed、外部エディタ）で変更されたファイルは、その推論からは見えません。

• agentclaimは意味を理解しません。2つの編集がテキスト的に独立していても、意味的に整合しないことがあります。他方のエージェントがいたことを伝えますが、判断はあなた次第です。

• クリーンな三方マージでも意味的に誤っている可能性があります。人間の場合とまったく同じです。agentclaimはファイルがマージされたことを伝えるので、それに依存する前に再読してください。

• クレームはマシンごとです。ホスト間で同期されるものはありません。

テスト

npm test

32件のエンドツーエンドチェック。このスイートは上記の3つの実インシデントをすべて再現し、単独セッションではツールが完全にノーオペレーションであることを証明し、各ゲートを合格例と不合格例の両方で検証します。自らのバグを捕捉できないゲートは、信頼を生むため、ゲートがないよりも悪いのです。

リンク

• ソースとイシュー: https://github.com/volkangunay/agentclaim

• npm: https://www.npmjs.com/package/agentclaim

ライセンス

MIT © Volkan Günay