Synapse A2A

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

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
Testing
Configuration (.synapse)
Development & Release

Features

Category	Feature
A2A Compliant	All communication uses Message/Part + Task format, Agent Card discovery
CLI Integration	Turn existing CLI tools into A2A agents without modification
@Agent Syntax	Send messages directly with `@claude`, `@codex-8120`
Sender Identification	Auto-identify sender via `metadata.sender` + PID matching
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
Task Delegation	Auto-forward tasks to other agents via natural language rules
File Safety	Prevent multi-agent conflicts with file locking and change tracking (visible in `synapse list`)
Agent Monitor	Real-time status (READY/WAITING/PROCESSING/DONE), terminal jump with Enter/j key

Prerequisites

OS: macOS / Linux (Windows via WSL2 recommended)
Python: 3.10+
CLI Tools: Pre-install and configure the agents you want to use:

Quick Start

1. Install Synapse A2A

# Install from PyPI (recommended)
pip install synapse-a2a

# With gRPC support
pip install "synapse-a2a[grpc]"

For developers (editing this repository):

# Install with uv
uv sync

# Or pip (editable)
pip install -e .

2. Install Skills (Recommended)

Installing skills is strongly recommended to get the most out of Synapse A2A.

Skills help Claude automatically understand Synapse A2A features: @agent messaging, task delegation, File Safety, and more.

# Install via skills.sh (https://skills.sh/)
npx skills add s-hiraoku/synapse-a2a

See Skills for details.

3. Start Agents

# Terminal 1: Claude
synapse claude

# Terminal 2: Codex
synapse codex

# Terminal 3:

...

s-hiraoku/synapse-a2a

README