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

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