| name | synapse-a2a |
| license | MIT |
| description | Synapse A2A agent communication -- sending messages, spawning agents, delegating tasks, sharing memory, managing the LLM wiki, and coordinating file edits. Use this skill when: running synapse send/reply/broadcast/interrupt, spawning agents with synapse spawn or synapse team start, sharing knowledge with synapse memory, managing wiki pages with synapse wiki, locking files with synapse file-safety, checking agent status with synapse list/status, or orchestrating any multi-agent workflow. For AI/programmatic use, prefer synapse list --json, synapse status <target> --json, or the MCP list_agents tool instead of interactive synapse list. |
Synapse A2A Communication
Inter-agent communication framework via Google A2A Protocol.
Worktree Discipline (subagents, read this first)
NEVER cd into .synapse/worktrees/<name>/ directories.
Subagents (Claude Code Agent tool, Codex subprocess, and any other
sub-process driven by the parent session) inherit a persistent shell
from the parent. A stray cd into a worktree leaks out of the subagent
turn and silently corrupts the parent's working directory — git status,
git diff, and even git commit then land on the wrong worktree, which
wastes debugging time and can put commits on the wrong branch.
Rules for working with .synapse/worktrees/:
- Do not
cd into a worktree, ever. Stay in the original working
directory for the entire session.
- Read and write files inside a worktree using absolute paths only
(for example
Read /Volumes/.../.synapse/worktrees/foo/src/bar.py,
not cd .synapse/worktrees/foo && cat src/bar.py).
- Run
git against a worktree with git -C /abs/path/to/worktree ...
instead of changing directory.
- Worktrees are managed by Synapse (
synapse spawn --worktree,
synapse team start --worktree). Treat them as read/write data
surfaces, not as places to live.
If you need to operate from inside a worktree (e.g. running pytest
there), spawn a dedicated agent for it with synapse spawn --worktree
rather than changing the parent shell's directory.
Quick Reference
| Task | Command |
|---|
| List agents | synapse list for humans (auto-refresh, interactive: arrows/1-9 select, Enter jump, k kill, / filter). For AI/scripts use synapse list --json, synapse list --plain, or MCP list_agents |
| Agent detail | synapse status <target> [--json] |
| Stuck-agent watchdog (Stage 1) | synapse watchdog check [--alarm-only] [--json] (one-shot heuristic scan; #646) |
| Send message | synapse send <target> "<msg>" (default: --notify; --from auto-detected) |
| Broadcast | synapse broadcast "<msg>" |
| Wait for reply | synapse send <target> "<msg>" --wait |
| Fire-and-forget | synapse send <target> "<msg>" --silent |
| Reply | synapse reply "<response>" |
| Reply to specific | synapse reply "<response>" --to <sender_id> |
| Reply with failure | synapse reply --fail "<reason>" |
| Interrupt (priority 4) | synapse interrupt <target> "<msg>" |
| Send keys to PTY (escape hatch for TUI dialogs; #695) | synapse send-keys <target> <keys> (e.g. a for codex "don't ask again", \r for Enter; bypasses A2A — use when an agent is stuck on an interactive dialog without synapse jump) |
| Spawn agent | synapse spawn <type> --name <n> --role "<r>" -- <tool-specific-automation-args> |
| Spawn + send first task (preferred for delegation) | synapse spawn <type> --name <n> --role "<r>" --task-file <path> --task-timeout 600 --notify |
| Spawn with worktree | synapse spawn <type> --worktree --name <n> --role "<r>" -- <tool-specific-automation-args> |
| Team start | synapse team start <homogeneous-profiles...> [--worktree] -- <tool-specific-automation-args> |
Collaboration Decision Framework
Evaluate collaboration opportunities before starting work:
| Situation | Action |
|---|
| Small task within your role | Do it yourself |
| Task outside your role, READY agent exists | Delegate: synapse send --notify or --silent |
| No suitable agent exists, need to delegate a task | Spawn + task in one command: synapse spawn <type> --name <n> --role "<r>" --task-file <spec.md> --task-timeout 600 --notify. This spawns, waits for READY, and sends the first task — no manual readiness polling needed. |
| Need a bare agent (no initial task) | synapse spawn <type> --name <n> --role "<r>" (send tasks later via synapse send) |
| Stuck or need expertise | Ask: synapse send <target> "<question>" --wait |
| Completed a milestone | Report: synapse send <manager> "<summary>" --silent |
| Discovered a pattern | Share: synapse memory save <key> "<pattern>" --tags ... --notify |
Recommended Collaboration Gate (3+ phases OR 10+ file changes):
Consider these steps before diving into large work:
synapse list --json or MCP list_agents — check available agentssynapse memory search "<topic>" — check if someone already solved this- Build Agent Assignment Plan (Phase / Agent / Rationale) when delegation is beneficial
- Spawn specialists if needed (prefer different model types for diversity)
Skip this gate for small/medium tasks where the overhead exceeds the benefit.
Use Synapse Features Actively
| Feature | Why It Matters | Commands |
|---|
| Shared Memory | Collective knowledge survives agent restarts | synapse memory save/search/list |
| File Safety | Locking prevents data loss when two agents edit the same file -- skip inside worktrees (SYNAPSE_WORKTREE_PATH) | synapse file-safety lock/unlock/locks |
| Worktree | File isolation eliminates merge conflicts in parallel editing | synapse spawn --worktree |
| Broadcast | Team-wide announcements reach all agents instantly | synapse broadcast "<msg>" |
| History | Audit trail tracks what happened and when | synapse history list/show/stats |
| Probabilistic Recall | Recall relevant past task observations by recency, importance, and keyword overlap without dumping all history | HistoryManager.recall_observations |
| Plan Approval | Gated execution ensures quality before action | synapse approve/reject |
| Canvas | Visual dashboard for sharing rich cards and templates (briefing, comparison, dashboard, steps, slides, plan); cards downloadable as Markdown, JSON, CSV, or native format via browser button or GET /api/cards/{card_id}/download | synapse canvas post/link/briefing/plan/open/list/restart |
| Agent Control | Browser-based agent management via Canvas #/admin view (select agents, send messages, view responses, double-click agent row to jump to terminal) | synapse canvas open → navigate to #/admin |
| Workflow View | Browser-based workflow management via Canvas #/workflow view (list workflows, inspect steps, create/edit/delete/import/export workflow YAML, trigger runs, monitor progress with live SSE updates; run history persisted to SQLite across restarts) | synapse canvas open → navigate to |
When to Use Canvas
Use Canvas when the output benefits from visual structure or will be referenced later:
- Use Canvas for: diagrams, comparison tables, multi-step plans, design docs, results with rich formatting
- Skip Canvas for: simple completion reports, single-file changes, quick status updates (use broadcast or reply instead)
Template selection guide:
briefing — structured reports, status updates, release summariescomparison — before/after, option trade-offs, review diffssteps — plans, migration sequences, execution checklistsslides — walkthroughs, demos, page-by-page narrativesdashboard — multi-widget operational snapshots, compact status boardsplan — task DAGs with Mermaid visualization and step tracking
Use raw synapse canvas post <format> for single blocks; templates for multi-section content.
Spawning Decision Table
⚠️ Same-model rule — try subagents first. When a Claude Code agent needs
another claude (or a codex agent needs another codex), use the in-process
subagent (Agent / Task tool for Claude, subprocess for Codex) before
reaching for synapse spawn. Spawning the same model on the same account
shares the rate-limit window — it doubles consumption against the same quota
instead of distributing it. Reserve same-model synapse spawn for cases
where the helper must outlive the parent session, needs file isolation that
subagents can't provide, or holds a distinct long-running role.
synapse spawn is the right tool for cross-model delegation
(Claude → codex / gemini), agents that lack subagent support
(Gemini / OpenCode / Copilot), or persistent multi-task helpers.
Default spawn policy: When using synapse spawn, pass the underlying CLI's
tool-specific automation args after -- so spawned agents can run unattended.
For most CLIs this is an approval-skip / auto-approve flag; for OpenCode use
--agent build to select the build agent profile and rely on OpenCode's
permission config for approval behavior.
Apply the same rule to synapse team start: include the appropriate forwarded
CLI args by default, and keep teams homogeneous when those args are
CLI-specific.
Common defaults (Synapse already injects these automatically — pass --no-auto-approve
to opt out):
- 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 injects -cdefault_permissions=":workspace"; Codex 0.128+ removed --full-auto)
- OpenCode:
synapse spawn opencode --name <n> --role "<r>" -- --agent build (selects the build agent profile; not a skip-approval flag)
- Copilot CLI:
synapse spawn copilot --name <n> --role "<r>" -- --allow-all
- Claude team:
synapse team start claude claude -- --permission-mode=auto
- Gemini team:
synapse team start gemini gemini -- --approval-mode=yolo
- Codex team:
synapse team start codex codex (synapse injects -cdefault_permissions=":workspace")
- OpenCode team:
synapse team start opencode opencode -- --agent build (selects the build agent profile; permission prompts still depend on OpenCode config)
- Copilot team:
synapse team start copilot copilot -- --allow-all
2026-04 migration: Anthropic deprecated --dangerously-skip-permissions
in favor of --permission-mode=auto (safety classifier instead of disabling
all checks). Gemini similarly recommends --approval-mode=yolo over the
legacy --yolo / -y short forms. Synapse now injects the new flags by
default; the legacy forms still work and remain in each profile's
alternative_flags.
| Condition | Action |
|---|
| Existing READY agent can handle it | synapse send — reuse is faster (avoids startup overhead) |
| Same-model helper needed (Claude → claude, Codex → codex) | Use the in-process subagent first (Agent/Task tool for Claude, subprocess for Codex). synapse spawn same-model shares the rate-limit window. |
| Need parallel execution | synapse spawn with --worktree -- <tool-specific-automation-args> for file isolation (cross-model preferred) |
| Task needs a different model's strengths | synapse spawn a different type (Claude spawns Gemini / Codex, etc.) |
| User specified agent count | Follow exactly |
| Single focused subtask | Subagent (same model) or synapse spawn (cross model) |
| N independent subtasks | Subagents for same-model fan-out, synapse spawn for cross-model |
Spawn lifecycle (preferred, one-command): synapse spawn --task-file ... --task-timeout 600 --notify → wait for A2A completion notification → evaluate result → synapse kill <name> -f → confirm in synapse list --json
Legacy lifecycle (only when you need control between spawn and first task): spawn → poll synapse list --json or synapse status <target> --json for READY (allow several minutes; default 30s timeout is too short for most profiles) → synapse send --notify → evaluate → synapse kill -f → confirm cleanup.
⚠️ Common pitfall: sending to an agent that is not yet READY either hangs at the HTTP layer or blocks on the internal readiness wait. Either use synapse spawn --task-file (preferred — it handles readiness for you), or explicitly confirm "status": "READY" before calling synapse send. Do not assume 30 seconds is enough — most profiles take 1-5 minutes.
Agent status set (synapse list --json .status):
| Status | Meaning | Action |
|---|
READY | Idle, can accept new work | synapse send |
SENDING_REPLY | Temporarily sending an outbound A2A send/reply POST | Wait; previous status is restored after the POST finishes |
PROCESSING | Actively working a task | Wait, or synapse interrupt if stuck |
WAITING | Awaiting a permission/approval prompt | synapse approve / synapse reject |
WAITING_FOR_INPUT | Task is paused asking for non-permission input (#538) | synapse reply <task_id> with the answer |
RATE_LIMITED | Last task failed due to LLM provider rate limit (#561) | Wait for the provider window to reset, then re-send |
DONE | Task complete; demotes to READY after ~10s | Read result, then proceed |
SHUTTING_DOWN | Agent is exiting | Do not send |
Stuck on a CLI dialog (not A2A WAITING)? When an agent looks idle but is
blocked on its own TUI prompt (codex edit-confirmation, model picker,
rate-limit dialog), use synapse send-keys <target> <keys> to write directly
to the PTY without synapse jump. Example: synapse send-keys Impl a sends
the codex "don't ask again" shortcut. (#695)
Killing spawned agents after completion frees ports, memory, and PTY sessions,
and prevents orphaned agents from accidentally accepting future tasks.
synapse spawn gemini \
--name Tester \
--role "test writer" \
--task-file /tmp/test-spec.md \
--task-timeout 600 \
--notify
synapse kill Tester -f
synapse list --json
If synapse kill fails or the agent still appears in synapse list --json, retry with -f,
check the agent status/logs, and report the cleanup failure instead of leaving an
orphaned agent behind.
Response Mode Guide
Choose based on whether you need the result:
| Mode | Flag | Use When |
|---|
| Wait | --wait | You need the answer before continuing (questions, reviews) |
| Notify | --notify (default) | Async — you'll be notified on completion |
| Silent | --silent | Fire-and-forget delegation (no response needed; sender history still updates best-effort on completion) |
Worker Agent Guide
When you receive a task from a manager:
On Task Receipt
- Start work immediately (
synapse reply is valid for Synapse-tracked messages with a registered reply target, including [REPLY EXPECTED] and --response; otherwise user-pasted A2A: text has no reply target, so respond with synapse send instead)
- Check shared knowledge:
synapse memory search "<task topic>"
- Lock files before editing (skip if SYNAPSE_WORKTREE_PATH is set):
synapse file-safety lock <file> $SYNAPSE_AGENT_ID
During Work
- Report progress if task takes >5 minutes:
synapse send <manager> "Progress: <update>" --silent
- Report blockers immediately:
synapse send <manager> "<question>" --wait
- Save findings:
synapse memory save <key> "<finding>" --tags <topic>
- You can delegate subtasks too — spawn helpers (prefer different model types)
- Always clean up agents you spawn:
synapse kill <name> -f
On Completion
- Report to manager:
synapse send <manager> "Done: <summary>" --silent
On Failure
- Report details:
synapse send <manager> "Failed: <error details>" --silent
Related Skills
| Skill | Purpose |
|---|
synapse-manager | Multi-agent orchestration workflow (delegation, monitoring, verification) |
synapse-reinst | Re-inject instructions after /clear or context reset |
References
For detailed information, consult these reference files:
| Reference | Contents |
|---|
references/commands.md | Full CLI command documentation with all options |
references/api.md | A2A endpoints, readiness gate, error handling |
references/examples.md | Multi-agent workflow examples and patterns |
references/file-safety.md | File locking workflow and commands |
references/messaging.md | Sending, replying, priorities, status states, interactive controls |
references/spawning.md | Spawn lifecycle, patterns, worktree, permissions, API |
references/collaboration.md | Agent naming, external agents, auth, resume, path overrides |
references/features.md | Sessions, workflows, saved agents, tokens, skills, settings, Canvas |
