synapse-a2a

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.

synapse send gemini "Please review this code" --from claude
synapse send claude "What is the status?" --from codex
synapse send codex-8120 "Fix this bug" --priority 3 --from gemini

Important: Always use --from to identify yourself so the recipient knows who sent the message and can reply.

Target Resolution (Matching Priority):

1. Exact ID: synapse-claude-8100 (direct match)
2. Type-port: claude-8100, codex-8120, opencode-8130, copilot-8140 (shorthand)
3. 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 type-port shorthand (e.g., claude-8100) instead.

Choosing --response vs --no-response

Rule: If your message asks for a reply, use --response

# Question - needs reply
synapse send gemini "What is the best approach?" --response --from claude

# Delegation - no reply needed
synapse send codex "Run tests and fix failures" --from claude

Roundtrip Communication (--response / --reply-to)

For request-response patterns:

# Sender: Wait for response (blocks until reply received)
synapse send gemini "Analyze this data" --response --from claude

# Receiver: Reply to the request (use task_id from [A2A:task_id:sender])
synapse send claude "Analysis result: ..." --reply-to <task_id> --from gemini

The --response flag makes the sender wait. The receiver MUST use --reply-to with the task_id to link the response.

Short Task IDs & :R Flag: PTY displays 8-character short IDs. When the sender used --response, a :R suffix appears after the sender_id to indicate a reply is required:

• With --response: [A2A:54241e7e:synapse-claude-8100:R] - reply required
• Without --response: [A2A:54241e7e:synapse-claude-8100] - no reply needed

Use the task_id (not including :R) with --reply-to:

• Short ID: --reply-to 54241e7e
• Full UUID: --reply-to 54241e7e-1234-5678-abcd-ef1234567890

Receiving and Replying to Messages

When you receive an A2A message, it appears as:

[A2A:<task_id>:<sender_id>:R] <message>   ← Response required (:R flag)
[A2A:<task_id>:<sender_id>] <message>     ← No response required

When to use --reply-to:

# :R flag present → use --reply-to (task_id only, not including :R)
synapse send claude "Here is my analysis..." --reply-to abc12345 --from gemini

# If sender delegated a task → just do the task, no --reply-to needed

Example - Question:

Received: [A2A:abc12345:synapse-claude-8100] What is the project structure?
Reply:    synapse send claude "The project has src/, tests/..." --reply-to abc12345 --from gemini

Example - Delegation:

Received: [A2A:xyz67890:synapse-claude-8100] Run the tests and fix failures
Action:   Just do the task. No reply needed unless you have questions.

Priority Levels

# Normal priority (default)
synapse send gemini "Analyze this"

# Higher priority
synapse send claude "Urgent review needed" --priority 4

# Emergency interrupt
synapse send codex "STOP" --priority 5

Agent Status

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

synapse list
# Output:
# NAME                  TYPE    STATUS      PORT   WORKING_DIR
# synapse-claude-8100   claude  READY       8100   my-project
# synapse-gemini-8110   gemini  WAITING     8110   my-project  # <- needs user input
# synapse-codex-8120    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 - Focuses agent's terminal pane

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

Key Features

• Agent Communication: @agent pattern, priority control, response handling
• Task History: Search, export, statistics (synapse history)
• File Safety: Lock files to prevent conflicts (synapse file-safety)
• Settings: Configure via settings.json (synapse init)

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