s-hiraoku-synapse-a2a

Synapse A2A

🌐 Language: English | 日本語 | 中文 | 한국어 | Español | Français

Enable agents to collaborate on tasks without changing their behavior

A framework that enables inter-agent collaboration via the Google A2A Protocol while keeping CLI agents (Claude Code, Codex, Gemini, OpenCode, GitHub Copilot CLI) exactly as they are

Quick Start

This golden path starts two background agents and sends one visible cross-agent message in four commands.

Prerequisites (not counted): run uv sync, and make sure authenticated claude and codex CLIs are installed on your PATH.

uv run synapse start claude --port 8108

What to expect: Synapse starts a Claude A2A server in the background and prints a PID plus the log path.

uv run synapse start codex --port 8122

What to expect: Synapse starts a Codex A2A server in the background and prints a PID plus the log path.

uv run synapse list --plain

What to expect: the one-shot agent list includes synapse-claude-8108 and synapse-codex-8122; wait or answer any agent prompt until both show READY.

uv run synapse send synapse-codex-8122 "Reply with exactly: SYNAPSE_GOLDEN_PATH_OK" --from synapse-claude-8108 --wait

What to expect: Codex receives an A2A message from Claude and the command prints a reply containing SYNAPSE_GOLDEN_PATH_OK. If the send call fails with a UDS or HTTP timeout, run uv run synapse list --plain again and wait until both agents show READY before rerunning. If the receiver pauses for approval, answer the prompt in the agent terminal.

Cleanup (not counted):

uv run synapse kill claude-8108 -f
uv run synapse kill codex-8122 -f

See issue #604 for context.

Project Goals

┌─────────────────────────────────────────────────────────────────┐
│  ✅ Non-Invasive: Don't change agent behavior                   │
│  ✅ Collaborative: Enable agents to work together               │
│  ✅ Transparent: Maintain existing workflows                    │
└─────────────────────────────────────────────────────────────────┘

Synapse A2A transparently wraps each agent's input/output without modifying the agent itself. This means:

• Leverage each agent's strengths: Users can freely assign roles and specializations
• Zero learning curve: Continue using existing workflows
• Future-proof: Resistant to agent updates

See Project Philosophy for details.

flowchart LR
    subgraph Terminal1["Terminal 1"]
        subgraph Agent1["synapse claude :8100"]
            Server1["A2A Server"]
            PTY1["PTY + Claude CLI"]
        end
    end
    subgraph Terminal2["Terminal 2"]
        subgraph Agent2["synapse codex :8120"]
            Server2["A2A Server"]
            PTY2["PTY + Codex CLI"]
        end
    end
    subgraph External["External"]
        ExtAgent["Google A2A Agent"]
    end

    Server1 <-->|"POST /tasks/send"| Server2
    Server1 <-->|"A2A Protocol"| ExtAgent
    Server2 <-->|"A2A Protocol"| ExtAgent

---

Table of Contents

• Features
• Prerequisites
• Installation
• Use Cases
• Skills
• Documentation
• Architecture
• CLI Commands
• API Endpoints
• Task Structure
• Sender Identification
• Priority Levels
• Agent Card
• Registry and Port Management
• File Safety
• Agent Monitor
• CI Automation (Claude Code)
• Testing
• Configuration (.synapse)
• Development & Release

---

Features