agent-comm

agent-comm

エージェントに依存しない相互通信システムです。 AI コーディングエージェント（Claude Code、Codex CLI、Gemini CLI、Aider、または任意のカスタムツール）が互いに対話し、状態を共有して、リアルタイムで作業を調整できます。

ライトテーマ	ダークテーマ

理由

同じコードベースで複数の AI エージェントを実行すると、あるターミナルでコードレビューを行い、別のターミナルで実装し、さらに別のターミナルでテストをしていても、エージェント同士は互いの存在を認識できません。その結果、作業が重複したり、マージコンフリクトが発生したり、コンテキストを見落としたりします。

	agent-comm がない場合	agent-comm がある場合
検出	エージェントは互いの存在を認識できません	エージェントがスキルを登録し、能力を基に互いを検出します
調整	同じファイルを編集して、コンフリクトが発生します	ファイルや領域をロックし、作業を分担します
コミュニケーション	なし — 各エージェントが状況を把握できずに作業します	メッセージ、チャンネル、ブロードキャストでやり取りできます
状態の共有	作業が重複し、コンテキストを見落とします	アトミック CAS 対応の共有 KV ストア
可視性	何が起きているのかわかりません	リアルタイムのダッシュボードとアクティビティフィードですべてを表示します

agent-comm は、エージェント間で共有する通信レイヤーを提供します。

• エージェントは名前、能力、スキルを登録し、ほかのエージェントから検出できるようにします
• スキルやタグを使って互いを検出し、タスクを動的に振り分けます
• 重要度（low／normal／high／urgent）と任意の ACK を指定して、メッセージ（ダイレクト、ブロードキャスト、チャンネルベース）を交換し、作業を調整します
• ブロッキング待機（comm_poll）で受信トレイをポーリングするため、処理中に届いたほかのエージェントからのシグナルを、ビジーループなしで受け取れます
• ロック、フラグ、進捗管理に使える状態（アトミック CAS 対応のキーバリューストア）を共有します
• コミット、テスト結果、ファイル編集などのアクティビティイベントを共有フィードに記録します
• 進捗がないまま稼働している（ハートビートは正常）スタック状態のエージェントを検出します
• システムレイヤーの file-coord フック（下記参照）を使ってファイル編集を直列化し、共有ファイルで並行作業するエージェント同士が互いの変更を上書きできないようにします
• アクティビティフィードタブを含む、すべての状況をリアルタイムで表示するウェブダッシュボードを提供します

MCP（stdio トランスポート）に対応しているエージェント、または HTTP リクエストを送信できるエージェント（REST API）であれば利用できます。

MCP ツールだけでなく、フックを使う理由

MCP ツール（comm_state など）は、エージェントが連携するための 基本機能 を提供しますが、連携を 強制 するものではありません。エージェント自身が、ツールを呼び出すことを忘れないようにする必要があります。ベンチでは、モデルの裁量に任せた場合の挙動を測定しました。その結果、厳密な手順を促すプロンプトを使っても、Claude は最初のロック取得時にはプロトコルに従うものの、その後は「役に立とうとしてタスクを終わらせる」行動に戻ってしまいます。 ソフトな連携は信頼できません。

解決策は、scripts/hooks/ に付属する 2 つの PreToolUse フックです。file-coord はすべての Edit／Write／MultiEdit をインターセプトし、REST の POST /api/state/file-locks/<path>/cas でファイルをロックします（別のエージェントがロックを保持している場合は編集をブロックします）。bash-guard は git commit、git push、npm install、npm test、ビルド、マイグレーション、開発サーバーの起動をインターセプトし、別のセッションの WIP と競合する場合にブロックまたは警告します。これにより、プロトコルはエージェントが無視するかもしれないプロンプトではなく、インフラになります。

ベンチの主要なパイロットは multi-term-commit です。同じプロジェクトで 2 つのターミナルセッションを使う際に日常的に生じる問題を直接再現しています。セッション A が 2 つのファイルを編集しますが、コミットはしません。続いてセッション B が別の 2 つのファイルを編集し、git commit -am "my work" を実行します。フックがなければ、B のコミットに A の WIP が気づかれないまま含まれてしまいます。フックがあれば、B のコミットは bash レイヤーで、次に取るべき行動を示すメッセージとともにブロックされ、B は選択的なステージング、変更の復元、または連携を行います。ベンチの結果は次のとおりです。

	単純な方法（フックなし）	フックあり
コミットの純度	混在 — bar.js、baz.js、foo.js、qux.js	純粋 — baz.js、qux.js
実時間	91.0 秒	78.8 秒（-13%）
合計コスト	$0.774	$0.591（-24%）
結果	A の WIP が B の名前で気づかれないままコミットされた	クリーンなコミット。上書きなし

このフックは、より安全なだけでなく、高速で、しかも低コストです。 理由は、共有ワークスペースでエージェント同士が連携できないと、古い状態を読み取ってタスクの途中で混乱し、リトライや再考が発生するためです。アクセスを直列化し、競合を早期に明らかにすることで、こうした無駄な思考をなくせます。npm run setup を実行すると、両方のフックが自動的にインストールされます。Claude Code、OpenCode、その他のカスタム MCP クライアントへの手動インストールについては、セットアップ → ファイル連携を参照してください。測定方法については、bench/README.mdを参照してください。

agent-comm の仕組み

agent-comm は、3 種類のトランスポート（AI ホスト向けの MCP stdio、フック、ダッシュボード、カスタムスクリプト向けの REST + WebSocket）を公開する単一の Node プロセスであり、WAL モードの SQLite データベースをバックエンドに使用します。Claude Code（またはその他のホスト）の設定にインストールされたフックは、localhost:3421 の REST エンドポイントを呼び出して、ファイルロックを取得し、誰が何を編集したかを照会し、プレゼンスをブロードキャストします。同じポートのダッシュボード UI では、すべてのエージェント、メッセージ、チャンネル、共有状態のエントリをリアルタイムで確認できます。複数の AI ホストが同時に接続し、同じ状況を共有できます。

graph TD
    A["Agent A<br/>(Claude Code)"] -->|MCP stdio| COMM
    B["Agent B<br/>(Codex CLI)"] -->|MCP stdio| COMM
    C["Agent C<br/>(Custom script)"] -->|REST API| COMM
    HK["PreToolUse hooks<br/>(file-coord, bash-guard)"] -->|REST cas| COMM

    subgraph COMM["agent-comm"]
        D["Agents<br/>Register, discover, heartbeat"]
        E["Messages<br/>Direct, broadcast, channels, threads"]
        F["State<br/>Namespaced KV with CAS"]
        G["Events<br/>Real-time pub/sub"]
        D --> DB["SQLite DB<br/>WAL mode, FTS5 search"]
        E --> DB
        F --> DB
        DB --> WS["WebSocket"]
    end

    WS --> UI["Dashboard UI<br/>http://localhost:3421"]

クイックスタート

npm からインストール

npm install -g agent-comm

またはソースからクローン

git clone https://github.com/keshrath/agent-comm.git
cd agent-comm
npm install
npm run build

オプション 1：MCP サーバー（MCP 対応のあらゆる AI ホスト向け）

agent-comm は stdio MCP サーバーとして動作するため、MCP 対応のあらゆるホストで使用できます。 テスト済みのホストには、Claude Code、Cline、OpenCode、Cursor（状態の読み取り専用）、 Windsurf、Codex CLI、Aider、Continue.dev があります。各ホスト向けの設定例は docs/SETUP.mdにあります。

汎用 MCP 設定：

{
  "mcpServers": {
    "agent-comm": {
      "command": "npx",
      "args": ["agent-comm"]
    }
  }
}

これをホストの MCP 設定ファイルに追加してください（パスはホストによって異なります。 Claude Code の場合は ~/.claude.json、OpenCode の場合は ~/.config/opencode/config.json、Cursor の場合は ~/.cursor/config.json などです。 詳しくは docs/SETUP.md の各ホストのセクションを参照してください）。

接続するホストにかかわらず、最初の MCP 接続時にダッシュボードが http://localhost:3421 で自動的に起動します。

オプション 2：スタンドアロンサーバー（REST／WebSocket クライアント向け）

node dist/server.js --port 3421

オプション 3：自動セットアップ（Claude Code）

npm run setup

MCP サーバーを ~/.claude.json に登録し、フックスクリプト（ライフサイクル＋ファイル調整＋bash ガード）をインストールして、権限を設定します。その他のホスト：ホストごとの統合手順については docs/SETUP.md を参照してください。ツール呼び出し前フックをサポートするホストであれば、どのホストでも同じ file-coord.mjs スクリプトを変更せずに使用できます。

MCP ツール（7）

ツール	説明
comm_register	名前、機能、メタデータ、スキル、自動参加チャンネルを指定して登録します
comm_agents	エージェント管理 — アクション：list、discover、whoami、heartbeat、status、unregister
comm_send	メッセージを送信します — ダイレクト（to）、チャンネル、ブロードキャスト、返信（reply_to）、転送（forward）
comm_inbox	受信トレイを読み取ります（ダイレクト＋チャンネルメッセージ、未読フィルター、importance フィルター、thread_id によるスレッド表示）
comm_poll	新しい受信トレイメッセージが届くまで待機します（timeout_ms と importance フィルターをサポート）
comm_channel	チャンネル管理 — アクション：create、list、join、leave、archive、update、members、history
comm_state	共有キーと値の状態 — アクション：set、get、list、delete、cas

REST API

すべてのエンドポイントは JSON を返します。ループバック限定です。外部からの Host／Origin ヘッダーには 403 を返し、リクエストボディは application/json である必要があり、ワイルドカード CORS は許可されません。詳細は完全な API リファレンスを参照してください。

GET  /health                              Server status + uptime
GET  /api/agents                          List online agents
GET  /api/agents/:id                      Get agent by ID or name
GET  /api/agents/:id/heartbeat             Agent liveness (status + heartbeat age)
GET  /api/channels                        List active channels
GET  /api/channels/:name                  Channel details + members
GET  /api/channels/:name/members          Channel member list
GET  /api/channels/:name/messages         Channel messages (?limit=50)
GET  /api/messages                        List messages (?limit=50&from=&to=&offset=)
GET  /api/messages/:id/thread             Get thread
GET  /api/search?q=keyword                Full-text search (?limit=20&channel=&from=)
GET  /api/state                           List state entries (?namespace=&prefix=)
GET  /api/state/:namespace/:key           Get state entry
GET  /api/feed                              Activity feed events (?agent=&type=&since=&limit=50)
GET  /api/overview                        Full snapshot (agents, channels, messages, state)
GET  /api/export                          Full database export as JSON

POST   /api/messages                      Send a message (body: {from, to?, channel?, content})
POST   /api/state/:namespace/:key         Set state (body: {value, updated_by})
POST   /api/state/:namespace/:key/cas     Atomic compare-and-swap (file-coord hook uses this)
DELETE /api/messages                       Purge all messages
DELETE /api/messages                       Delete messages by filter
DELETE /api/messages/:id                   Delete a message (body: {agent_id})
DELETE /api/state/:namespace/:key          Delete state entry
DELETE /api/agents/offline                 Purge offline agents
POST   /api/cleanup                       Trigger manual cleanup
POST   /api/cleanup/stale                 Clean up stale agents and old messages
POST   /api/cleanup/full                  Full database cleanup

エージェントの可視性とステータス

comm_agents の action: "heartbeat" は任意の status_text パラメーターを受け付けます。これにより、エージェントはオンライン状態を維持するための呼び出しと同時に、表示ステータスを更新できます。

// MCP call — heartbeat + status update in one
comm_agents({ "action": "heartbeat", "status_text": "implementing auth module" })

// Clear status text (pass null)
comm_agents({ "action": "heartbeat", "status_text": null })

// Plain heartbeat — status text unchanged
comm_agents({ "action": "heartbeat" })

ライフサイクルフックをサポートするホスト（Claude Code、OpenCode、フック API が提供される予定の Cursor／Codex）では、scripts/hooks/ に同梱されているライフサイクルフックスクリプトによって、ハートビート、登録、ステータスが自動化されます。Agent ツールによって起動されたサブエージェントも、SubagentStart を通じて同じ登録を引き継ぐため、メインセッションと並んでダッシュボードに表示されます。フックをサポートしないホスト（2025 年時点の Cursor、Windsurf、Aider）でも MCP ツールを使用できます。エージェントはホストの指示ファイルから comm_register と comm_agents heartbeat を呼び出す必要があります。カスタム MCP クライアントやスクリプトは、REST エンドポイントを呼び出すか、comm_heartbeat を直接使用して、進行状況をリアルタイムに表示できます。

REST エンドポイント GET /api/agents/:id/heartbeat は、外部監視用にエージェントの稼働情報（ステータス、ハートビート経過時間（ms／s）、ステータステキスト）を返します。

通信パターン

ダイレクトメッセージ

sequenceDiagram
    participant A as Agent A
    participant S as agent-comm
    participant B as Agent B

    A->>S: comm_send(to B, content review PR 42)
    Note over S: Store in SQLite, emit event
    B->>S: comm_inbox()
    S-->>B: message from A
    B->>S: comm_reply(message_id 1, LGTM merging)

CAS による共有状態（分散ロック）

sequenceDiagram
    participant A as Agent A
    participant S as agent-comm
    participant B as Agent B

    A->>S: comm_state(action cas, key deploy-lock, new agent-a)
    S-->>A: swapped true
    B->>S: comm_state(action cas, key deploy-lock, new agent-b)
    S-->>B: swapped false
    Note over B: Lock held by agent-a, back off

ダッシュボード

ウェブダッシュボードは http://localhost:3421 で自動的に起動し、エージェント、メッセージ、チャンネル、共有状態、アクティビティフィードをリアルタイムで表示します。すべてのビューと機能については、ダッシュボードガイドを参照してください。

---

テスト

npm test              # 288 tests across 16 files
npm run test:watch    # Watch mode
npm run test:e2e      # E2E tests only
npm run test:coverage # Coverage report
npm run check         # Full CI: typecheck + lint + format + test

環境変数

変数	デフォルト	説明
AGENT_COMM_PORT	3421	ダッシュボードの HTTP／WebSocket ポート
AGENT_COMM_HOST	127.0.0.1	ダッシュボードのバインドアドレス（ネットワークに公開するには 0.0.0.0 を指定）
AGENT_COMM_RETENTION_DAYS	7	古いデータが自動削除されるまでの日数（1～365）

ドキュメント

• セットアップガイド — インストール、クライアントの設定（Claude Code、OpenCode、Cursor、Windsurf）、フック
• アーキテクチャ — ソース構成、設計原則、データベーススキーマ
• ダッシュボード — Web UI の表示と機能
• 変更履歴

ライセンス

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