供人类使用：synapse list（自动刷新，交互式：箭头/1-9 选择，Enter 跳转，k 终止，/ 过滤）。供 AI/脚本使用：synapse list --json、synapse list --plain 或 MCP list_agents
代理详情
synapse status <target> [--json]
发送消息
synapse send <target> "<msg>"（默认：--notify； 自动检测）
🇺🇸English
Synapse A2A Communication
Inter-agent communication framework via Google A2A Protocol.
Quick Reference
Task
Command
List agents
synapse list for humans (auto-refresh, interactive: arrows/1-9 select, Enter jump, k kill, / filter). For AI/scripts use synapse list --json, synapse list --plain, or MCP list_agents
Build Agent Assignment Plan (Phase / Agent / Rationale)
Spawn specialists if needed (prefer different model types for diversity)
Use Synapse Features Actively
Feature
Why It Matters
Commands
Shared Memory
Collective knowledge survives agent restarts
synapse memory save/search/list
File Safety
Locking prevents data loss when two agents edit the same file
synapse file-safety lock/unlock/locks
Worktree
File isolation eliminates merge conflicts in parallel editing
synapse spawn --worktree
Broadcast
Team-wide announcements reach all agents instantly
synapse broadcast "<msg>"
History
Audit trail tracks what happened and when
synapse history list/show/stats
Plan Approval
Gated execution ensures quality before action
synapse approve/reject
Canvas
Visual dashboard for sharing rich cards and templates (briefing, comparison, dashboard, steps, slides, plan); cards downloadable as Markdown, JSON, CSV, or native format via browser button or GET /api/cards/{card_id}/download
synapse canvas post/link/briefing/plan/open/list
Agent Control
Browser-based agent management via Canvas #/admin view (select agents, send messages, view responses, double-click agent row to jump to terminal)
synapse canvas open → navigate to #/admin
Workflow View
Browser-based workflow management via Canvas #/workflow view (list workflows, inspect steps, trigger runs, monitor progress with live SSE updates; run history persisted to SQLite across restarts)
synapse canvas open → navigate to #/workflow
Plan Cards
Mermaid DAG + step list with dependency visualization
synapse canvas plan
Smart Suggest
MCP tool that analyzes prompts and suggests team/task splits for large work
MCP tool: analyze_task
Proactive Mode
Mandatory feature usage checklist for every task (SYNAPSE_PROACTIVE_MODE_ENABLED=true)
See references/features.md
MCP Bootstrap
Distribute instructions via MCP resources for compatible clients (opt-in, including Copilot via tools-only). MCP tools: bootstrap_agent, list_agents, analyze_task
synapse mcp serve / python -m synapse.mcp
Canvas Template Default Triggers
Use Canvas templates by default when the output should be read by another agent or a human later, not just glanced at once in the terminal.
briefing for structured reports, status updates, and release summaries
comparison for before/after, option trade-offs, and review diffs
steps for plans, migration sequences, and execution checklists
slides for walkthroughs, demos, and page-by-page narratives
dashboard for multi-widget operational snapshots and compact status boards
plan for task DAGs with Mermaid visualization and step tracking
Prefer raw synapse canvas post <format> only when a single block is enough. If the message has multiple sections or needs stronger information hierarchy, use a template.
Spawning Decision Table
Default spawn policy: When using synapse spawn, pass the underlying CLI's tool-specific automation args after -- so spawned agents can run unattended. For most CLIs this is an approval-skip / auto-approve flag; for OpenCode use --agent build to select the build agent profile and rely on OpenCode's permission config for approval behavior.
Apply the same rule to synapse team start: include the appropriate forwarded CLI args by default, and keep teams homogeneous when those args are CLI-specific.
Common defaults:
Claude Code: synapse spawn claude --name <n> --role "<r>" -- --dangerously-skip-permissions
Claude team: synapse team start claude claude -- --dangerously-skip-permissions
Gemini team: synapse team start gemini gemini -- --approval-mode=yolo
Codex team: synapse team start codex codex -- --full-auto
OpenCode team: synapse team start opencode opencode -- --agent build (selects the build agent profile; permission prompts still depend on OpenCode config)
Copilot team: synapse team start copilot copilot -- --allow-all-tools
Condition
Action
Existing READY agent can handle it
synapse send — reuse is faster (avoids startup overhead)
Need parallel execution
synapse spawn with --worktree -- <tool-specific-automation-args> for file isolation
Task needs a different model's strengths
Spawn a different type (Claude spawns Gemini, etc.)
User specified agent count
Follow exactly
Single focused subtask
Spawn 1 agent
N independent subtasks
Spawn N agents
Spawn lifecycle : spawn → confirm in synapse list --json or synapse status <target> --json → wait for READY → send task → evaluate result → kill → confirm cleanup in synapse list --json
Killing spawned agents after completion frees ports, memory, and PTY sessions, and prevents orphaned agents from accidentally accepting future tasks.
# Spawn, delegate, verify, cleanup
synapse spawn gemini --name Tester --role "test writer" -- --approval-mode=yolo
synapse list --json # Verify agent appears (AI-safe)
# Wait for readiness (or rely on server-side Readiness Gate)
synapse send Tester "Write tests for src/auth.py" --wait
# Evaluate result, then cleanup
synapse kill Tester -f
synapse list --json # Verify cleanup (AI-safe)
If synapse kill fails or the agent still appears in synapse list --json, retry with -f, check the agent status/logs, and report the cleanup failure instead of leaving an orphaned agent behind.
Response Mode Guide
Choose based on whether you need the result:
Mode
Flag
Use When
Wait
--wait
You need the answer before continuing (questions, reviews)
Notify
--notify (default)
Async — you'll be notified on completion
Silent
--silent
Fire-and-forget delegation (no response needed; sender history still updates best-effort on completion)
Worker Agent Guide
When you receive a task from a manager:
On Task Receipt
Start work immediately ([REPLY EXPECTED] requires a reply; otherwise no reply needed)
