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
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
- Quick Start
- 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
| Category | Feature |
|---|---|
| A2A Compliant | All communication uses Message/Part + Task format, Agent Card discovery |
| Agent Card Context Extension | Pass system context (ID, routing rules, other agents) via x-synapse-context to keep PTY clean |
| CLI Integration | Turn existing CLI tools into A2A agents without modification |
| synapse send | Send messages between agents via synapse send <agent> "message". Waits up to 30s for PROCESSING targets to finish before delivering (skipped for --force, priority 5, and --silent) |
| Sender Identification | Auto-identify sender via SYNAPSE_AGENT_ID env var → metadata.sender + PID matching (process ancestry, fallback) |
| Readiness Gate | /tasks/send returns 503 until agent initialization completes; priority 5 and replies bypass |
| Priority Interrupt | Priority 5 sends SIGINT before message (emergency stop) |
| Multi-Instance | Run multiple agents of the same type (automatic port assignment) |
| External Integration | Communicate with other Google A2A agents |
| File Safety | Prevent multi-agent conflicts with file locking and change tracking (visible in synapse list) |
| Agent Naming | Custom names and roles for easy identification (synapse send my-claude "hello") |
| Agent Summary | Persistent 120-char agent summary (synapse set-summary). Manual text, --auto from git context, or --clear. Visible in Canvas, MCP list_agents, Agent Card extensions.synapse, and synapse list --columns SUMMARY |
| Agent Monitor | Real-time status (READY/WAITING/PROCESSING/DONE), CURRENT task preview, terminal jump |
| Task History | Automatic task tracking with search, export, and statistics (enabled by default) |
| Quality Gates | Configurable hooks (on_idle, on_task_completed) that control status transitions |