SKILL.md

Synapse A2A Communication

Inter-agent communication framework via Google A2A Protocol.

Worktree Discipline (subagents, read this first)

**NEVER cd into .synapse/worktrees/<name>/ directories.**

Subagents (Claude Code Agent tool, Codex subprocess, and any other

sub-process driven by the parent session) inherit a persistent shell

from the parent. A stray cd into a worktree leaks out of the subagent

turn and silently corrupts the parent's working directory — git status,

git diff, and even git commit then land on the wrong worktree, which

wastes debugging time and can put commits on the wrong branch.

Rules for working with .synapse/worktrees/:

Do not cd into a worktree, ever. Stay in the original working

directory for the entire session.

Read and write files inside a worktree using absolute paths only

(for example Read /Volumes/.../.synapse/worktrees/foo/src/bar.py,

not cd .synapse/worktrees/foo && cat src/bar.py).

Run git against a worktree with git -C /abs/path/to/worktree ...

instead of changing directory.

Worktrees are managed by Synapse (synapse spawn --worktree,

synapse team start --worktree). Treat them as read/write data

surfaces, not as places to live.

If you need to operate from inside a worktree (e.g. running pytest

there), spawn a dedicated agent for it with synapse spawn --worktree

rather than changing the parent shell's directory.

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

Agent detail

synapse status <target> [--json]

Stuck-agent watchdog (Stage 1)

synapse watchdog check [--alarm-only] [--json] (one-shot heuristic scan; #646)

Send message

synapse send <target> "<msg>" (default: --notify; --from auto-detected)

Broadcast

synapse broadcast "<msg>"

Wait for reply

synapse send <target> "<msg>" --wait

Fire-and-forget

synapse send <target> "<msg>" --silent

synapse reply "<response>"

Reply to specific

synapse reply "<response>" --to <sender_id>

Reply with failure

synapse reply --fail "<reason>"

Interrupt (priority 4)

synapse interrupt <target> "<msg>"

Send keys to PTY (escape hatch for TUI dialogs; #695)

synapse send-keys <target> <keys> (e.g. a for codex "don't ask again", \r for Enter; bypasses A2A — use when an agent is stuck on an interactive dialog without synapse jump)

Spawn agent

synapse spawn <type> --name <n> --role "<r>" -- <tool-specific-automation-args>

Spawn + send first task (preferred for delegation)

synapse spawn <type> --name <n> --role "<r>" --task-file <path> --task-timeout 600 --notify

Spawn with worktree

synapse spawn <type> --worktree --name <n> --role "<r>" -- <tool-specific-automation-args>

Team start

synapse team start <homogeneous-profiles...> [--worktree] -- <tool-specific-automation-args>

Approve plan

synapse approve <id>

Reject plan

synapse reject <id> --reason "<feedback>"

Save knowledge

synapse memory save <key> "<content>" --tags <t> --notify

Search knowledge

synapse memory search "<query>"

Lock file

synapse file-safety lock <file> <agent_id> --intent "..."

Check locks

synapse file-safety locks

Task history

synapse history list --agent <name>

Kill agent

synapse kill <name> -f

Cleanup orphans

synapse cleanup --dry-run (list); synapse cleanup -f (kill all orphans whose parent crashed/cleared)

Attach files

synapse send <target> "<msg>" --attach <file> --wait

Saved agents

synapse agents list / synapse agents set <profile> / synapse agents unset <profile> / synapse agents roles / synapse spawn <agent_id>; live agents expose agent_definition_id as a stable target alias

Shared session handoff

synapse session publish <name> / synapse session import <name> using SYNAPSE_SHARED_SESSION_DIR

Post to Canvas

synapse canvas post <format> "<body>" --title "<title>"

Link preview

synapse canvas link "<url>" --title "<title>"

Post template

synapse canvas briefing '<json>' --title "<title>"

Post plan card

synapse canvas plan '<json>' --title "<title>" (Mermaid DAG + step list with status tracking)

Open Canvas

synapse canvas open (auto-starts server, opens browser)

Restart Canvas

synapse canvas restart (stop + start; use when canvas status reports ⚠ STALE after upgrade)

Sync workflow skills

synapse workflow sync (regenerate skills from workflow YAMLs, remove orphans)

Run workflow (auto-spawn)

synapse workflow run <name> --auto-spawn (supports DAG steps with depends_on and condition)

Multi-agent patterns

synapse map init/list/show/run/status/stop (built-in: generator-verifier, orchestrator-subagent, agent-teams, message-bus, shared-state)

Wiki ingest

synapse wiki ingest <source> [--scope project|global] (ingest a source file into the wiki)

Wiki query

synapse wiki query "<question>" [--scope project|global] (search wiki pages)

Wiki lint

synapse wiki lint [--scope project|global] (validate wiki consistency)

Wiki status

synapse wiki status [--scope project|global] (show wiki index stats)

Collaboration Decision Framework

Evaluate collaboration opportunities before starting work:

Situation

Action

Small task within your role

Do it yourself

Task outside your role, READY agent exists

Delegate: synapse send --notify or --silent

No suitable agent exists, need to delegate a task

Spawn + task in one command: synapse spawn <type> --name <n> --role "<r>" --task-file <spec.md> --task-timeout 600 --notify. This spawns, waits for READY, and sends the first task — no manual readiness polling needed.

Need a bare agent (no initial task)

synapse spawn <type> --name <n> --role "<r>" (send tasks later via synapse send)

Stuck or need expertise

Ask: synapse send <target> "<question>" --wait

Completed a milestone

Report: synapse send <manager> "<summary>" --silent

Discovered a pattern

Share: synapse memory save <key> "<pattern>" --tags ... --notify

Recommended Collaboration Gate (3+ phases OR 10+ file changes):

Consider these steps before diving into large work:

synapse list --json or MCP list_agents — check available agents

synapse memory search "<topic>" — check if someone already solved this

Build Agent Assignment Plan (Phase / Agent / Rationale) when delegation is beneficial

Spawn specialists if needed (prefer different model types for diversity)

Skip this gate for small/medium tasks where the overhead exceeds the benefit.

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 -- skip inside worktrees (SYNAPSE_WORKTREE_PATH)

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

Probabilistic Recall

Recall relevant past task observations by recency, importance, and keyword overlap without dumping all history

HistoryManager.recall_observations

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/restart

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, create/edit/delete/import/export workflow YAML, trigger runs, monitor progress with live SSE updates; run history persisted to SQLite across restarts)

synapse canvas open → navigate to #/workflow

Harnesses View

Browser-based browser for agent harness resources at Canvas #/harnesses — sub-views #/harnesses/skills (SKILL.md inventory across user/project/synapse/plugin scopes, scanned per active project root) and #/harnesses/mcp (MCP server configs from project .mcp.json per active root, plus user-scope: Claude Code ~/.claude.json, Codex ~/.codex/config.toml, Gemini ~/.gemini/settings.json, OpenCode ~/.config/opencode/opencode.json, and Claude Desktop config)

synapse canvas open → navigate to #/harnesses

Plan Cards

Mermaid DAG + step list with dependency visualization

synapse canvas plan

LLM Wiki

Structured knowledge base for ingesting, querying, and validating project/global docs

synapse wiki ingest/query/lint/status

Smart Suggest

MCP tool that analyzes prompts and suggests team/task splits for large work

MCP tool: analyze_task

Project Learnings

Saved definitions can load project-adaptive learnings from .synapse/learnings/<agent_definition_id>.md on startup

synapse agents set + Markdown learnings

Proactive Mode

Task-size-based feature usage guide (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, canvas_post

synapse mcp serve / python -m synapse.mcp

When to Use Canvas

Use Canvas when the output benefits from visual structure or will be referenced later:

Use Canvas for: diagrams, comparison tables, multi-step plans, design docs, results with rich formatting

Skip Canvas for: simple completion reports, single-file changes, quick status updates (use broadcast or reply instead)

Template selection guide:

briefing — structured reports, status updates, release summaries

comparison — before/after, option trade-offs, review diffs

steps — plans, migration sequences, execution checklists

slides — walkthroughs, demos, page-by-page narratives

dashboard — multi-widget operational snapshots, compact status boards

plan — task DAGs with Mermaid visualization and step tracking

Use raw synapse canvas post <format> for single blocks; templates for multi-section content.

Spawning Decision Table

⚠️ Same-model rule — try subagents first. When a Claude Code agent needs

another claude (or a codex agent needs another codex), use the in-process

subagent (Agent / Task tool for Claude, subprocess for Codex) before

reaching for synapse spawn. Spawning the same model on the same account

shares the rate-limit window — it doubles consumption against the same quota

instead of distributing it. Reserve same-model synapse spawn for cases

where the helper must outlive the parent session, needs file isolation that

subagents can't provide, or holds a distinct long-running role.

synapse spawn is the right tool for cross-model delegation

(Claude → codex / gemini), agents that lack subagent support

(Gemini / OpenCode / Copilot), or persistent multi-task helpers.

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 (Synapse already injects these automatically — pass --no-auto-approve

to opt out):

Claude Code: synapse spawn claude --name <n> --role "<r>" -- --permission-mode=auto

Gemini CLI: synapse spawn gemini --name <n> --role "<r>" -- --approval-mode=yolo

Codex CLI: synapse spawn codex --name <n> --role "<r>" (synapse injects -cdefault_permissions=":workspace"; Codex 0.128+ removed --full-auto)

OpenCode: synapse spawn opencode --name <n> --role "<r>" -- --agent build (selects the build agent profile; not a skip-approval flag)

Copilot CLI: synapse spawn copilot --name <n> --role "<r>" -- --allow-all

Claude team: synapse team start claude claude -- --permission-mode=auto

Gemini team: synapse team start gemini gemini -- --approval-mode=yolo

Codex team: synapse team start codex codex (synapse injects -cdefault_permissions=":workspace")

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

2026-04 migration: Anthropic deprecated --dangerously-skip-permissions

in favor of --permission-mode=auto (safety classifier instead of disabling

all checks). Gemini similarly recommends --approval-mode=yolo over the

legacy --yolo / -y short forms. Synapse now injects the new flags by

default; the legacy forms still work and remain in each profile's

alternative_flags.

Condition

Action

Existing READY agent can handle it

synapse send — reuse is faster (avoids startup overhead)

Same-model helper needed (Claude → claude, Codex → codex)

Use the in-process subagent first (Agent/Task tool for Claude, subprocess for Codex). synapse spawn same-model shares the rate-limit window.

Need parallel execution

synapse spawn with --worktree -- <tool-specific-automation-args> for file isolation (cross-model preferred)

Task needs a different model's strengths

synapse spawn a different type (Claude spawns Gemini / Codex, etc.)

User specified agent count

Follow exactly

Single focused subtask

Subagent (same model) or synapse spawn (cross model)

N independent subtasks

Subagents for same-model fan-out, synapse spawn for cross-model

Spawn lifecycle (preferred, one-command): synapse spawn --task-file ... --task-timeout 600 --notify → wait for A2A completion notification → evaluate result → synapse kill <name> -f → confirm in synapse list --json

Legacy lifecycle (only when you need control between spawn and first task): spawn → poll synapse list --json or synapse status <target> --json for READY (allow several minutes; default 30s timeout is too short for most profiles) → synapse send --notify → evaluate → synapse kill -f → confirm cleanup.

⚠️ Common pitfall: sending to an agent that is not yet READY either hangs at the HTTP layer or blocks on the internal readiness wait. Either use synapse spawn --task-file (preferred — it handles readiness for you), or explicitly confirm "status": "READY" before calling synapse send. Do not assume 30 seconds is enough — most profiles take 1-5 minutes.

Agent status set (synapse list --json .status):

Status

Meaning

Action

READY

Idle, can accept new work

synapse send

SENDING_REPLY

Temporarily sending an outbound A2A send/reply POST

Wait; previous status is restored after the POST finishes

PROCESSING

Actively working a task

Wait, or synapse interrupt if stuck

WAITING

Awaiting a permission/approval prompt

synapse approve / synapse reject

WAITING_FOR_INPUT

Task is paused asking for non-permission input (#538)

synapse reply <task_id> with the answer

RATE_LIMITED

Last task failed due to LLM provider rate limit (#561)

Wait for the provider window to reset, then re-send

DONE

Task complete; demotes to READY after ~10s

Read result, then proceed

SHUTTING_DOWN

Agent is exiting

Do not send

**Stuck on a CLI dialog (not A2A WAITING)?** When an agent looks idle but is

blocked on its own TUI prompt (codex edit-confirmation, model picker,

rate-limit dialog), use synapse send-keys <target> <keys> to write directly

to the PTY without synapse jump. Example: synapse send-keys Impl a sends

the codex "don't ask again" shortcut. (#695)

Killing spawned agents after completion frees ports, memory, and PTY sessions,

and prevents orphaned agents from accidentally accepting future tasks.

# Preferred: one-command spawn + delegate (handles readiness wait internally)

synapse spawn gemini \

    --name Tester \

    --role "test writer" \

    --task-file /tmp/test-spec.md \

    --task-timeout 600 \

    --notify

# (do other work; receive async A2A notification when Tester finishes)

# 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 (synapse reply is valid for Synapse-tracked messages with a registered reply target, including [REPLY EXPECTED] and --response; otherwise user-pasted A2A: text has no reply target, so respond with synapse send instead)

Check shared knowledge: synapse memory search "<task topic>"

Lock files before editing (skip if SYNAPSE_WORKTREE_PATH is set): synapse file-safety lock <file> $SYNAPSE_AGENT_ID

During Work

Report progress if task takes >5 minutes: synapse send <manager> "Progress: <update>" --silent

Report blockers immediately: synapse send <manager> "<question>" --wait

Save findings: synapse memory save <key> "<finding>" --tags <topic>

You can delegate subtasks too — spawn helpers (prefer different model types)

Always clean up agents you spawn: synapse kill <name> -f

On Completion

Report to manager: synapse send <manager> "Done: <summary>" --silent

On Failure

Report details: synapse send <manager> "Failed: <error details>" --silent

Related Skills

Skill

Purpose

synapse-manager

Multi-agent orchestration workflow (delegation, monitoring, verification)

synapse-reinst

Re-inject instructions after /clear or context reset

References

For detailed information, consult these reference files:

Reference

Contents

references/commands.md

Full CLI command documentation with all options

references/api.md

A2A endpoints, readiness gate, error handling

references/examples.md

Multi-agent workflow examples and patterns

references/file-safety.md

File locking workflow and commands

references/messaging.md

Sending, replying, priorities, status states, interactive controls

references/spawning.md

Spawn lifecycle, patterns, worktree, permissions, API

references/collaboration.md

Agent naming, external agents, auth, resume, path overrides

references/features.md

Sessions, workflows, saved agents, tokens, skills, settings, Canvas

synapse-a2a

SKILL.md

Synapse A2A Communication

Worktree Discipline (subagents, read this first)

Quick Reference

Collaboration Decision Framework

Use Synapse Features Actively

When to Use Canvas

Spawning Decision Table

Response Mode Guide

Worker Agent Guide

On Task Receipt

During Work

On Completion

On Failure

Related Skills

References

Stop writing automation&scrapers

synapse-a2a

SKILL.md

Synapse A2A Communication

Worktree Discipline (subagents, read this first)

Quick Reference

Collaboration Decision Framework

Use Synapse Features Actively

When to Use Canvas

Spawning Decision Table

Response Mode Guide

Worker Agent Guide

On Task Receipt

During Work

On Completion

On Failure

Related Skills

References

Let your agent run on any real-world website

Related skills

Stop writing automation&scrapers