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

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, and delays briefly (default 2s, override via SYNAPSE_SEND_READY_DELAY) for READY targets so the user has time to commit input — if the target flips to PROCESSING during the window, the send fires immediately (#467 / #642). Both waits are 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
Permission Detection	WAITING status maps to A2A input_required with x-permission-prompt metadata. Child agents send structured escalation metadata to their parent, which can auto-approve/deny via the Approval Gate or fall back to manual POST /tasks/{id}/permission/approve and /deny. In synapse send --wait, the sender now keeps polling until the parent intervenes or the timeout expires. Each profile defines a deny_response for rejection. See Permission Modes
Plan Approval	Plan-mode workflow with synapse approve/reject for human-in-the-loop review
Graceful Shutdown	synapse kill sends shutdown request before SIGTERM (30s timeout, -f for force). Worktree branches are auto-merged back to the base branch on kill (uncommitted changes are WIP-committed first; conflicts preserve the branch with a warning). Use --no-merge to skip auto-merge
Delegate Mode	--delegate-mode makes an agent a manager that delegates instead of editing files
Auto-Spawn Panes	synapse team start — 1st agent takes over current terminal, others in new panes. Defaults to --worktree isolation (opt out with --no-worktree). --all-new to start all in new panes. Supports profile:name:role:skill_set:port spec (tmux/iTerm2/Terminal.app/Ghostty/zellij)
Soft Interrupt	synapse interrupt <target> "message" — Ergonomic shorthand for synapse send -p 4 --silent to quickly interrupt an agent
Token/Cost Tracking	Skeleton for per-agent token usage tracking; synapse history stats shows TOKEN USAGE section when data exists
Saved Agent Definitions	synapse agents add/list/show/delete plus agents set/unset/roles — Save reusable agent templates or profile defaults (profile + name + role + skill set). synapse spawn accepts Agent IDs/names, synapse <profile> can load .synapse/agents.json defaults, and running agents expose the saved petname as agent_definition_id so commands can target the stable ID instead of the port-based runtime ID
Spawn Single Agent	synapse spawn <profile|saved-agent> — Spawn a single agent in a new terminal pane or window. Accepts profile names or saved agent IDs/names. Auto-tiles (tmux): when a second or subsequent agent is spawned, tmux select-layout tiled is automatically applied for even pane distribution (no flags needed). Use --worktree / -w for Synapse-native git worktree isolation (all agents, .synapse/worktrees/). --branch / -b auto-enables --worktree and sets the base branch (defaults to origin/main). Use --no-worktree to opt out. --task "message" / --task-file path auto-sends a task after the agent becomes READY (with --task-timeout, --wait/--notify/--silent). Recommended pattern: synapse spawn <profile> --task-file <path> --task-timeout 600 --notify. Legacy -- --worktree also supported for Claude Code only
CI Automation	PostToolUse hooks detect git push/gh pr create and auto-poll CI status, merge conflicts, and CodeRabbit reviews. Skills: /check-ci, /fix-ci, /fix-conflict, /fix-review
Issue Bootstrap	/dev-issue <number> slash command bootstraps issue implementation in one step — fetches the issue from GitHub, generates a task brief, creates a feature branch (feat/<slug>-<number>), and spawns a Codex agent on it (#643)
Learning Mode	Two independent flags: SYNAPSE_LEARNING_MODE_ENABLED=true enables Prompt Improvement section; SYNAPSE_LEARNING_MODE_TRANSLATION=true enables JP-to-EN Learning section. Either flag activates learning.md injection and Tips. Response uses normal formatting (no separators); structured formatting (━━━ separators, section headers) applies only to feedback sections (Prompt Improvement, JP-to-EN Learning, Tips)
Proactive Mode	SYNAPSE_PROACTIVE_MODE_ENABLED=true guides agents to use Synapse features (shared memory, canvas, file safety, delegation, broadcast) based on a task-size x feature matrix. Small tasks skip most features; medium tasks use them selectively; large tasks require full coordination. Per-feature skip conditions prevent unnecessary overhead. Follows the learning_mode pattern: env var activation + .synapse/proactive.md instruction file appended at startup. Off by default
Shared Memory	Deprecated — superseded by LLM Wiki (see below). User-global SQLite knowledge base (~/.synapse/memory.db) for cross-agent knowledge sharing. Agents save, search, and retrieve learned knowledge across sessions (synapse memory save/list/search/show/delete/stats). API endpoints at /memory/*. Enabled by default (SYNAPSE_SHARED_MEMORY_ENABLED=true). New knowledge should use synapse wiki instead. See Shared Memory vs LLM Wiki
LLM Wiki	Knowledge accumulation layer inspired by Karpathy's LLM Wiki pattern. Agents build and maintain a structured, interlinked Markdown knowledge base with frontmatter metadata, [[wikilink]] cross-references, and confidence scores. Two scopes: .synapse/wiki/ (project) and ~/.synapse/wiki/ (global). CLI: synapse wiki ingest/query/lint/status/refresh/init. Living Docs: pages track source_files and source_commit in frontmatter; lint/status detect stale pages when tracked files change; refresh --apply updates commit SHAs. Page types: entity, concept, decision, comparison, synthesis, learning. Canvas Knowledge view at #/knowledge; GET /api/wiki/graph returns a Mermaid diagram of page links. MCP instruction synapse://instructions/wiki. Config: wiki.enabled (default true). See LLM Wiki Design
Session Save/Restore	Save running team configurations as named snapshots and restore them later (synapse session save/list/show/restore/delete/sessions). session publish/import syncs snapshots through SYNAPSE_SHARED_SESSION_DIR for team handoff. Each agent's CLI conversation session_id is automatically captured and stored in the registry at startup. Restoring with --resume uses the saved session_id to resume each agent's conversation history, with an automatic 10-second timeout fallback if resume fails (see the Resume Mode section in the guide for details)
Workflow	Define reusable YAML-based message sequences and execute them with synapse workflow run. Each workflow is a named list of steps (target, message, priority, response_mode). Supports --dry-run to preview, --continue-on-error for resilient execution, --auto-spawn for automatic agent spawning, and --async for background execution (returns run_id; check progress with synapse workflow status <run_id>). target: self: steps can target the calling agent itself; a helper agent is auto-spawned to avoid deadlock (nested workflow execution from helpers is forbidden, max depth 1). Bare-type targets respect caller CWD: target: claude resolves only to agents in the workflow runner's working directory, so it never dispatches to a same-type agent in a different project; combine with auto_spawn to start a fresh one when none exists (#568 / #645). Persistent execution history: completed runs are stored in SQLite (.synapse/workflow_runs.db) and survive server restarts; active runs are cached in memory with DB fallback. Workflow-level trigger and auto_spawn fields enable skill auto-generation: creating or syncing a workflow produces a SKILL.md (marked <!-- synapse-workflow-autogen -->) in .claude/skills/ and .agents/skills/, making workflows discoverable as slash-command skills. Use synapse workflow sync to regenerate all skills and remove orphans. Stored in .synapse/workflows/ (project) or ~/.synapse/workflows/ (user). See Workflow Self-Target
Canvas	Shared visual output surface for agents. Renders diagrams (Mermaid with theme-synced palettes), tables, charts, code, diffs, and 25 content formats in a browser UI. Enhanced markdown rendering with tables, blockquotes, ordered lists, and inline formatting via a built-in state-machine parser. Includes progress, terminal, dependency-graph, and cost card types. Supports 6 layout templates: briefing, comparison, dashboard, steps, slides, plan for structured multi-block cards. Plan Card template visualizes task plans with Mermaid DAG + step list, status tracking (proposed/active/completed/cancelled). Task card expand/collapse state persists across dashboard polling updates. HTML Artifact Support: format: "html" sandboxed iframes with parent-iframe theme sync (CSS variables --bg, --fg, --border via postMessage), auto-resize (ResizeObserver), dark mode CSS, and full document normalization (extracts head/body from <!doctype html> documents). CLI shortcuts: synapse canvas mermaid/markdown/table/chart/briefing/plan/.... Server: synapse canvas serve (port 3000). Agent Control: interactive Agent Control tab (formerly "Admin") for sending messages to agents, viewing responses, and managing the fleet from the browser. Agent selection via clickable table rows (double-click to jump to agent's terminal, right-click context menu with Kill Agent action and confirm modal), multi-line textarea with Cmd+Enter, IME support, multi-artifact response extraction, terminal junk stripping. Card Download: export any card via GET /api/cards/{card_id}/download?format={format} — all 25 content formats map to optimal download formats (Markdown, JSON, CSV, HTML, native); 6 templates export as Markdown/JSON. Download buttons in card grid headers and Spotlight title bar. Clipboard Copy: copy any card as Markdown to the clipboard via the copy button (reuses the download endpoint with ?format=md); available in both card grid headers and Spotlight view. Spotlight navigation: keyboard shortcuts (ArrowLeft/Right to navigate cards, Escape to exit manual navigation and return to live/latest mode), spotlight-swap animations, template badge in title bar, minimal info bar mode, and mobile-responsive layout. DB Browser: sidebar tree + paginated table view for inspecting Synapse SQLite databases (/api/db/list, /api/db/{db}/{table} endpoints; task_board.db is excluded). Dashboard: responsive auto-fit grid layout. Accessibility: agent panel uses role=button, tabindex, aria-expanded, and focus-visible styling. Sidebar menu: Canvas, History, Dashboard, Agent Control, Workflow, Database, Harnesses (landing) / Skills (tree-table of discovered skills at #/harnesses/skills; two-level hierarchy: User Global (subdivided by agent harness: Claude Code .claude/skills/** vs shared .agents/skills/**) → Projects (per-directory, further split by agent bucket when applicable) → Synapse Central Store; columns NAME / DESCRIPTION / LOCATION; collapsible with incremental name filter) / MCP Servers (tree-table of configured MCP servers at #/harnesses/mcp; two-level hierarchy: User Global (subdivided per agent: Claude Code ~/.claude.json, Codex ~/.codex/config.toml TOML, Gemini ~/.gemini/settings.json, OpenCode ~/.config/opencode/opencode.json, Claude Desktop) → Projects (per .mcp.json; projects without one render as a dashed-folder "no .mcp.json" row so scanned-but-unconfigured is distinguished from not-seen); columns NAME / COMMAND / DETAILS where DETAILS shows transport type and env:KEY chips — env values are never sent to the browser), System. See Canvas Design, Admin Command Center
Smart Suggest	analyze_task MCP tool analyzes user prompts and returns a delegation_strategy (self, subagent, or spawn) along with rich context (diff_stats, file_conflicts, dependencies, parallelizable) and a recommended_worktree field (true when spawn strategy or high file conflicts detected). Accepts optional files and agent_type params. When collaboration would be beneficial, suggests team/task splits displayed as Plan Cards on Canvas. Trigger conditions (file count, multi-directory changes, missing tests, prompt complexity, keywords) are configurable via .synapse/suggest.yaml. See Smart Suggest Design (Japanese)
Proactive Collaboration	Agents automatically evaluate collaboration opportunities before starting tasks. Built-in decision framework: do-it-yourself, delegate, ask-for-help, report-progress, share-knowledge. Cross-model spawning preference distributes token usage and avoids rate limits. Worker agents can also spawn/delegate (not just managers). Mandatory cleanup of spawned agents (synapse kill <name> -f)
Self-Learning Pipeline	Observation layer captures PTY and A2A signals into .synapse/observations.db. synapse learn analyzes repeated patterns and persists instincts (.synapse/instincts.db). synapse instinct lists/promotes learned instincts. synapse evolve clusters instincts into reusable skill candidates. Pipeline: Observation → Pattern Analyzer → Instinct → Evolve. Env: SYNAPSE_OBSERVATION_ENABLED (default true), SYNAPSE_OBSERVATION_DB_PATH, SYNAPSE_INSTINCT_DB_PATH
MCP Bootstrap	synapse mcp serve exposes bootstrap resources (instructions, settings, agent card) and tools (bootstrap_agent, list_agents, analyze_task) via the Model Context Protocol over stdio. Lets MCP-capable agents pull Synapse context with a minimal PTY startup bootstrap instead of the full initial instruction payload. When a Synapse MCP server config entry is detected, Synapse sends a short MCP bootstrap message at startup and keeps approval prompts enabled unless the session is resumed; non-Synapse MCP entries do not trigger this path. Copilot MCP config: ~/.copilot/mcp-config.json. See MCP Bootstrap Design (Japanese)
Multi-Agent Patterns	Declarative coordination patterns that define how agents should behave rather than what to do (contrast with imperative Workflows). Five built-in pattern types: generator-verifier (generate + verify against criteria), orchestrator-subagent (decompose and delegate), agent-teams (parallel workers on a task queue), message-bus (pub/sub event-driven coordination), shared-state (agents collaborate via shared wiki). CLI: synapse multiagent init/list/show/run/status/stop (alias synapse map). Pattern configs stored in .synapse/patterns/ (project) or ~/.synapse/patterns/ (user). Canvas integration: Pattern tab with list/detail views at /api/multiagent endpoints. --dry-run to preview, --async for background execution

---

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

<details>
<summary><b>macOS / Linux / WSL2 (recommended)</b></summary>

# pipx (recommended)
pipx install synapse-a2a

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

</details>

<details>
<summary><b>Windows</b></summary>

WSL2 is strongly recommended. Synapse A2A uses pty.spawn() which requires a Unix-like terminal.

# 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

</details>

<details>
<summary><b>Developer (from source)</b></summary>

# Install with uv
uv sync

# Or pip (editable)
pip install -e .

</details>

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:

Agent	Port Range
Claude	8100-8109
Gemini	8110-8119
Codex	8120-8129
OpenCode	8130-8139
Copilot	8140-8149

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

Operation	SSH	Synapse
Manual CLI operation	◎	◎
Programmatic task submission	△ requires expect etc.	◎ HTTP API
Multiple simultaneous clients	△ multiple sessions	◎ single endpoint
Real-time progress notifications	✗	◎ SSE/Webhook
Automatic inter-agent coordination	✗	◎ synapse send

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

Skill	Description
synapse-a2a	Comprehensive guide for inter-agent communication: synapse send, priority, A2A protocol, history, File Safety, settings
synapse-manager	Multi-agent management workflow: task delegation, progress monitoring, quality verification with regression testing, feedback delivery, cross-review orchestration, worker agent guide, and mandatory cleanup enforcement
check-ci	Check CI status, merge conflict state, and CodeRabbit review status for the current PR (/check-ci, /check-ci --fix)
fix-ci	Auto-diagnose and fix CI failures: lint, format, type-check, test errors
fix-conflict	Auto-resolve merge conflicts: fetch base, test merge, analyze both sides, resolve, verify, push
fix-review	Auto-fix CodeRabbit review comments: classify by severity (Bug/Style/Suggestion), apply fixes, verify, push
dev-issue	/dev-issue <number> — Bootstrap issue implementation in one step: fetch the issue, generate a task brief, create a feature branch, and spawn a Codex agent on it

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

Scope	Location	Description
Synapse	~/.synapse/skills/	Central store (deploy to agents from here)
User	~/.claude/skills/, ~/.agents/skills/, etc.	User-wide skills
Project	./.claude/skills/, ./.agents/skills/, etc.	Project-local skills
Plugin	./plugins/*/skills/	Read-only plugin skills

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 [name]                 # Create a skill template
synapse skills create [name] --launch-agent  # Spawn an agent to finish it with anthropic-skill-creator

# 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):

Skill Set	Description	Skills
architect	System architecture and design — design docs, API contracts, code review	synapse-a2a, system-design, api-design, code-review, project-docs
developer	Implementation and quality — test-first development, refactoring, code simplification	synapse-a2a, test-first, refactoring, code-simplifier, agent-memory
reviewer	Code review and security — structured reviews, security audits, code simplification	synapse-a2a, code-review, security-audit, code-simplifier
frontend	Frontend development — React/Next.js performance, component composition, design systems, accessibility	synapse-a2a, react-performance, frontend-design, react-composition, web-accessibility
manager	Multi-agent management — task delegation, progress monitoring, quality verification, cross-review orchestration, re-instruction	synapse-a2a, synapse-manager, task-planner, agent-memory, code-review, synapse-reinst
documentation	Documentation expert — audit, restructure, synchronize, and maintain project documentation	synapse-a2a, project-docs, api-design, agent-memory

Directory Structure

plugins/
└── synapse-a2a/
    ├── .claude-plugin/plugin.json
    ├── .codex-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.

Codex can discover the repo-local plugin through .agents/plugins/marketplace.json. Gemini can use the expanded skills in the .agents/skills/ directory.

---

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

Component	File	Role
FastAPI Server	synapse/server.py	Provides A2A endpoints
A2A Router	synapse/a2a_compat.py	A2A protocol endpoints and PTY bridging
A2A Models	synapse/a2a_models.py	Pydantic data models for A2A messages and tasks
TaskStore	synapse/task_store.py	In-memory task persistence and status tracking
A2A Client	synapse/a2a_client.py	Communication with other agents
TerminalController	synapse/controller.py	PTY management, READY/PROCESSING detection
Shell	synapse/shell.py	Interactive shell with @Agent pattern routing
AgentRegistry	synapse/registry.py	Agent registration and lookup
Worktree	synapse/worktree.py	Synapse-native git worktree isolation for all agents
FileSafety	synapse/file_safety.py	Multi-agent file locking and change tracking
SkillManager	synapse/skills.py	Skill discovery, deploy, import, skill sets
Commands	synapse/commands/	CLI command handlers (extracted from cli.py)
SkillManagerCmd	synapse/commands/skill_manager.py	Skill management TUI and CLI
AgentProfileStore	synapse/agent_profiles.py	Saved agent definitions (reusable templates for spawn)
WorkflowRunDB	synapse/workflow_db.py	SQLite persistence for workflow execution history
WorkflowRunner	synapse/workflow_runner.py	Step-by-step workflow executor
Observation	synapse/observation.py	PTY/A2A signal capture for self-learning pipeline
PatternAnalyzer	synapse/pattern_analyzer.py	Observation pattern analysis
Instinct	synapse/instinct.py	Learned instinct persistence
Transport	synapse/transport.py	Transport abstraction layer
Canvas	synapse/canvas/	Shared visual output surface (server, protocol, store, export, routes)
Patterns	synapse/patterns/	Multi-agent coordination patterns (base, store, runner)
MultiagentCmd	synapse/commands/multiagent.py	CLI handlers for synapse multiagent / synapse map
MCP Server	synapse/mcp/	MCP bootstrap resource server (instructions, settings, agent card)

Responsibility Boundaries

Synapse keeps the runtime split into four dependency layers. Lower layers do not import higher layers.

flowchart TB
    Core["Core: A2A protocol, task lifecycle, status"]
    Adapters["Adapters: claude/codex/gemini profiles and HTTP wrappers"]
    Runtime["Runtime: CLI, PTY controller, registry, worktrees"]
    Extensions["Extensions: Canvas, skills, hooks, workflows, self-learning"]

    Extensions --> Runtime
    Runtime --> Adapters
    Adapters --> Core

The practical rule is: protocol/task code stays in a2a_*, task_store.py, status.py, and transport.py; provider-specific behavior lives in profile/adaptor modules; PTY and process orchestration stay in runtime modules; optional capabilities build on top through synapse/commands/, synapse/canvas/, workflow, hooks, and skills.

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

Command	Description
synapse <profile>	Start in foreground
synapse start <profile>	Start in background
synapse stop <profile|id>	Stop agent (can specify ID)
synapse kill <target>	Graceful shutdown (sends shutdown request, then SIGTERM after 30s). Auto-merges worktree branch
synapse kill <target> -f	Force kill (immediate SIGKILL). Auto-merges worktree branch
synapse kill <target> --no-merge	Kill without auto-merging worktree branch
synapse cleanup	Kill orphan agents (children whose spawned_by parent crashed/cleared). --dry-run to preview, -f to skip prompt, optional positional agent id to target one. Set SYNAPSE_ORPHAN_IDLE_TIMEOUT=<sec> to opt into opportunistic cleanup of long-READY orphans on synapse list
synapse merge <agent>	Merge worktree branch without killing the agent. --all for all agents, --dry-run to preview
synapse jump <target>	Jump to agent's terminal
synapse send-keys <target> [data]	Write raw input bytes into a running agent's PTY. Escape hatch for unsticking agents blocked on a TUI dialog (codex edit-confirmation, model picker, rate-limit dialog) without synapse jump. --enter appends \r, --no-escape disables unicode_escape decoding, --json emits the raw HTTP response. CLI wrapper for POST /pty/write (require_auth-gated, same trust model as /tasks/{id}/cancel / /permission/approve). #695, Refs #694
synapse rename <target>	Assign name/role to agent
synapse set-summary <target> [text]	Set persistent agent summary (120 chars). --auto generates from git context, --clear removes
synapse --version	Show version
synapse list	List running agents (Rich TUI in alternate screen with auto-refresh, ↑↓/1-9 selection, Enter/j terminal jump, and k kill confirmation)
synapse list --plain	Force one-shot plain-text output without entering the TUI