Synapse A2a

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

Collaboration Decision Framework

Evaluate collaboration opportunities before starting work:

Recommended Collaboration Gate (3+ phases OR 10+ file changes): Consider these steps before diving into large work:

1. synapse list --json or MCP list_agents — check available agents
2. synapse memory search "<topic>" — check if someone already solved this
3. Build Agent Assignment Plan (Phase / Agent / Rationale) when delegation is beneficial
4. 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

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 summaries
• comparison — before/after, option trade-offs, review diffs
• steps — plans, migration sequences, execution checklists
• slides — walkthroughs, demos, page-by-page narratives
• dashboard — multi-widget operational snapshots, compact status boards
• plan — 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.

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):

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.

# 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)

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:

Worker Agent Guide

When you receive a task from a manager:

On Task Receipt

1. 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)
2. Check shared knowledge: synapse memory search "<task topic>"
3. 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

1. Report to manager: synapse send <manager> "Done: <summary>" --silent

On Failure

1. Report details: synapse send <manager> "Failed: <error details>" --silent

Related Skills

References

For detailed information, consult these reference files: