%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#eef6ff", "primaryBorderColor": "#2563eb", "primaryTextColor": "#0f172a", "lineColor": "#64748b", "tertiaryColor": "#f8fafc", "fontFamily": "Inter, ui-sans-serif, system-ui, sans-serif"}}}%%
flowchart LR
Operator["Operator surface
Telegram / CLI / iOS"] -->|intent, approvals, summaries| Gateway["Notification gateway
Hermes / launcher / shell"]
Gateway -->|MCP tools| Runtime["Agent runtime
Claude Code / Codex / OpenCode / Hermes"]
Runtime -->|register, tasks, messages, locks, KV| Coordinator["swarm-mcp Coordinator
stdio MCP server per session"]
subgraph Durable["swarm.db durable state"]
Instances[("instances
instance_id, heartbeat, labels")]
Tasks[("tasks
status, deps, assignee, result")]
Messages[("messages + events
peer activity and audit")]
Context[("context
active file locks")]
KV[("kv
workspace identity and small shared state")]
end
Coordinator -->|register / heartbeat / adopt| Instances Coordinator -->|request / claim / update| Tasks Coordinator -->|send / wait / audit| Messages Coordinator -->|get_file_lock / lock / unlock| Context Coordinator -->|kv_get / kv_set| KV
Gateway -->|dispatch spawn intent| Spawner["Spawner backend
creates new workers
herdr today / swarm-ui alt / swarm-server future"]
Spawner -->|precreate row + inject SWARM_MCP_INSTANCE_ID| Instances
Spawner -->|launch worker process on chosen surface| Worker["Worker agent
adopts instance_id"]
Worker -->|register/adopt + coordinate| Coordinator
Worker -->|publish transport handle| KV
Coordinator -->|prompt_peer reads identity/workspace/backend/instance| KV
Coordinator -->|wake existing handle| Workspace["Workspace backend
resolves and wakes published handles
herdr panes today / swarm-server PTYs future"]
Workspace -->|short wake prompt only| Worker
Gateway <-->|human-facing issue state| Tracker["Work tracker
Linear / Jira / backlog"]
Worker -->|authorized evidence and comments| Tracker
classDef durable fill:#ecfdf5,stroke:#059669,color:#064e3b classDef adapter fill:#fff7ed,stroke:#ea580c,color:#7c2d12 classDef runtime fill:#eef6ff,stroke:#2563eb,color:#0f172a classDef surface fill:#fdf2f8,stroke:#db2777,color:#831843 classDef tracker fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95
class Coordinator,Instances,Tasks,Messages,Context,KV durable class Spawner,Workspace adapter class Runtime,Worker runtime class Operator,Gateway surface class Tracker tracker