synapse-a2a

Synapse A2A Communication

Google A2A Protocol を介したエージェント間通信フレームワークです。

Worktree の規律（サブエージェントは最初にお読みください）

.synapse/worktrees/<name>/ ディレクトリに cd してはいけません。

サブエージェント（Claude Code Agent ツール、Codex サブプロセス、その他、親セッションによって起動されたサブプロセス）は、親から永続的なシェルを引き継ぎます。誤って worktree に cd すると、サブエージェントのターンが終了した後もその状態が残り、親の作業ディレクトリが気付かないうちに変わってしまいます。その結果、git status、git diff、さらには git commit まで別の worktree で実行され、デバッグに時間がかかるうえ、誤ったブランチにコミットしてしまうおそれがあります。

.synapse/worktrees/ で作業する際のルール：

• worktree に cd してはいけません。セッション中は、最初の作業ディレクトリから移動しないでください。
• worktree 内のファイルを読み書きする場合は、絶対パスのみを使用してください（例：Read /Volumes/.../.synapse/worktrees/foo/src/bar.py。cd .synapse/worktrees/foo && cat src/bar.py ではありません）。
• ディレクトリを移動する代わりに、git -C /abs/path/to/worktree ... を使用して worktree に対して git を実行してください。
• worktree は Synapse（synapse spawn --worktree、synapse team start --worktree）によって管理されます。作業場所ではなく、読み書きするデータとして扱ってください。

worktree 内で操作する必要がある場合（例：そこで pytest を実行する場合）は、親シェルのディレクトリを変更するのではなく、synapse spawn --worktree で専用のエージェントを起動してください。

クイックリファレンス

タスク	コマンド
エージェントの一覧表示	人間向けには synapse list（自動更新、対話操作：矢印キー／1～9で選択、Enterでジャンプ、kで終了、/でフィルター）。AI／スクリプトでは synapse list --json、synapse list --plain、または MCP の list_agents を使用します
エージェントの詳細	synapse status <target> [--json]
停滞エージェントの監視（ステージ 1）	synapse watchdog check [--alarm-only] [--json]（一度限りのヒューリスティックなスキャン。#646）
メッセージの送信	synapse send <target> "<msg>"（デフォルト：--notify。--from は自動検出）
一斉送信	synapse broadcast "<msg>"
返信を待つ	synapse send <target> "<msg>" --wait
返信を待たずに送信	synapse send <target> "<msg>" --silent
返信	synapse reply "<response>"
特定の相手に返信	synapse reply "<response>" --to <sender_id>
失敗を報告して返信	synapse reply --fail "<reason>"
割り込み（優先度 4）	synapse interrupt <target> "<msg>"
PTY にキーを送信（TUI ダイアログ用の緊急手段。#695）	synapse send-keys <target> <keys>（例：codex の「今後確認しない」には a、Enter には \r。A2A を介さず、エージェントが対話型ダイアログで停止しており、synapse jump を使えない場合に使用します）
エージェントの起動	synapse spawn <type> --name <n> --role "<r>" -- <tool-specific-automation-args>
起動して最初のタスクを送信（タスク委任時に推奨）	synapse spawn <type> --name <n> --role "<r>" --task-file <path> --task-timeout 600 --notify
ワークツリーを使ってエージェントを起動	synapse spawn <type> --worktree --name <n> --role "<r>" -- <tool-specific-automation-args>
チームの起動	synapse team start <homogeneous-profiles...> [--worktree] -- <tool-specific-automation-args>
プランの承認	synapse approve <id>
プランの却下	synapse reject <id> --reason "<feedback>"
ナレッジの保存	synapse memory save <key> "<content>" --tags <t> --notify
ナレッジの検索	synapse memory search "<query>"
ファイルのロック	synapse file-safety lock <file> <agent_id> --intent "..."
ロックの確認	synapse file-safety locks
タスク履歴	synapse history list --agent <name>
エージェントの終了	synapse kill <name> -f
孤立プロセスのクリーンアップ	synapse cleanup --dry-run（一覧表示）；synapse cleanup -f（親がクラッシュまたはクリアされた孤立プロセスをすべて終了）
ファイルの添付	synapse send <target> "<msg>" --attach <file> --wait
保存済みエージェント	synapse agents list / synapse agents set <profile> / synapse agents unset <profile> / synapse agents roles / synapse spawn <agent_id>；稼働中のエージェントでは、安定したターゲットエイリアスとして agent_definition_id を利用できます
共有セッションの引き継ぎ	SYNAPSE_SHARED_SESSION_DIR を使用して synapse session publish <name> / synapse session import <name>
Canvas への投稿	synapse canvas post <format> "<body>" --title "<title>"
リンクのプレビュー	synapse canvas link "<url>" --title "<title>"
テンプレートの投稿	synapse canvas briefing '<json>' --title "<title>"
プランカードの投稿	synapse canvas plan '<json>' --title "<title>"（Mermaid DAG と、ステータス追跡機能付きのステップ一覧）
Canvas を開く	synapse canvas open（サーバーを自動起動し、ブラウザーを開きます）
Canvas の再起動	synapse canvas restart（停止して再起動します。アップグレード後に canvas status が ⚠ STALE を報告する場合に使用します）
ワークフロースキルの同期	synapse workflow sync（ワークフロー YAML からスキルを再生成し、孤立したスキルを削除します）
ワークフローの実行（自動起動）	synapse workflow run <name> --auto-spawn（depends_on と condition を含む DAG ステップをサポート）
マルチエージェントのパターン	synapse map init/list/show/run/status/stop（組み込み：generator-verifier、orchestrator-subagent、agent-teams、message-bus、shared-state）
Wiki への取り込み	synapse wiki ingest <source> [--scope project|global]（ソースファイルを Wiki に取り込みます）
Wiki のクエリ	synapse wiki query "<question>" [--scope project|global]（Wiki ページを検索します）
Wiki の lint	synapse wiki lint [--scope project|global]（Wiki の整合性を検証します）
Wiki のステータス	synapse wiki status [--scope project|global]（Wiki インデックスの統計を表示します）

コラボレーションの判断フレームワーク

作業を始める前に、コラボレーションの機会を評価します。

状況	対応
自分の役割の範囲内にある小規模なタスク	自分で対応する
自分の役割の範囲外のタスクで、READY 状態のエージェントがいる	委任する：synapse send --notify または --silent
適切なエージェントがいないため、タスクを委任する必要がある	1 つのコマンドで起動とタスクの送信を行う：synapse spawn <type> --name <n> --role "<r>" --task-file <spec.md> --task-timeout 600 --notify。エージェントを起動し、READY 状態になるまで待ってから最初のタスクを送信するため、手動で準備状況を確認する必要はありません。
初期タスクなしでエージェントだけを起動する必要がある	synapse spawn <type> --name <n> --role "<r>"（タスクは後から synapse send で送信）
行き詰まった、または専門知識が必要	質問する：synapse send <target> "<question>" --wait
マイルストーンを完了した	報告する：synapse send <manager> "<summary>" --silent
パターンを発見した	共有する：synapse memory save <key> "<pattern>" --tags ... --notify

推奨されるコラボレーションの確認手順（3 フェーズ以上、または 10 ファイル以上の変更）： 大規模な作業に取りかかる前に、次の手順を検討してください。

1. synapse list --json または MCP の list_agents — 利用可能なエージェントを確認する
2. synapse memory search "<topic>" — すでに解決した人がいないか確認する
3. 委任が有効な場合は、エージェント割り当て計画（フェーズ／エージェント／理由）を作成する
4. 必要に応じて専門家を起動する（多様性を確保するため、異なるモデルタイプを優先する）

小規模または中規模のタスクで、手順にかかる負担がメリットを上回る場合は、この確認手順を省略してください。

Synapse の機能を積極的に活用する

機能	重要な理由	コマンド
共有メモリ	エージェントを再起動しても、共有された知識が残ります	synapse memory save/search/list
ファイルの安全性	ロックにより、2 つのエージェントが同じファイルを編集する際のデータ損失を防ぎます。ワークツリー内ではスキップしてください（SYNAPSE_WORKTREE_PATH）	synapse file-safety lock/unlock/locks
ワークツリー	ファイルを分離することで、並行編集時のマージ競合をなくします	synapse spawn --worktree
ブロードキャスト	チーム全体へのお知らせをすべてのエージェントに即座に届けます	synapse broadcast "<msg>"
履歴	監査証跡により、何がいつ起きたかを追跡できます	synapse history list/show/stats
確率的想起	履歴全体を出力せずに、直近性、重要度、キーワードの一致度に基づいて、過去のタスクに関する関連観察を想起します	HistoryManager.recall_observations
計画の承認	実行前に品質を確保するため、承認を経て実行します	synapse approve/reject
キャンバス	リッチカードやテンプレート（ブリーフィング、比較、ダッシュボード、手順、スライド、計画）を共有するためのビジュアルダッシュボードです。カードはブラウザーのボタンまたは GET /api/cards/{card_id}/download から、Markdown、JSON、CSV、またはネイティブ形式でダウンロードできます	synapse canvas post/link/briefing/plan/open/list/restart
エージェント制御	Canvas の #/admin ビューから、ブラウザーベースでエージェントを管理できます（エージェントの選択、メッセージの送信、応答の確認、エージェントの行をダブルクリックしてターミナルに移動）	synapse canvas open → #/admin に移動
ワークフロービュー	Canvas の #/workflow ビューから、ブラウザーベースでワークフローを管理できます（ワークフローの一覧表示、手順の確認、ワークフロー YAML の作成／編集／削除／インポート／エクスポート、実行の開始、ライブ SSE 更新による進捗の監視。実行履歴は再起動後も保持されるよう SQLite に保存されます）	synapse canvas open → #/workflow に移動
ハーネスビュー	Canvas の #/harnesses にある、エージェントハーネスのリソースを確認するブラウザーベースの画面です。サブビューには、#/harnesses/skills（ユーザー／プロジェクト／Synapse／プラグインの各スコープにある SKILL.md の一覧を、アクティブな各プロジェクトのルートに対してスキャン）と、#/harnesses/mcp（アクティブな各ルートのプロジェクト .mcp.json にある MCP サーバー設定と、ユーザースコープの Claude Code ~/.claude.json、Codex ~/.codex/config.toml、Gemini ~/.gemini/settings.json、OpenCode ~/.config/opencode/opencode.json、Claude Desktop 設定）が含まれます	synapse canvas open → #/harnesses に移動
計画カード	Mermaid DAG と手順の一覧で依存関係を視覚化します	synapse canvas plan
LLM Wiki	プロジェクト／全体のドキュメントを取り込み、照会、検証するための構造化ナレッジベースです	synapse wiki ingest/query/lint/status
スマート提案	プロンプトを分析し、大規模な作業をチーム／タスクに分割する方法を提案する MCP ツールです	MCP ツール：analyze_task
プロジェクトの学習内容	保存された定義は、起動時に .synapse/learnings/<agent_definition_id>.md からプロジェクトに適応した学習内容を読み込めます	synapse agents set ＋ Markdown の学習内容
プロアクティブモード	タスクの規模に応じた機能の使用ガイドです（SYNAPSE_PROACTIVE_MODE_ENABLED=true）	references/features.md を参照
MCP ブートストラップ	MCP リソースを通じて、互換性のあるクライアントに手順を配布します（オプトイン。ツールのみを介した Copilot も含む）。MCP ツール：bootstrap_agent、list_agents、analyze_task、canvas_post	synapse mcp serve / python -m synapse.mcp

Canvas を使用するタイミング

視覚的な構成が役立つ出力や、後で参照する出力には Canvas を使用します。

• Canvas を使用する場合： 図、比較表、複数ステップの計画、設計ドキュメント、リッチな書式の結果
• Canvas を使用しない場合： 単純な完了報告、単一ファイルの変更、簡単な進捗報告（代わりにブロードキャストまたは返信を使用）

テンプレートの選択ガイド：

• briefing — 構造化されたレポート、進捗報告、リリース概要
• comparison — 変更前後、選択肢のトレードオフ、レビュー差分
• steps — 計画、移行手順、実行チェックリスト
• slides — ウォークスルー、デモ、ページごとのナラティブ
• dashboard — 複数ウィジェットによる運用状況のスナップショット、簡潔なステータスボード
• plan — Mermaid による可視化とステップ追跡に対応したタスク DAG

単一ブロックには synapse canvas post <format> を直接使用し、複数セクションのコンテンツにはテンプレートを使用します。

エージェント起動の判断表

⚠️ 同一モデルのルール — まずサブエージェントを試してください。 Claude Code エージェントが別の claude を必要とする場合（または codex エージェントが別の codex を必要とする場合）は、synapse spawn を使用する前に、プロセス内サブエージェント（Claude では Agent / Task ツール、Codex ではサブプロセス）を使用してください。同じアカウントで同じモデルを synapse spawn すると、レート制限枠が共有されるため、消費量が分散されず、同じクォータに対する消費が倍増します。同一モデルでの synapse spawn は、ヘルパーを親セッション終了後も存続させる必要がある場合、サブエージェントでは対応できないファイル分離が必要な場合、または独立した長時間の役割を担う場合に限ってください。

synapse spawn は、異なるモデルへの委任（Claude → codex / gemini）、サブエージェントをサポートしていないエージェント（Gemini / OpenCode / Copilot）、または永続的な複数タスク用ヘルパーに適しています。

デフォルトの起動ポリシー： synapse spawn を使用するときは、起動されたエージェントが無人で実行できるよう、-- の後に基盤となる CLI 固有の自動化引数を渡してください。ほとんどの CLI では、承認をスキップする／自動承認するフラグを指定します。OpenCode では --agent build を使用して build エージェントプロファイルを選択し、承認動作は OpenCode の権限設定に従わせてください。

同じルールを synapse team start にも適用してください。適切な CLI 引数をデフォルトで渡し、それらの引数が CLI 固有の場合はチーム内の CLI を統一してください。

一般的なデフォルト（Synapse がすでに自動で挿入します — 無効にするには --no-auto-approve を渡してください）：

• Claude Code：synapse spawn claude --name <n> --role "<r>" -- --permission-mode=auto
• Gemini CLI：synapse spawn gemini --name <n> --role "<r>" -- --approval-mode=yolo
• Codex CLI：synapse spawn codex --name <n> --role "<r>"（synapse が -cdefault_permissions=":workspace" を挿入します。Codex 0.128+ では --full-auto が削除されています）
• OpenCode：synapse spawn opencode --name <n> --role "<r>" -- --agent build（build エージェントプロファイルを選択します。承認をスキップするフラグではありません）
• Copilot CLI：synapse spawn copilot --name <n> --role "<r>" -- --allow-all
• Claude チーム：synapse team start claude claude -- --permission-mode=auto
• Gemini チーム：synapse team start gemini gemini -- --approval-mode=yolo
• Codex チーム：synapse team start codex codex（synapse が -cdefault_permissions=":workspace" を挿入します）
• OpenCode チーム：synapse team start opencode opencode -- --agent build（build エージェントプロファイルを選択します。権限の確認は引き続き OpenCode の設定に依存します）
• Copilot チーム：synapse team start copilot copilot -- --allow-all

2026-04 の移行： Anthropic は --dangerously-skip-permissions を廃止し、代わりに --permission-mode=auto を採用しました（すべてのチェックを無効化するのではなく、安全性分類を使用します）。Gemini も、従来の --yolo / -y の短縮形式ではなく、--approval-mode=yolo を推奨しています。Synapse は新しいフラグをデフォルトで挿入するようになりました。従来の形式も引き続き使用でき、各プロファイルの alternative_flags に残されています。 | 条件 | アクション | |-----------|--------| | 既存の READY エージェントで対応できる | synapse send — 再利用すると高速です（起動時のオーバーヘッドを回避できます） | | 同じモデルのヘルパーが必要（Claude → claude、Codex → codex） | まずインプロセスのサブエージェントを使用します（Claude では Agent／Task ツール、Codex ではサブプロセス）。synapse spawn で同じモデルを起動すると、レート制限のウィンドウを共有します。 | | 並列実行が必要 | ファイルを分離するため、--worktree -- <tool-specific-automation-args> を指定して synapse spawn を実行します（モデルをまたぐ方法を推奨） | | タスクで別のモデルの強みを活用する必要がある | 別のタイプを synapse spawn します（Claude から Gemini／Codex などを起動） | | ユーザーがエージェント数を指定した | 指定どおりにします | | 焦点を絞ったサブタスクが 1 つ | サブエージェント（同じモデル）または synapse spawn（モデルをまたぐ場合） | | 独立したサブタスクが N 個 | 同じモデルへの振り分けにはサブエージェント、モデルをまたぐ場合には synapse spawn を使用します |

起動から終了までのライフサイクル（推奨、1 コマンド）：synapse spawn --task-file ... --task-timeout 600 --notify → A2A 完了通知を待つ → 結果を評価する → synapse kill <name> -f → synapse list --json で確認する

従来のライフサイクル（起動から最初のタスクまでの間に制御が必要な場合のみ）：起動 → READY になるまで synapse list --json または synapse status <target> --json をポーリングする（数分待ちます。デフォルトの 30 秒のタイムアウトは、ほとんどのプロファイルには短すぎます） → synapse send --notify → 評価する → synapse kill -f → クリーンアップを確認する。

⚠️ よくある落とし穴： READY になっていないエージェントに送信すると、HTTP 層でハングするか、内部の準備完了待ちでブロックされます。synapse spawn --task-file を使う（推奨 — 準備完了の処理を自動で行います）か、synapse send を呼び出す前に "status": "READY" であることを明示的に確認してください。30 秒で十分だと思い込まないでください。ほとんどのプロファイルでは 1〜5 分かかります。

エージェントのステータス一覧（synapse list --json の .status）：

ステータス	意味	アクション
READY	アイドル状態で、新しい作業を受け付け可能	synapse send
SENDING_REPLY	一時的に、送信先への A2A send／reply POST を送信中	待ちます。POST の完了後、前のステータスに戻ります
PROCESSING	タスクを処理中	待つか、停止している場合は synapse interrupt
WAITING	権限／承認のプロンプトへの応答待ち	synapse approve／synapse reject
WAITING_FOR_INPUT	権限以外の入力を求めてタスクが一時停止中（#538）	回答とともに synapse reply <task_id>
RATE_LIMITED	LLM プロバイダーのレート制限により、直前のタスクが失敗（#561）	プロバイダーのウィンドウがリセットされるまで待ってから、再送信します
DONE	タスク完了。約 10 秒後に READY に降格	結果を確認してから、次に進みます
SHUTTING_DOWN	エージェント終了中	送信しないでください

CLI のダイアログで停止している（A2A の WAITING ではない）場合： エージェントがアイドル状態に見えても、独自の TUI プロンプト（codex の編集確認、モデル選択、レート制限ダイアログ）でブロックされている場合は、synapse jump を使わずに synapse send-keys <target> <keys> で PTY に直接入力します。例：synapse send-keys Impl a は codex の「次回から確認しない」ショートカットを送信します。（#695）

起動したエージェントは完了後に終了すると、ポート、メモリ、PTY セッションが解放され、孤立したエージェントが誤って今後のタスクを受け付けることを防げます。

# Preferred: one-command spawn + delegate (handles readiness wait internally)
synapse spawn gemini \
    --name Tester \
    --role "test writer" \
    --task-file /tmp/test-spec.md \
    --task-timeout 600 \
    --notify
# (do other work; receive async A2A notification when Tester finishes)
# Evaluate result, then cleanup
synapse kill Tester -f
synapse list --json                       # Verify cleanup (AI-safe)

synapse kill が失敗する場合、またはエージェントが synapse list --json に引き続き表示される場合は、-f を付けて再試行し、エージェントのステータス／ログを確認して、孤立したエージェントを残さずにクリーンアップの失敗を報告してください。

応答モードガイド

結果が必要かどうかに基づいて選択します。

モード	フラグ	使用する場面
待機	--wait	続行する前に回答が必要な場合（質問、レビュー）
通知	--notify（デフォルト）	非同期 — 完了時に通知されます
サイレント	--silent	応答が不要な委任（応答を待たずに実行。完了時には送信側の履歴もベストエフォートで更新されます）

ワーカーエージェントガイド

マネージャーからタスクを受け取った場合：

タスク受領時

1. すぐに作業を開始します（登録済みの返信先がある Synapse 追跡メッセージでは、[REPLY EXPECTED] や --response を含め、synapse reply が有効です。それ以外の場合、ユーザーが貼り付けた A2A: テキストには返信先がないため、代わりに synapse send で応答します）
2. 共有ナレッジを確認します：synapse memory search "<task topic>"
3. 編集前にファイルをロックします（SYNAPSE_WORKTREE_PATH が設定されている場合は省略します）：synapse file-safety lock <file> $SYNAPSE_AGENT_ID

作業中

• タスクに5分以上かかる場合は、進捗を報告します：synapse send <manager> "Progress: <update>" --silent
• 障害が発生した場合は、すぐに報告します：synapse send <manager> "<question>" --wait
• 調査結果を保存します：synapse memory save <key> "<finding>" --tags <topic>
• サブタスクを委任することもできます。ヘルパーを起動してください（異なる種類のモデルを優先してください）
• 起動したエージェントは必ず終了させます：synapse kill <name> -f

完了時

1. マネージャーに報告します：synapse send <manager> "Done: <summary>" --silent

失敗時

1. 詳細を報告します：synapse send <manager> "Failed: <error details>" --silent

関連スキル

スキル	用途
synapse-manager	マルチエージェントのオーケストレーションワークフロー（委任、監視、検証）
synapse-reinst	/clear またはコンテキストのリセット後に指示を再注入します

参考資料

詳しい情報については、以下の参考ファイルを参照してください。

参考資料	内容
references/commands.md	すべてのオプションを含む CLI コマンドの完全なドキュメント
references/api.md	A2A エンドポイント、準備完了ゲート、エラー処理
references/examples.md	マルチエージェントのワークフロー例とパターン
references/file-safety.md	ファイルロックのワークフローとコマンド
references/messaging.md	メッセージの送信、返信、優先度、ステータス、インタラクティブ操作
references/spawning.md	起動のライフサイクル、パターン、ワークツリー、権限、API
references/collaboration.md	エージェントの命名、外部エージェント、認証、再開、パスのオーバーライド
references/features.md	セッション、ワークフロー、保存済みエージェント、トークン、スキル、設定、Canvas