| name | synapse-a2a |
| description | This skill provides comprehensive guidance for inter-agent communication using the Synapse A2A framework. Use this skill when sending messages to other agents, routing @agent patterns, understanding priority levels, handling A2A protocol operations, managing task history, configuring settings, or using File Safety features for multi-agent coordination. Automatically triggered when agent communication, A2A protocol tasks, history operations, or file safety operations are detected. |
Synapse A2A Communication
Inter-agent communication framework via Google A2A Protocol.
Quick Reference
| Task | Command |
|---|
| List agents (Rich TUI) | synapse list (event-driven refresh via file watcher with 10s fallback, ↑/↓ or 1-9 to select, Enter/j jump, k kill, / filter) |
| Send message | synapse send <target> "<message>" --from <sender> |
| Wait for reply | synapse send <target> "<message>" --response --from <sender> |
| Reply to last message | synapse reply "<response>" --from <agent> |
| Emergency stop | synapse send <target> "STOP" --priority 5 --from <sender> |
| Stop agent | synapse stop <profile|id> |
| Kill agent | synapse kill <target> (with confirmation, use -f to force) |
| Jump to terminal | synapse jump <target> |
| Rename agent | synapse rename <target> --name <name> --role <role> |
| Check file locks | synapse file-safety locks |
| View history | synapse history list |
| Initialize settings | synapse init |
| Edit settings (TUI) | synapse config (includes List Display for column config) |
| View settings | synapse config show [--scope user|project] |
| Show instructions | synapse instructions show <agent> |
| Send instructions | synapse instructions send <agent> [--preview] |
| Version info | synapse --version |
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.
synapse send gemini "Please review this code" --response --from synapse-claude-8100
synapse send claude "What is the status?" --response --from synapse-codex-8121
synapse 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):
- Custom name:
my-claude (highest priority, exact match, case-sensitive)
- Exact ID:
synapse-claude-8100 (direct match)
- Type-port:
claude-8100, codex-8120, opencode-8130, copilot-8140 (shorthand)
- 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)
synapse send gemini "What is the best approach?" --response --from synapse-claude-8100
synapse send codex "FYI: Build completed" --no-response --from synapse-claude-8100
Roundtrip Communication (--response)
For request-response patterns:
synapse send gemini "Analyze this data" --response --from synapse-claude-8100
synapse reply "Analysis result: ..." --from synapse-gemini-8110
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.
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:
synapse 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/..." --from synapse-codex-8121
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
| Priority | Description | Use Case |
|---|
| 1-2 | Low | Background tasks |
| 3 | Normal | Standard tasks |
| 4 | Urgent | Follow-ups, status checks |
| 5 | Interrupt | Emergency (sends SIGINT first) |
synapse send gemini "Analyze this" --response --from synapse-claude-8100
synapse send claude "Urgent review needed" --response --priority 4 --from synapse-codex-8121
synapse send codex "STOP" --priority 5 --from synapse-claude-8100
Agent Status
| Status | Meaning | Color |
|---|
| READY | Idle, waiting for input | Green |
| WAITING | Awaiting user input (selection, confirmation) | Cyan |
| PROCESSING | Busy handling a task | Yellow |
| DONE | Task completed (auto-clears after 10s) | Blue |
Verify before sending: Run synapse list and confirm the target agent's Status column shows READY:
synapse list
Status meanings:
READY: Safe to send messagesWAITING: Agent needs user input - use terminal jump (see below) to respondPROCESSING: Busy, wait or use --priority 5 for emergency interruptDONE: Recently completed, will return to READY shortly
Interactive Controls
In synapse list, you can interact with agents:
| Key | Action |
|---|
1-9 | Select agent row (direct) |
↑/↓ | Navigate agent rows |
Enter or j | Jump to selected agent's terminal |
k | Kill selected agent (with confirmation) |
/ | Filter by TYPE or WORKING_DIR |
ESC | Clear filter first, then selection |
q | Quit |
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 - Focuses agent's terminal pane
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:
synapse claude --name my-claude --role "code reviewer"
synapse claude --no-setup
synapse rename synapse-claude-8100 --name my-claude --role "test writer"
synapse rename my-claude --role "documentation"
synapse rename my-claude --clear
Once named, use the custom name for all operations:
synapse send my-claude "Review this code" --from synapse-codex-8121
synapse jump my-claude
synapse 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
Key Features
- Agent Naming: Custom names and roles for easy identification
- Agent Communication:
synapse send command, 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
- Settings: Configure via
settings.json (synapse init)
- Approval Mode: Control initial instruction approval (
approvalMode in settings)
References
For detailed documentation, read:
references/commands.md - Full CLI command referencereferences/file-safety.md - File Safety detailed guidereferences/api.md - A2A endpoints and message formatreferences/examples.md - Multi-agent workflow examples
