Synapse A2A Communication

Inter-agent communication framework via Google A2A Protocol.

Quick Reference

Tip: Run synapse list before sending to verify the target agent is READY.

Sending Messages (Recommended)

Use synapse send command for inter-agent communication. This works reliably from any environment including sandboxed agents.

bash
1synapse send gemini "Please review this code" --response --from synapse-claude-8100
2synapse send claude "What is the status?" --response --from synapse-codex-8121
3synapse send codex-8120 "Fix this bug" --response --priority 3 --from synapse-gemini-8110

Important:

• Always use --from with your agent ID (format: synapse-<type>-<port>). Do NOT use custom names or agent types for --from.
• By default, use --response to wait for a reply. Only use --no-response for notifications or fire-and-forget tasks.

Target Resolution (Matching Priority):

1. Custom name: my-claude (highest priority, exact match, case-sensitive)
2. Exact ID: synapse-claude-8100 (direct match)
3. Type-port: claude-8100, codex-8120, opencode-8130, copilot-8140 (shorthand)
4. Type only: claude, gemini, codex, opencode, copilot (only if single instance)

Note: When multiple agents of the same type are running, type-only targets (e.g., claude) will fail with an ambiguity error. Use custom name (e.g., my-claude) or type-port shorthand (e.g., claude-8100) instead.

Choosing --response vs --no-response

Analyze the message content and determine if a reply is expected:

• If the message expects or benefits from a reply → use --response
• If the message is purely informational with no reply needed → use --no-response
• If unsure, use --response (safer default)

bash
1# Message that expects a reply
2synapse send gemini "What is the best approach?" --response --from synapse-claude-8100
3
4# Purely informational, no reply needed
5synapse send codex "FYI: Build completed" --no-response --from synapse-claude-8100

Roundtrip Communication (--response)

For request-response patterns:

bash
1# Sender: Wait for response (blocks until reply received)
2synapse send gemini "Analyze this data" --response --from synapse-claude-8100
3
4# Receiver: Reply to sender (auto-routes via reply tracking)
5synapse reply "Analysis result: ..."

The --response flag makes the sender wait. The receiver should reply using the synapse reply command.

Reply Tracking: Synapse automatically tracks senders who expect a reply ([REPLY EXPECTED] messages). Use synapse reply for responses - it automatically knows who to reply to.

Broadcasting to All Agents

Send a message to all agents sharing the same working directory:

bash
1# Broadcast status check to all cwd agents
2synapse broadcast "Status check" --from synapse-claude-8100
3
4# Urgent broadcast
5synapse broadcast "Urgent: stop all work" --priority 4 --from synapse-claude-8100
6
7# Fire-and-forget broadcast
8synapse broadcast "FYI: Build completed" --no-response --from synapse-claude-8100

Note: Broadcast only targets agents in the same working directory as the sender. This prevents unintended messages to agents working on different projects.

Receiving and Replying to Messages

When you receive an A2A message, it appears with the A2A: prefix:

Message Formats:

A2A: [REPLY EXPECTED] <message>   <- Reply is REQUIRED
A2A: <message>                    <- Reply is optional (one-way notification)

If [REPLY EXPECTED] marker is present, you MUST reply using synapse reply.

Reply Tracking: Synapse stores sender info only for messages with [REPLY EXPECTED] marker. Multiple senders can be tracked simultaneously (each sender has one entry).

Replying to messages:

bash
1# Use the reply command (auto-routes to last sender)
2synapse reply "Here is my analysis..."
3
4# When multiple senders are pending, inspect and choose target
5synapse reply --list-targets
6synapse reply "Here is my analysis..." --to <sender_id>
7
8# In sandboxed environments (like Codex), specify your agent ID
9synapse reply "Here is my analysis..." --from <your_agent_id>

Example - Question received (MUST reply):

Received: A2A: [REPLY EXPECTED] What is the project structure?
Reply:    synapse reply "The project has src/, tests/..."

Example - Delegation received (no reply needed):

Received: A2A: Run the tests and fix failures
Action:   Just do the task. No reply needed unless you have questions.

Priority Levels

Default priority: send = 3 (normal), broadcast = 1 (low).

bash
1# Normal priority (default: 3) - with response
2synapse send gemini "Analyze this" --response --from synapse-claude-8100
3
4# Higher priority - urgent request
5synapse send claude "Urgent review needed" --response --priority 4 --from synapse-codex-8121
6
7# Emergency interrupt
8synapse send codex "STOP" --priority 5 --from synapse-claude-8100

Agent Status

Verify before sending: Run synapse list and confirm the target agent's Status column shows READY:

bash
1synapse list
2# Output (NAME column shows custom name if set, otherwise agent ID):
3# NAME        TYPE    STATUS      PORT   WORKING_DIR
4# my-claude   claude  READY       8100   my-project      # <- has custom name
5# gemini      gemini  WAITING     8110   my-project      # <- no custom name, shows type
6# codex       codex   PROCESSING  8120   my-project      # <- busy

Status meanings:

• READY: Safe to send messages
• WAITING: Agent needs user input - use terminal jump (see below) to respond
• PROCESSING: Busy, wait or use --priority 5 for emergency interrupt
• DONE: Recently completed, will return to READY shortly

Interactive Controls

In synapse list, you can interact with agents:

Supported Terminals:

• iTerm2 (macOS) - Switches to correct tab/pane
• Terminal.app (macOS) - Switches to correct tab
• Ghostty (macOS) - Activates application
• VS Code integrated terminal - Opens to working directory
• tmux - Switches to agent's session
• Zellij - Activates terminal app (direct pane focus not supported via CLI)

Use case: When an agent shows WAITING status, use terminal jump to quickly respond to its selection prompt.

Agent Naming

Assign custom names and roles to agents for easier identification:

bash
1# Start with name and role
2synapse claude --name my-claude --role "code reviewer"
3
4# Skip interactive name/role setup
5synapse claude --no-setup
6
7# Update name/role after agent is running
8synapse rename synapse-claude-8100 --name my-claude --role "test writer"
9synapse rename my-claude --role "documentation"  # Change role only
10synapse rename my-claude --clear                 # Clear name and role

Once named, use the custom name for all operations:

bash
1synapse send my-claude "Review this code" --from synapse-codex-8121
2synapse jump my-claude
3synapse kill my-claude

Name vs ID:

• Display/Prompts: Shows name if set, otherwise ID (e.g., Kill my-claude (PID: 1234)?)
• Internal processing: Always uses agent ID (synapse-claude-8100)
• Target resolution: Name has highest priority when matching targets

External Agent Management

Connect to external A2A-compatible agents over HTTP/HTTPS:

bash
1# Discover and add an external agent
2synapse external add https://agent.example.com --alias myagent
3
4# List registered external agents
5synapse external list
6
7# Show agent details (capabilities, skills)
8synapse external info myagent
9
10# Send message to external agent
11synapse external send myagent "Analyze this data"
12synapse external send myagent "Process file" --wait  # Wait for completion
13
14# Remove agent
15synapse external remove myagent

External agents are stored persistently in ~/.a2a/external/.

Authentication

Secure A2A communication with API key authentication:

bash
1# Interactive setup (generates keys + shows instructions)
2synapse auth setup
3
4# Generate API key(s)
5synapse auth generate-key
6synapse auth generate-key -n 3 -e  # 3 keys in export format
7
8# Enable authentication
9export SYNAPSE_AUTH_ENABLED=true
10export SYNAPSE_API_KEYS=<key>
11export SYNAPSE_ADMIN_KEY=<admin_key>
12synapse claude

Resume Mode

Start agents without sending initial instructions (for session recovery):

bash
1synapse claude -- --resume
2synapse gemini -- --resume
3synapse codex -- resume        # Codex: resume is a subcommand
4synapse opencode -- --continue
5synapse copilot -- --continue

To inject instructions later: synapse instructions send <agent>.

Key Features

• Agent Naming: Custom names and roles for easy identification
• Agent Communication: synapse send command, synapse broadcast for cwd-scoped messaging, priority control, response handling
• Task History: Search, export, statistics (synapse history)
• File Safety: Lock files to prevent conflicts (synapse file-safety); active locks shown in synapse list EDITING_FILE column
• External Agents: Connect to external A2A agents (synapse external)
• Authentication: API key-based security (synapse auth)
• Skill Management: Central skill store, deploy, import, create, skill sets (synapse skills). Skill set details (name, description, skills) are included in agent initial instructions when selected.
• Settings: Configure via settings.json (synapse init)
• Approval Mode: Control initial instruction approval (approvalMode in settings)
• Shared Task Board: Create, claim, and complete tasks with dependency tracking (synapse tasks)
• Quality Gates: Configurable hooks (on_idle, on_task_completed) that gate status transitions
• Plan Approval: Plan-mode workflow with synapse approve/reject for review
• Graceful Shutdown: synapse kill sends shutdown request before SIGTERM (30s timeout)
• Delegate Mode: --delegate-mode creates a coordinator that delegates instead of editing files
• Auto-Spawn Panes: synapse team start — 1st agent takes over current terminal (handoff), others in new panes. --all-new for all new panes. Supports profile:name:role:skill_set spec (tmux/iTerm2/Terminal.app/zellij)
• Spawn Single Agent: synapse spawn <profile> — Spawn a single agent in a new terminal pane or window. Automatically uses --headless mode.

Spawning Agents

Spawn a single agent in a new terminal pane or window.

bash
1synapse spawn claude                          # Spawn Claude in a new pane
2synapse spawn gemini --port 8115              # Spawn with explicit port
3synapse spawn claude --name Tester --role "test writer"  # With name/role
4synapse spawn claude --terminal tmux          # Use specific terminal

Headless Mode: When an agent is started via synapse spawn, it automatically runs with the --headless flag. This skips all interactive setup (name/role prompts, startup animations, and initial instruction approval prompts) to allow for smooth programmatic orchestration. The A2A server remains active, and initial instructions are still sent to enable communication.

Note: The spawning agent is responsible for the lifecycle of the spawned agent. Ensure you terminate spawned agents using synapse kill <target> -f when their task is complete.

Pane Auto-Close: When an agent process terminates, the pane/tab/window closes automatically in all supported terminals. Zellij uses --close-on-exit; iTerm2, Terminal.app, and Ghostty use exec to replace the shell process; tmux split-window closes natively on process exit.

Path Overrides

When running multiple environments or tests, override storage paths via env vars:

• SYNAPSE_REGISTRY_DIR (default: ~/.a2a/registry)
• SYNAPSE_EXTERNAL_REGISTRY_DIR (default: ~/.a2a/external)
• SYNAPSE_HISTORY_DB_PATH (default: ~/.synapse/history/history.db)
• SYNAPSE_SKILLS_DIR (default: ~/.synapse/skills)

References

For detailed documentation, read:

• references/commands.md - Full CLI command reference
• references/file-safety.md - File Safety detailed guide
• references/api.md - A2A endpoints and message format
• references/examples.md - Multi-agent workflow examples