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

Prerequisites

• OS: macOS / Linux (Windows via WSL2 recommended)
• Python: 3.10+
• CLI Tools: Pre-install and configure the agents you want to use:
  • Claude Code
  • Codex CLI
  • Gemini CLI
  • OpenCode
  • GitHub Copilot CLI

Installation

1. Install Synapse A2A

# pipx (recommended)
pipx install synapse-a2a

# Or run directly with uvx (no install)
uvx synapse-a2a claude

# Inside WSL2 — same as Linux
pipx install synapse-a2a

# Scoop (experimental, WSL2 still required for pty)
scoop bucket add synapse-a2a https://github.com/s-hiraoku/scoop-synapse-a2a
scoop install synapse-a2a

# Install with uv
uv sync

# Or pip (editable)
pip install -e .

With gRPC support:

pip install "synapse-a2a[grpc]"

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, File Safety, and more.

# Requires GitHub CLI 2.90.0+
# https://github.blog/changelog/2026-04-16-manage-agent-skills-with-github-cli/
gh skill install s-hiraoku/synapse-a2a synapse-a2a
gh skill install s-hiraoku/synapse-a2a synapse-manager
# Pin a release: gh skill install s-hiraoku/synapse-a2a synapse-a2a --pin v0.26.4
# Target a specific agent runtime: ... --agent claude-code

See Skills for details and
docs/skills-management.md for the full
migration matrix. The legacy npx skills add ... / skills.sh path
still works but is no longer the recommended way to install — use
gh skill install for version pinning and provenance tracking.

3. Start Agents

# Terminal 1: Claude
synapse claude

# Terminal 2: Codex
synapse codex

# Terminal 3: Gemini
synapse gemini

# Terminal 4: OpenCode
synapse opencode

# Terminal 5: GitHub Copilot CLI
synapse copilot

Note: If terminal scrollback display is garbled, try:

uv run synapse gemini
# or
uv run python -m synapse.cli gemini

Ports are auto-assigned:

4. Inter-Agent Communication

Use synapse send to send messages between agents. The --from flag is optional -- Synapse auto-detects the sender from SYNAPSE_AGENT_ID (set at startup):

synapse send codex "Please review this design"
synapse send gemini "Suggest API improvements"

For multiple instances of the same type, use type-port format:

synapse send codex-8120 "Handle this task"
synapse send codex-8121 "Handle that task"

5. HTTP API

# Send message
curl -X POST http://localhost:8100/tasks/send \
  -H "Content-Type: application/json" \
  -d '{"message": {"role": "user", "parts": [{"type": "text", "text": "Hello!"}]}}'

# Emergency stop (Priority 5)
curl -X POST "http://localhost:8100/tasks/send-priority?priority=5" \
  -H "Content-Type: application/json" \
  -d '{"message": {"role": "user", "parts": [{"type": "text", "text": "Stop!"}]}}'

Use Cases

1. Instant Specification Lookup (Simple)

While coding with Claude, quickly query Gemini (better at web search) for the latest library specs or error info without context switching.

# In Claude's terminal:
synapse send gemini "Summarize the new f-string features in Python 3.12"

2. Cross-Review Designs (Intermediate)

Get feedback on your design from agents with different perspectives.

# After Claude drafts a design:
synapse send gemini "Critically review this design from scalability and maintainability perspectives"

3. TDD Pair Programming (Intermediate)

Separate "test writer" and "implementer" for robust code.

# Terminal 1 (Codex):
Create unit tests for auth.py - normal case and token expiration case.

# Terminal 2 (Claude):
synapse send codex-8120 "Implement auth.py to pass the tests you created"

4. Security Audit (Specialized)

Have an agent with a security expert role audit your code before committing.

# Give Gemini a role:
You are a security engineer. Review only for vulnerabilities (SQLi, XSS, etc.)

# After writing code:
synapse send gemini "Audit the current changes (git diff)"

5. Auto-Fix from Error Logs (Advanced)

Pass error logs to an agent for automatic fix suggestions.

# Tests failed...
pytest > error.log

# Ask agent to fix
synapse send claude "Read error.log and fix the issue in synapse/server.py"

6. Language/Framework Migration (Advanced)

Distribute large refactoring work across agents.

# Terminal 1 (Claude):
Read legacy_api.js and create TypeScript type definitions

# Terminal 2 (Codex):
synapse send claude "Use the type definitions you created to rewrite legacy_api.js to src/new_api.ts"

7. Proactive Collaboration with Cross-Model Spawning (Advanced)

Agents proactively assess when to delegate, spawn helpers, or share knowledge. The collaboration framework encourages cross-model spawning to distribute token usage across providers and avoid rate limits.

# Manager spawns a different model type for a subtask (cross-model preference)
synapse spawn gemini --worktree --name Tester --role "test writer"

# Spawn on a specific branch (--branch auto-enables --worktree)
synapse spawn codex --branch renovate/major-eslint-monorepo --name Fixer --role "dependency updater"

# Spawn + send task in one step (polls for READY then auto-sends)
synapse spawn gemini --worktree --name Tester --role "test writer" \
  --task "Write integration tests for auth module" --notify

# Or delegate manually after spawn (prefer --notify over --wait)
synapse send Tester "Write integration tests for auth module" --notify

# Share discoveries via LLM Wiki for all agents to use
synapse wiki ingest docs/auth-pattern.md --scope project

# Merge worktree branch without stopping the agent (integrate intermediate results)
synapse merge Tester

# MANDATORY: Always clean up agents you spawn (worktree branches auto-merge back)
synapse kill Tester -f
# Skip auto-merge if you want to review the branch first
synapse kill Tester -f --no-merge

Key principles:

• Cross-model preference: Spawn different model types (Claude, Gemini, Codex) to leverage diverse strengths and distribute rate limit pressure
• Worker autonomy: Any agent can spawn helpers and delegate, not just managers
• Check before spawning: Run synapse list first to reuse existing READY agents before spawning new ones
• Mandatory cleanup: Always synapse kill <name> -f agents you spawned after their work completes. Worktree branches are auto-merged; use --no-merge to skip
• Feature usage: Actively use LLM Wiki, file safety, worktree, broadcast, and history

8. Cross-Worktree Knowledge Transfer (Advanced)

Share skills, config, or investigation results with agents running in different worktrees. Synapse automatically detects worktree relationships (parent, child, and sibling worktrees of the same repo), so --force is not needed for related worktree agents. Use --message-file for messages containing backticks or code blocks to avoid shell expansion issues.

# Spawn a worker in its own worktree
synapse spawn codex --worktree feature-api --name Cody --role "API implementation"

# Spawn on a non-main base branch (--branch auto-enables --worktree)
synapse spawn codex --worktree feature-api --branch develop --name Cody --role "API implementation"

# Write instructions to a file (avoids shell expansion of backticks)
cat > /tmp/instructions.md << 'EOF'
## /release skill usage
Run `/release patch` to bump the patch version.
EOF

# Send across worktree boundaries (no --force needed for related worktrees)
synapse send Cody --message-file /tmp/instructions.md --silent

Alternatives: --attach sends files without needing --message-file. synapse memory save is directory-agnostic and works across all agents.

Comparison with SSH Remote

Note: SSH is often sufficient for individual CLI use. Synapse shines when you need automation, coordination, and multi-agent collaboration.

Skills

Installing skills is strongly recommended when using Synapse A2A with Claude Code.

Why Install Skills?

With skills installed, Claude automatically understands and executes:

• synapse send: Inter-agent communication via synapse send codex "Fix this" (sender auto-detected)
• Priority control: Message sending with Priority 1-5 (5 = emergency stop)
• File Safety: Prevent multi-agent conflicts with file locking and change tracking
• History management: Search, export, and statistics for task history

Installation

Install via the GitHub CLI (requires gh 2.90.0+):

# Install core skills from this repository
gh skill install s-hiraoku/synapse-a2a synapse-a2a
gh skill install s-hiraoku/synapse-a2a synapse-manager

# Pin to a release tag so updates are explicit
gh skill install s-hiraoku/synapse-a2a synapse-a2a --pin v0.26.4

# Install for a specific agent runtime
gh skill install s-hiraoku/synapse-a2a synapse-a2a --agent claude-code
gh skill install s-hiraoku/synapse-a2a synapse-a2a --agent copilot

# Preview a skill before installing
gh skill preview s-hiraoku/synapse-a2a synapse-a2a

# Check for upstream changes on installed skills
gh skill update

Each installed skill's SKILL.md frontmatter records the source
repository, ref, and tree SHA, so gh skill update can detect
drift and --pin gives you a deterministic version.

Legacy path — npx skills add s-hiraoku/synapse-a2a
(skills.sh) still works for older gh installs, but gh skill
is the recommended tool going forward. See
docs/skills-management.md for the
migration matrix.

Included Skills

Core Skills: Essential skills like synapse-a2a are automatically deployed to agent directories on startup (best-effort) to ensure basic quality even if skill sets are skipped.

Skill Management

Synapse includes a built-in skill manager with a central store (~/.synapse/skills/) for organizing and deploying skills across agents.

Skill Scopes

Commands

# Interactive TUI
synapse skills

# List and browse
synapse skills list                          # All scopes
synapse skills list --scope synapse          # Central store only
synapse skills show <name>                   # Skill details

# Manage
synapse skills delete <name> [--force]
synapse skills move <name> --to <scope>

# Central store operations
synapse skills import <name>                 # Import from agent dirs to ~/.synapse/skills/
synapse skills deploy <name> --agent claude,codex --scope user
synapse skills add <repo>                    # Install from repo (legacy wrapper; prefer `gh skill install`)
synapse skills create                        # Show guided skill creation steps

# Skill sets (named groups)
synapse skills set list
synapse skills set show <name>
synapse skills apply <target> <set_name>     # Apply skill set to running agent
synapse skills apply <target> <set_name> --dry-run  # Preview changes without applying

Default Skill Sets

Synapse ships with 6 built-in skill sets (defined in .synapse/skill_sets.json):

Directory Structure

plugins/
└── synapse-a2a/
    ├── .claude-plugin/plugin.json
    ├── README.md
    └── skills/
        ├── synapse-a2a/
        │   ├── SKILL.md
        │   └── references/          # api, collaboration, commands, examples, features, file-safety, messaging, spawning
        └── synapse-manager/
            ├── SKILL.md
            ├── references/          # auto-approve-flags, commands-quick-ref, features-table, worker-guide
            └── scripts/             # wait_ready.sh, check_team_status.sh, regression_triage.sh

See plugins/synapse-a2a/README.md for details.

Note: Codex and Gemini don't support plugins, but you can place expanded skills in the .agents/skills/ directory to enable these features.

Documentation

• guides/README.md - Documentation overview
• guides/multi-agent-setup.md - Setup guide
• guides/usage.md - Commands and usage patterns
• guides/settings.md - .synapse configuration details
• guides/troubleshooting.md - Common issues and solutions

Architecture

A2A Server/Client Structure

In Synapse, each agent operates as an A2A server. There's no central server; it's a P2P architecture.

┌─────────────────────────────────────┐    ┌─────────────────────────────────────┐
│  synapse claude (port 8100)         │    │  synapse codex (port 8120)          │
│  ┌───────────────────────────────┐  │    │  ┌───────────────────────────────┐  │
│  │  FastAPI Server (A2A Server)  │  │    │  │  FastAPI Server (A2A Server)  │  │
│  │  /.well-known/agent.json      │  │    │  │  /.well-known/agent.json      │  │
│  │  /tasks/send                  │◄─┼────┼──│  A2AClient                    │  │
│  │  /tasks/{id}                  │  │    │  └───────────────────────────────┘  │
│  └───────────────────────────────┘  │    │  ┌───────────────────────────────┐  │
│  ┌───────────────────────────────┐  │    │  │  PTY + Codex CLI              │  │
│  │  PTY + Claude CLI             │  │    │  └───────────────────────────────┘  │
│  └───────────────────────────────┘  │    └─────────────────────────────────────┘
└─────────────────────────────────────┘

Each agent is:

• A2A Server: Accepts requests from other agents
• A2A Client: Sends requests to other agents

Key Components

Startup Sequence

sequenceDiagram
    participant Synapse as Synapse Server
    participant Registry as AgentRegistry
    participant PTY as TerminalController
    participant CLI as CLI Agent

    Synapse->>Registry: 1. Register agent (agent_id, pid, port)
    Synapse->>PTY: 2. Start PTY
    PTY->>CLI: 3. Start CLI agent
    Synapse->>PTY: 4. Send minimal bootstrap message (sender: synapse-system)
    PTY->>CLI: 5. AI retrieves system context via Agent Card (x-synapse-context)

Communication Flow

sequenceDiagram
    participant User
    participant Claude as Claude (8100)
    participant Client as A2AClient
    participant Codex as Codex (8120)

    User->>Claude: @codex Review this design
    Claude->>Client: send_to_local()
    Client->>Codex: POST /tasks/send-priority
    Codex->>Codex: Create Task → Write to PTY
    Codex-->>Client: {"task": {"id": "...", "status": "working"}}
    Client-->>Claude: [→ codex] Send complete

CLI Commands

Basic Operations

# Start agent (foreground)
synapse claude
synapse codex
synapse gemini
synapse opencode
synapse copilot

# Start with custom name and role
synapse claude --name my-claude --role "code reviewer"

# Start with saved agent definition (--agent / -A)
synapse claude --agent calm-lead
synapse claude -A Claud                           # Short flag, lookup by display name

# Skip interactive name/role setup
synapse claude --no-setup

# Specify port
synapse claude --port 8105

# Pass arguments to CLI tool
synapse claude -- --resume

Agent Naming

Assign custom names and roles to agents for easier identification and management:

# Interactive setup (default when starting agent)
synapse claude
# → Prompts for name and role

# Skip interactive setup
synapse claude --no-setup

# Set name and role via CLI options
synapse claude --name my-claude --role "code reviewer"

# Load role from file (@prefix reads file content)
synapse claude --name reviewer --role "@./roles/reviewer.md"

# Use saved agent definition (--agent / -A)
synapse claude --agent calm-lead
synapse claude -A Claud                           # Short flag

# After agent is running, change name/role
synapse rename synapse-claude-8100 --name my-claude --role "test writer"
synapse rename my-claude --role "documentation"  # Change role only
synapse rename my-claude --clear                 # Clear name and role

Once named, use the custom name for all operations:

synapse send my-claude "Review this code"
synapse jump my-claude
synapse kill my-claude

Name vs ID:

• Display/Prompts: Shows name if set, otherwise ID (e.g., Kill my-claude (PID: 1234)?)
• Internal processing: Always uses Runtime ID (synapse-claude-8100)
• Target resolution: Name has highest priority when matching targets

Save Prompt on Exit

When an interactive agent session exits, Synapse can prompt to save the current
agent definition for reuse:

Save this agent definition for reuse? [y/N]:

• Triggered only for interactive synapse <profile> sessions with a configured name.
• Not shown in --headless mode or non-TTY environments.
• Not shown for synapse stop ... or synapse kill ... (those commands only stop running processes).
• Default scope is project, but switches to user when the session is running inside a worktree (issue #410). The prompt makes this explicit (default: user - project scope in a worktree is deleted on cleanup). When a worktree is cleaned up, any *.agent files saved under <worktree>/.synapse/agents/ are also copied back to the main repo's .synapse/agents/ as a safety net (main repo files win on collision).
• Disable with SYNAPSE_AGENT_SAVE_PROMPT_ENABLED=false.

Command List

Resume Mode

When resuming an existing session, use these flags to skip initial instruction sending (A2A protocol explanation), keeping your context clean:

# Resume Claude Code session
synapse claude -- --resume

# Resume Gemini with history
synapse gemini -- --resume=5

# Codex uses 'resume' as a subcommand (not --resume flag)
synapse codex -- resume --last

Default flags (customizable in settings.json):

• Claude: --resume, --continue, -r, -c
• Gemini: --resume, -r
• Codex: resume
• OpenCode: --continue, -c
• Copilot: --continue, --resume

Instruction Management

Manually resend initial instructions when they weren't sent (e.g., after --resume mode):

# Show instruction content
synapse instructions show claude

# List instruction files
synapse instructions files claude

# Send initial instructions to running agent
synapse instructions send claude

# Preview before sending
synapse instructions send claude --preview

# Send to specific Runtime ID
synapse instructions send synapse-claude-8100

Useful when:

• You need A2A protocol info after starting with --resume
• Agent lost/forgot instructions and needs recovery
• Debugging instruction content

External Agent Management

# Register external agent
synapse external add http://other-agent:9000 --alias other

# List
synapse external list

# Send message
synapse external send other "Process this task"

Task History Management

Search, browse, and analyze past agent execution results.

Note: History is enabled by default since v0.3.13. To disable:

# Disable via environment variable
export SYNAPSE_HISTORY_ENABLED=false
synapse claude

Basic Operations

# Show latest 50 entries
synapse history list

# Filter by agent
synapse history list --agent claude

# Custom limit
synapse history list --limit 100

# Show task details
synapse history show task-id-uuid

Keyword Search

Search input/output fields by keyword:

# Single keyword
synapse history search "Python"

# Multiple keywords (OR logic)
synapse history search "Python" "Docker"

# AND logic (all keywords must match)
synapse history search "Python" "function" --logic AND

# With agent filter
synapse history search "Python" --agent claude

# Limit results
synapse history search "error" --limit 20

Statistics

# Overall stats (total, success rate, per-agent breakdown)
synapse history stats

# Specific agent stats
synapse history stats --agent claude

When token usage data is available (collected via synapse/token_parser.py), synapse history stats displays a TOKEN USAGE section with aggregated input/output tokens and estimated cost per agent.

Data Export

# JSON export (stdout)
synapse history export --format json

# CSV export
synapse history export --format csv

# Save to file
synapse history export --format json --output history.json
synapse history export --format csv --agent claude > claude_history.csv

Retention Policy

# Delete data older than 30 days
synapse history cleanup --days 30

# Keep database under 100MB
synapse history cleanup --max-size 100

# Force (no confirmation)
synapse history cleanup --days 30 --force

# Dry run
synapse history cleanup --days 30 --dry-run

Storage:

• SQLite database: ~/.synapse/history/history.db (user-global)
• Stored: task ID, agent name, input, output, status, metadata
• Auto-indexed: agent_name, timestamp, task_id

Settings:

• Enabled by default (v0.3.13+)
• Disable: SYNAPSE_HISTORY_ENABLED=false

synapse send Command (Recommended)

Use synapse send for inter-agent communication. Works in sandboxed environments.

synapse send <target> "<message>" [--from <sender>] [--priority <1-5>] [--wait | --notify | --silent]

Target Formats:

When multiple agents of the same type are running, type-only (e.g., claude) will error. Use claude-8100 or synapse-claude-8100.

Options:

Message sources: Exactly one of positional message, --message-file, --task-file, or --stdin must be supplied. File/stdin inputs bypass the shell, so messages containing backticks, code fences, or long Markdown no longer trigger false shell-expansion warnings.

--wait and --notify spawn a sender-side task that produces structured A2A reply artifacts derived from the PTY output delta captured since task start. Synapse uses this delta, not the raw terminal tail, to reduce status-line noise in replies. TUI response cleaning (clean_copilot_response()) now runs for all agents, stripping Ink TUI artifacts (spinners, box-drawing borders, status bar, input echo) before finalization. In server mode, startup/runtime logs stay off stderr so they do not leak into the agent TUI. Quota-exhaustion output such as 402 You have no quota is classified as a failed task instead of a normal reply.

PROCESSING wait: When the target agent is in PROCESSING state, synapse send automatically waits up to 30 seconds for the agent to become idle before delivering the message. This prevents message loss when an agent is busy. The wait is skipped for --force, priority 5 (emergency), and --silent sends.

Choosing response mode:

Default is --notify (async notification on completion).

Working directory check: synapse send verifies that the sender's current working directory matches the target agent's working_dir. Worktree relationships are automatically detected — parent repo, child worktree, and sibling worktrees of the same repo are all allowed without --force. For truly different projects, a warning is shown with available agents in the current directory (or a synapse spawn suggestion) and the command exits with code 1. Use --force to bypass this check.

Examples:

# Task with result expected (async notification - default)
synapse send gemini "Analyze this and report findings" --notify

# Task with immediate response (blocking)
synapse send gemini "What is the best approach?" --wait

# Delegated task, fire-and-forget
synapse send codex "Fix this bug and commit" --silent

# Send message (single instance; --from auto-detected)
synapse send claude "Hello" --priority 1

# Long message support (automatic temp-file fallback)
synapse send claude --message-file /path/to/message.txt --silent
synapse send claude --task-file /path/to/tasks/auth.md --notify   # alias for --message-file (task-specification intent)
synapse send claude -T /path/to/tasks/auth.md --notify            # -T short form
echo "very long content..." | synapse send claude --stdin --silent

# File attachments
synapse send claude "Review this" --attach src/main.py --wait

# Send to specific instance (multiple of same type)
synapse send claude-8100 "Hello"

# Emergency stop
synapse send claude "Stop!" --priority 5

# Bypass working directory mismatch check (only needed for different projects)
synapse send claude "Review this" --force

# Explicit --from (only needed in sandboxed environments like Codex)
synapse send claude "Hello" --from $SYNAPSE_AGENT_ID

Default behavior: With a2a.flow=auto (default), synapse send uses --notify mode — the command returns immediately and you receive a PTY notification when the receiver completes. Use --wait for synchronous blocking, or --silent for fire-and-forget (no completion notification).

Sender auto-detection: --from is optional. Synapse auto-detects the sender using SYNAPSE_AGENT_ID (set at startup), then falls back to PID matching (process ancestry). Use explicit --from only in sandboxed environments (like Codex) where env vars may not propagate. If the sender cannot be identified, Synapse prints Warning: Could not identify sender agent. Set SYNAPSE_AGENT_ID or use --from. and the outbound message has an empty sender field — set SYNAPSE_AGENT_ID or pass --from to fix it.

Troubleshooting delivery failures: If synapse send prints Error sending message: local send failed, re-run with SYNAPSE_LOG_LEVEL=DEBUG to see UDS/TCP failure details, HTTP status codes, and endpoint information. Common causes include an HTTP 409 Agent busy (working task) when the target is mid-task (use synapse status <target> to check, or -p 5 to interrupt), or the target agent being unreachable on its local socket.

synapse reply Command

Reply to the last received message:

synapse reply "<message>"
synapse reply --fail "reason for failure"   # Send a failed reply

The --from flag is only needed in sandboxed environments (like Codex). Without --from, Synapse auto-detects the sender. Use --fail to indicate the task could not be completed; this sends a failed status with an error instead of a normal text reply.

Low-Level A2A Tool

For advanced operations:

# List agents
python -m synapse.tools.a2a list

# Send message
python -m synapse.tools.a2a send --target claude --priority 1 "Hello"

# Reply to last received message (uses reply tracking)
python -m synapse.tools.a2a reply "Here is my response"

API Endpoints

A2A Compliant

Readiness Gate: /tasks/send and /tasks/send-priority return HTTP 503 (with Retry-After: 5) until the agent finishes initialization (identity instruction sending). Priority 5 (emergency interrupt) and reply messages bypass this gate. See CLAUDE.md for details.

Agent Teams

Synapse Extensions

Webhooks

External Agents

Task Structure

In the A2A protocol, all communication is managed as Tasks.

Task Lifecycle

stateDiagram-v2
    [*] --> submitted: POST /tasks/send
    submitted --> working: Processing starts
    working --> completed: Success
    working --> failed: Error
    working --> input_required: Waiting for input
    input_required --> working: Input received
    completed --> [*]
    failed --> [*]

Task Object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "context_id": "conversation-123",
  "status": "working",
  "message": {
    "role": "user",
    "parts": [{ "type": "text", "text": "Review this design" }]
  },
  "artifacts": [],
  "metadata": {
    "sender": {
      "sender_id": "synapse-claude-8100",
      "sender_type": "claude",
      "sender_endpoint": "http://localhost:8100"
    }
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:05Z"
}

Field Descriptions

Message Structure

{
  "role": "user",
  "parts": [
    { "type": "text", "text": "Message content" },
    {
      "type": "file",
      "file": {
        "name": "doc.pdf",
        "mimeType": "application/pdf",
        "bytes": "..."
      }
    }
  ]
}

Sender Identification

The sender of A2A messages can be identified via metadata.sender.

PTY Output Format

Messages are sent to the agent's PTY with a prefix that includes optional sender identification and reply expectations:

A2A: [From: NAME (SENDER_ID)] [REPLY EXPECTED] <message content>

• From: Identifies the sender's display name and unique Runtime ID.
• REPLY EXPECTED: Indicates that the sender is waiting for a response (blocking).

If sender information is not available, it falls back to:

• A2A: [From: SENDER_ID] <message content>
• A2A: <message content> (backward compatible format)

Reply Handling

Synapse automatically manages reply routing. Agents simply use synapse reply:

synapse reply "Here is my response"

The framework internally tracks sender information and routes replies automatically.

Task API Verification (Development)

curl -s http://localhost:8120/tasks/<id> | jq '.metadata.sender'

Response:

{
  "sender_id": "synapse-claude-8100",
  "sender_type": "claude",
  "sender_endpoint": "http://localhost:8100"
}

How It Works

1. On send: Reference Registry, identify own agent_id via PID matching (process ancestry)
2. On Task creation: Attach sender info to metadata.sender
3. On receive: Check via PTY prefix or Task API

Priority Levels

# Emergency stop
synapse send claude "Stop!" --priority 5

Agent Card

Each agent publishes an Agent Card at /.well-known/agent.json.

curl http://localhost:8100/.well-known/agent.json

{
  "name": "Synapse Claude",
  "description": "PTY-wrapped claude CLI agent with A2A communication",
  "url": "http://localhost:8100",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "multiTurn": true
  },
  "skills": [
    {
      "id": "chat",
      "name": "Chat",
      "description": "Send messages to the CLI agent"
    },
    {
      "id": "interrupt",
      "name": "Interrupt",
      "description": "Interrupt current processing"
    }
  ],
  "extensions": {
    "synapse": {
      "agent_id": "synapse-claude-8100",
      "pty_wrapped": true,
      "priority_interrupt": true,
      "at_agent_syntax": true,
      "summary": "Working on auth refactor"
    },
    "x-synapse-context": {
      "identity": "synapse-claude-8100",
      "routing_rules": {
        "self_patterns": ["@synapse-claude-8100", "@claude"],
        "forward_command": "synapse send <agent_id> \"<message>\" --from <your_agent_id>"
      },
      "available_agents": [
        { "id": "synapse-gemini-8110", "type": "gemini", "endpoint": "http://localhost:8110", "status": "READY" }
      ]
    }
  }
}

Context Injection (x-synapse-context)

To keep the PTY clean, Synapse uses the x-synapse-context extension to pass system context to agents. The PTY receives a minimal bootstrap message:

[SYNAPSE A2A] Your ID: synapse-claude-8100
Retrieve your system context:
curl -s http://localhost:8100/.well-known/agent.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(json.dumps(d.get('extensions', {}).get('x-synapse-context', {}), indent=2))"

AI agents execute this command to discover themselves and their peers.

Design Philosophy

Agent Card is a "business card" containing only external-facing information:

• capabilities, skills, endpoint, etc.
• Synapse Extension (x-synapse-context): Includes system context (ID, routing rules, other agents) and bootstrap instructions, keeping the PTY clean.
• Internal instructions are not included in the standard A2A fields (sent via x-synapse-context or initial Task).

Registry and Port Management

Registry Files

~/.a2a/registry/
├── synapse-claude-8100.json
├── synapse-claude-8101.json
└── synapse-gemini-8110.json

~/.a2a/reply/
└── synapse-claude-8100.reply.json   # Reply target persistence (auto-cleaned)

Auto Cleanup

Stale entries are automatically removed during:

• synapse list execution
• Message sending (when target is dead)

Port Ranges

PORT_RANGES = {
    "claude": (8100, 8109),
    "gemini": (8110, 8119),
    "codex": (8120, 8129),
    "opencode": (8130, 8139),
    "copilot": (8140, 8149),
    "dummy": (8190, 8199),
}

Typical Memory Usage (Resident Agents)

On macOS, idle resident agents are lightweight. As of January 25, 2026,
RSS is around ~12 MB per agent process in a typical development setup.

Actual usage varies by profile, plugins, history settings, and workload.
Note that ps reports RSS in KB (so ~12 MB corresponds to ~12,000 KB).
To measure on your machine:

ps -o pid,comm,rss,vsz,etime,command -A | rg "synapse"

If you don't have ripgrep:

ps -o pid,comm,rss,vsz,etime,command -A | grep "synapse"

File Safety

Prevents conflicts when multiple agents edit the same files simultaneously.

sequenceDiagram
    participant Claude
    participant FS as File Safety
    participant Gemini

    Claude->>FS: acquire_lock("auth.py")
    FS-->>Claude: ACQUIRED

    Gemini->>FS: validate_write("auth.py")
    FS-->>Gemini: DENIED (locked by claude)

    Claude->>FS: release_lock("auth.py")
    Gemini->>FS: acquire_lock("auth.py")
    FS-->>Gemini: ACQUIRED

Features

Enable

# Enable via environment variable
export SYNAPSE_FILE_SAFETY_ENABLED=true
synapse claude

Basic Commands

# Show statistics
synapse file-safety status

# List active locks
synapse file-safety locks

# Acquire lock
synapse file-safety lock /path/to/file.py claude --intent "Refactoring"

# Wait for lock to be released
synapse file-safety lock /path/to/file.py claude --wait --wait-timeout 60 --wait-interval 2

# Release lock
synapse file-safety unlock /path/to/file.py claude

# File change history
synapse file-safety history /path/to/file.py

# Recent changes
synapse file-safety recent

# Delete old data
synapse file-safety cleanup --days 30

Python API

from synapse.file_safety import FileSafetyManager, ChangeType, LockStatus

manager = FileSafetyManager.from_env()

# Acquire lock
result = manager.acquire_lock("/path/to/file.py", "claude", intent="Refactoring")
if result["status"] == LockStatus.ACQUIRED:
    # Edit file...

    # Record change
    manager.record_modification(
        file_path="/path/to/file.py",
        agent_name="claude",
        task_id="task-123",
        change_type=ChangeType.MODIFY,
        intent="Fix authentication bug"
    )

    # Release lock
    manager.release_lock("/path/to/file.py", "claude")

# Pre-write validation
validation = manager.validate_write("/path/to/file.py", "gemini")
if not validation["allowed"]:
    print(f"Write blocked: {validation['reason']}")

Storage: Default is .synapse/file_safety.db (SQLite, relative to working directory). Change via SYNAPSE_FILE_SAFETY_DB_PATH (e.g., ~/.synapse/file_safety.db for global).

See docs/file-safety.md for details.

Agent Monitor

Real-time monitoring of agent status with terminal jump capability.

Rich TUI Mode

# Start Rich TUI in the alternate screen with auto-refresh (default)
synapse list

# JSON output for AI/programmatic consumption
synapse list --json

The display automatically updates when agent status changes (via file watcher) with a 10-second fallback polling interval.

JSON Output

synapse list --json outputs a JSON array of agent objects for AI and scripting use. Each object includes: agent_id, agent_type, name, role, skill_set, port, status, pid, working_dir, endpoint, transport, current_task_preview, task_received_at, summary, and optionally editing_file.

If automation is attached to a TTY, use synapse list --json, synapse list --plain, or set SYNAPSE_NONINTERACTIVE=1. Bare synapse list is intended for human-operated interactive terminals.

For Copilot specifically, bracketed paste is enabled because Copilot CLI 1.0.12+ enables bracketed paste mode (ESC[?2004h). Synapse wraps input in paste markers so Ink routes it through usePaste as a single atomic event, which also eliminates the need for slash-command escaping. Input is delivered through an inject pipe mechanism that merges keyboard input and programmatic writes into the PTY's _copy loop, solving the issue where direct writes from other threads were lost. An input_ready_pattern (❯) detects when the TUI is ready before sending instructions. Long messages use a single-line file reference format. Bounded submit confirmation verifies that Copilot cleared the prompt after submission. Copilot CLI also enables Kitty Keyboard Protocol (KKP) on startup, which re-encodes Enter from \r to CSI 13 u, causing injected \r submits to be silently ignored. Synapse detects KKP activation in PTY output and immediately pops the mode, and also proactively disables KKP before the first submit as a safety net.

Display Columns

Customize columns in settings.json:

{
  "list": {
    "columns": ["ID", "NAME", "STATUS", "CURRENT", "TRANSPORT", "WORKING_DIR"]
  }
}

Status States

Interactive Controls

Supported Terminals: iTerm2, Terminal.app, Ghostty, VS Code, tmux, Zellij

WAITING Detection

WAITING detection is enabled in all five profiles (claude, codex, gemini, opencode, copilot). The #140 false positive issue was resolved by matching only against fresh PTY output (new_data) and adding auto-expiry (waiting_expiry, default 10s) with buffer tail re-check. As of #572, the waiting_detection regex is evaluated against a pyte-backed virtual terminal (synapse/pty_renderer.py) that replays cursor-motion CSI sequences in place, so TUI-based agents (ratatui, Ink, Bubble Tea) that overwrite the same cells are matched against the text a human actually sees rather than an ANSI-stripped byte stream. Alt-screen buffer (\x1b[?1049h/l) enter/leave is tracked, and a new GET /debug/pty endpoint on each per-agent A2A server returns the rendered screen as JSON ({display, cursor, alt_screen, columns, rows}) for debugging regex matches.

Detects agents waiting for user input (selection UI, Y/n prompts) using agent-specific regex patterns:

• Claude: ❯ Option cursor, ☐/☑ checkboxes, [Y/n] prompts
• Gemini: ● 1. Option selection UI, Action Required header, Allow once/for this session/for this file, No, suggest changes, Apply this change, Do you want to proceed
• Codex: › selector with numbered items, Yes, proceed, Yes, and don't ask again, No, and tell Codex, Press enter to confirm, Press [Ee]nter to confirm, Would you like to
• OpenCode: Permission Required header, horizontal button bar (Allow (a), Allow for session (s), Deny (d))
• Copilot: Numbered choices, selection indicators, [y/N] or (y/n) prompts, approve ... for the rest of the running session, No, and tell Copilot. A repeated WAITING state only confirms after the prompt text clears.

Compound Signal Status Detection

The PROCESSING to READY transition uses compound signals to prevent premature detection during A2A task processing:

• task_active flag: Suppresses READY when an A2A task is being processed (timeout: task_protection_timeout, default 30s)
• File locks: Suppresses READY when the agent holds file locks via FileSafetyManager

Use synapse status <agent> to inspect the detailed state of a specific agent, including current task elapsed time and file locks.

CI Automation (Claude Code)

Synapse A2A includes hooks and skills for automated CI monitoring and repair when used with Claude Code.

How It Works

1. PostToolUse hook (check-ci-trigger.sh) detects git push or gh pr create commands
2. Two background monitors launch automatically:
   • poll-ci.sh — polls GitHub Actions workflow status
   • poll-pr-status.sh — polls merge conflict state and CodeRabbit review comments
3. When issues are detected, the agent receives a systemMessage notification suggesting the appropriate fix skill

Available Skills

Conflict Detection Flow

git push / gh pr create
  └─→ check-ci-trigger.sh (PostToolUse hook)
        ├─→ poll-ci.sh (background) → monitors GitHub Actions
        └─→ poll-pr-status.sh (background)
              ├─→ checks mergeable state → if CONFLICTING → notifies agent → /fix-conflict
              └─→ checks CodeRabbit reviews → if comments found → classifies → notifies agent → /fix-review

Setup

These hooks and skills are pre-configured in .claude/settings.json. The following permissions are required:

• Skill(check-ci), Skill(fix-ci), Skill(fix-conflict), Skill(fix-review)
• Bash(gh api:*), Bash(gh repo view:*), Bash(gh pr checks:*)

Testing

Comprehensive test suite verifies A2A protocol compliance:

# All tests
pytest

# Specific category
pytest tests/test_a2a_compat.py -v
pytest tests/test_sender_identification.py -v

# Opt-in live E2E against real agent CLIs
SYNAPSE_LIVE_E2E=1 pytest tests/test_live_e2e_agents.py -q

# Limit live E2E to specific agents
SYNAPSE_LIVE_E2E=1 SYNAPSE_LIVE_E2E_PROFILES=copilot,codex \
  pytest tests/test_live_e2e_agents.py -q

Live E2E tests are skipped by default. They launch the real claude, codex,
gemini, opencode, and copilot CLIs in headless Synapse sessions and verify
that a message sent through /tasks/send completes and returns the requested
token. Use them for local validation or a dedicated CI job with authenticated
agent CLIs.

Configuration (.synapse)

Customize environment variables and initial instructions via .synapse/settings.json.

Scopes

Higher priority settings override lower ones.

Setup

# Create .synapse/ directory (copies all template files)
synapse init

# ? Where do you want to create .synapse/?
#   ❯ User scope (~/.synapse/)
#     Project scope (./.synapse/)
#
# ✔ Created ~/.synapse

# Reset to defaults
synapse reset

# Edit settings interactively (TUI)
synapse config

# Show current settings (read-only)
synapse config show
synapse config show --scope user

synapse init copies these files to .synapse/:

settings.json Structure

{
  "env": {
    "SYNAPSE_HISTORY_ENABLED": "true",
    "SYNAPSE_FILE_SAFETY_ENABLED": "true",
    "SYNAPSE_FILE_SAFETY_DB_PATH": ".synapse/file_safety.db"
  },
  "instructions": {
    "default": "[SYNAPSE INSTRUCTIONS...]\n...",
    "claude": "",
    "gemini": "",
    "codex": ""
  },
  "approvalMode": "required",
  "a2a": {
    "flow": "auto"
  }
}

Environment Variables (env)

A2A Communication Settings (a2a)

Approval Mode (approvalMode)

Controls whether to show a confirmation prompt before sending initial instructions.

When set to required, you'll see a prompt like:

[Synapse] Agent: synapse-claude-8100 | Port: 8100
[Synapse] Initial instructions will be sent to configure A2A communication.

Proceed? [Y/n/s(skip)]:

Options:

• Y (or Enter): Send initial instructions and start agent
• n: Abort startup
• s: Start agent without sending initial instructions

Initial Instructions (instructions)

Customize instructions sent at agent startup:

{
  "instructions": {
    "default": "Common instructions for all agents",
    "claude": "Claude-specific instructions (takes priority over default)",
    "gemini": "Gemini-specific instructions",
    "codex": "Codex-specific instructions"
  }
}

Priority:

1. Agent-specific setting (claude, gemini, codex, opencode, copilot) if present
2. Otherwise use default
3. If both empty, no initial instructions sent

Placeholders:

• {{agent_id}} - Runtime ID (e.g., synapse-claude-8100)
• {{port}} - Port number (e.g., 8100)

See guides/settings.md for details.

Development & Release

Publishing to PyPI

Merging a pyproject.toml version change to main automatically creates a git tag, GitHub Release, and publishes to PyPI.

# 1. Generate changelog with git-cliff
python scripts/generate_changelog.py

# 2. Update version in pyproject.toml and review CHANGELOG.md
# 3. Create PR and merge to main
# 4. Automation handles: tag → GitHub Release → PyPI → Homebrew/Scoop PR

Manual Publishing (Fallback)

# Build and publish with uv
uv build
uv publish

User Installation

macOS / Linux / WSL2 (recommended):

pipx install synapse-a2a

# Upgrade
pipx upgrade synapse-a2a

# Uninstall
pipx uninstall synapse-a2a

Windows (Scoop, experimental — WSL2 required for pty):

scoop bucket add synapse-a2a https://github.com/s-hiraoku/scoop-synapse-a2a
scoop install synapse-a2a

# Upgrade
scoop update synapse-a2a

Known Limitations

• TUI Rendering: Display may be garbled with Ink-based CLIs (response artifacts from Bubble Tea and Ink TUIs are automatically stripped)
• PTY Limitations: Some special input sequences not supported
• Ghostty Focus: Ghostty uses AppleScript to target the currently focused window or tab. If you switch tabs while a spawn or team start command is executing, the agent may be spawned in the unintended tab. Please wait for the command to complete before interacting with the terminal.
• Codex Sandbox: Codex CLI's sandbox blocks network access, requiring configuration for inter-agent communication (see below)

Inter-Agent Communication in Codex CLI

Codex CLI runs in a sandbox by default with restricted network access. To use @agent pattern for inter-agent communication, allow network access in ~/.codex/config.toml.

Global Setting (applies to all projects):

# ~/.codex/config.toml

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

Per-Project Setting:

# ~/.codex/config.toml

[projects."/path/to/your/project"]
sandbox_mode = "workspace-write"

[projects."/path/to/your/project".sandbox_workspace_write]
network_access = true

See guides/troubleshooting.md for details.

Enterprise Features

Security, notification, and high-performance communication features for production environments.

API Key Authentication

# Start with authentication enabled
export SYNAPSE_AUTH_ENABLED=true
export SYNAPSE_API_KEYS=<YOUR_API_KEY>
synapse claude

# Request with API Key
curl -H "X-API-Key: <YOUR_API_KEY>" http://localhost:8100/tasks

Webhook Notifications

Send notifications to external URLs when tasks complete.

# Register webhook
curl -X POST http://localhost:8100/webhooks \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/hook", "events": ["task.completed"]}'

SSE Streaming

Receive task output in real-time.

curl -N http://localhost:8100/tasks/{task_id}/subscribe

Event types:

Output Parsing

Automatically parse CLI output for error detection, status updates, and Artifact generation.

gRPC Support

Use gRPC for high-performance communication.

# Install gRPC dependencies
pip install synapse-a2a[grpc]

# gRPC runs on REST port + 1
# REST: 8100 → gRPC: 8101

See guides/enterprise.md for details.

Documentation

License

MIT License

Related Links

• Claude Code - Anthropic's CLI agent
• OpenCode - Open-source AI coding agent
• GitHub Copilot CLI - GitHub's AI coding assistant
• Google A2A Protocol - Agent-to-Agent protocol