Interface

Four doors into the same state: the dashboard (for the human watching), the CLI (for the human in a terminal and for scripts), MCP tools (for agents), and the in-session surface — the status line, permission cards, rewrites and blocks Claude Code renders while an agent works (section E). They share vocabulary exactly — a claim is a claim everywhere — and every dashboard action has a CLI equivalent.

The first three are surfaces you go to. The fourth comes to you: it is the only one an agent cannot ignore, because it arrives in the session's own footer and tool results. When a capability has to reach someone mid-task, it belongs in section E.

Shipped today (0.14.0)

• Nav: grouped sidebar nav from the view registry (M9.1) — Observe: Fleet / Timeline / Graphs · Work: Board / PRs / Trials / Hygiene · Insight: Outcomes / Gates / MCP / Context / Files / Spend / Stats / Search · Guard: Security / Provenance / Incidents / Rules / Team — plus a Session detail reached from any session row, and a ⌘K palette. Every list is a data-grid (sortable, resizable, filterable columns, layouts persisted per table).
• Board = a KPI strip (live / held / worktrees / ready or projects / incidents) + Tasks as a kanban (Ready · In progress · Blocked · Done) + Dispatch + Gates + Processes + Resources + Claims + a Worktree map (one tile per worktree, grouped by project, colored by live / dirty / unpushed / merged) + Incidents. Tasks and Worktrees carry a Cards/Table toggle (persisted). Every row, card and tile has one menu — the hover kebab, right-click, or Enter when focused — instead of inline action links; the menu carries the row's actions (open, diff, PR, run, claim, gates, release, stop, ack, codify, merge, copy …) with destructive ones last and confirmed. "View 4 — Incidents" ships as its own Incidents view (feed, Open/All, ack, ack-all) with a short open-only section on the Board.
• Steering (M13): Fleet rows carry the permission-broker Allow/Deny card for interactive sessions, not just spawned runs, and Incidents carry Codify → Apply. The Session input box exists for spawned runs (M3.3).
• Not yet: the full keyboard map (g f, j/k, ?) and the Settings page — project settings live in the sidebar menu, hook/rule status in swarm doctor. The ⌘K palette shipped with M9.1.
• CLI and MCP sections below are split into Today / Planned; section D lists the HTTP routes the daemon actually serves and section E the in-session surface.

A. Dashboard

Local web app served by the daemon at http://localhost:<port> (opened by swarm ui). Dense, monochrome, keyboard-first; it is an ops console, not a marketing page. Light and dark. Everything updates live over SSE; no refresh button anywhere.

Global frame

┌──────────────────────────────────────────────────────────────────────────────────────┐
│ ⌂ Swarm                              today $3.42    daemon ● 0.9.1    ⌕⌘K  💬  ⚙   │
├───────────────┬──────────────────────────────────────────────────────────────────────┤
│ OBSERVE       │                                                                      │
│  Fleet        │                                                                      │
│  Timeline     │                         <view>                                       │
│ WORK          │                                                                      │
│  Board        │                                                                      │
│  PRs          │                                                                      │
│ INSIGHT       │                                                                      │
│  Spend Stats… │                                                                      │
│ GUARD         │                                                                      │
│  Incidents ●2 │                                                                      │
│ PROJECTS      │                                                                      │
│ ● web-app  3  │                                                                      │
│ ○ swarm       │                                                                      │
│ + add folder  │                                                                      │
└───────────────┴──────────────────────────────────────────────────────────────────────┘

• View nav lives in the sidebar, grouped (M9.1): Observe (Fleet, Timeline, Graphs) · Work (Board, PRs) · Insight (Outcomes, Spend, Stats, Search) · Guard (Incidents, with unacked count). Views are declared once in a registry (VIEW_DEFS in app.js: id, label, icon, group, render, badge) — the nav, render dispatch, deep links and the palette all derive from it, so adding a view is one entry plus its render function. The header holds only chrome: logo, today's spend, daemon health, palette, feedback, settings.
• Below the nav: registered projects with live-session count and a coloured dot (● live, ○ idle). "Unpinned" groups sessions seen in unregistered folders; one click promotes to registered.
• Collapsing the sidebar leaves an icon rail — every view stays one click away; projects are reached through the palette.
• ⌘K palette: jump to any view, project or live session; anything else falls through to a full Search of Swarm's memory (handoffs, incidents, gates, prompts).
• Keyboard: ⌘K palette (arrows + enter), esc back/close. The fuller map (g f, j/k, ?) is still planned.

View 1 — Fleet (default)

Every live session across every project, one row each. Answers "what is happening on my machine right now?"

FLEET                                                    4 live · 2 idle · $3.42 today
┌────┬──────────────┬────────────┬──────────┬────────────────────────────────┬──────┬─────────┬──────┐
│    │ project      │ session    │ claim    │ now                            │ age  │ tokens  │ cost │
├────┼──────────────┼────────────┼──────────┼────────────────────────────────┼──────┼─────────┼──────┤
│ ●  │ web-app  │ owner ⌨    │ —        │ Read docs/planning/52-impl…    │ 2s   │ 184k    │ 1.10 │
│ ●  │ web-app  │ M0.6 ▶     │ M0.6     │ Bash bun run test              │ 41s  │ 92k     │ 0.61 │
│ ●  │ web-app  │  └ sub #2  │ (M0.6)   │ Grep "scan.*report"            │ 3s   │ 12k     │ 0.08 │
│ ●  │ api   │ owner ⌨    │ 9.13.5   │ waiting for input              │ 4m   │ 301k    │ 1.63 │
│ ◐  │ api   │ M0.7 ▶     │ M0.7     │ ⚠ permission: rm -rf dist      │ 12s  │ 40k     │ —    │
│ ○  │ web-app  │ M0.4 ▶     │ M0.4     │ ended · result ok · 14 turns   │ 1h   │ 210k    │ 1.40 │
└────┴──────────────┴────────────┴──────────┴────────────────────────────────┴──────┴─────────┴──────┘

• Icons: ⌨ interactive session, ▶ spawned by Swarm, └ subagent (nested under parent). ● active, ◐ blocked (waiting on permission/human), ○ ended.
• now is the latest event: tool name + compact input, or state text. Truncated; hover/focus shows full input.
• A blocked row is actionable inline: Allow / Deny / Open. That is the permission broker surface.
• Row click → Session view. Project cell click → Project view.
• Footer filter chips: project, kind, state, "only mine".

View 2 — Project

Shipped as Board: the CLAIMS, worktrees and RESOURCES blocks plus an Incidents section; TASKS ships when the repo declares [tasks] source (Ready / Open / All, Claim); PROCESSES lists what swarm serve / swarm proc started, with Stop; RECENT GATES lists verification runs (latest per gate decides) and the Tasks grid shows ✓ / ✗ / — per declared gate.

Board for one repository: claims, worktrees, resources, gates, and the task list if a task source is configured.

web-app   ~/code/web-app   main@a1b2c3 · 3 worktrees · 2 live       [▶ Run task] [⋯]

CLAIMS                                                             RESOURCES
┌──────┬──────────────┬─────────────┬───────────┬────────┐         ┌────────┬────────────┬───────┐
│ task │ holder       │ worktree    │ lease     │ state  │         │ name   │ holder     │ port  │
├──────┼──────────────┼─────────────┼───────────┼────────┤         ├────────┼────────────┼───────┤
│ M0.6 │ M0.6 ▶       │ wt/m0.6     │ 38m left  │ held   │         │ web    │ owner ⌨    │ 3000  │
│ M0.4 │ (ended)      │ wt/m0.4 ⚠   │ expired   │ orphan │         │ web    │ M0.6 ▶     │ 3401  │
│ M0.2 │ owner ⌨      │ wt/m0.2     │ 12m left  │ held   │         │ worker │ —          │ —     │
└──────┴──────────────┴─────────────┴───────────┴────────┘         │ db     │ owner ⌨    │ 54320 │
  ⚠ wt/m0.4 has 2 uncommitted files and no holder → [inspect] [adopt] [force release]   └────────┴────────────┴───────┘

TASKS  (docs/planning/52-implementation-plan.md · parsed 3s ago)            filter: ⚪ ready ▾
┌──────┬────────────────────────────────────┬──────────────┬──────────┬───────────────┐
│ id   │ task                               │ depends      │ status   │ gates         │
├──────┼────────────────────────────────────┼──────────────┼──────────┼───────────────┤
│ M0.6 │ web: Fleet + Session views         │ M0.3 ✅      │ 🟡 held  │ review ✓ sec — │
│ M0.7 │ smoke test + dogfood               │ M0.4 M0.5 M0.6│ ⚪ ready │ —             │
│ M1.1 │ claims + worktrees                 │ M0 ✅        │ ⚪ ready │ —             │
└──────┴────────────────────────────────────┴──────────────┴──────────┴───────────────┘
  row actions: [claim] [▶ run] [gates…]

PROCESSES                                             RECENT GATES
pid 48113  web   :3401  M0.6 ▶   up 14m  [stop]       M0.3 review   pass  2026-08-19 14:02  "…"
pid 47990  db    :54320 owner ⌨  up 3h                M0.3 security fail  2026-08-19 13:40  "open port"
                                                      M0.3 security pass  2026-08-19 13:58  "fixed"

• Run task opens a drawer: task id (from task source or free text), prompt (prefilled from the task row), model, permission mode, allowed tools, "open in new worktree" (always on). Submit = swarm run.
• Orphaned worktree banner is the single most important affordance in the product: it is where lost work gets found. adopt hands the claim to the current owner session; inspect shows git status + diff; force release needs a typed confirmation.
• Gates column shows each declared gate with ✓ / ✗ / — and the latest run on hover. A task cannot be marked done from here while any declared gate lacks a pass (M2).

View 3 — Session

The live stream for one session (interactive, spawned, or subagent). This is the "monitor how it's building" screen.

web-app · M0.6 ▶ · claude-opus-5 · wt/m0.6 · task M0.6 · 14m · 92k tok · $0.61        [⏸ pause] [■ stop] [⋯]
┌─────────────────────────────────────────────────────────────────┬────────────────────────────────┐
│ 14:02:11  ▸ user     implement M0.6 per docs/06-roadmap.md …    │ CONTEXT                        │
│ 14:02:13  ▸ assistant I'll start by reading the roadmap…        │ claim    M0.6 · 38m left       │
│ 14:02:14  ▸ Read      docs/06-roadmap.md                 ✓ 12ms │ worktree ~/.swarm/wt/web-app/m0.6│
│ 14:02:19  ▸ Bash      bun install                        ✓ 4.1s │ branch   task/m0.6 · 3 commits │
│ 14:02:40  ▸ Write     packages/web/src/Fleet.tsx         ✓      │ resources web:3401             │
│ 14:03:02  ▸ Bash      bun run test                       ✗ 1.2s │ processes 48113 web            │
│           │ FAIL Fleet.test.tsx › renders rows (expand)         │                                │
│ 14:03:05  ▸ assistant The test fails because…                   │ TURNS 14 · TOOLS 31            │
│ 14:03:08  ▸ Edit      packages/web/src/Fleet.tsx         ✓      │ Read 9 Bash 8 Edit 7 …          │
│ 14:03:12  ▸ Bash      rm -rf dist                  ⚠ waiting    │                                │
│           │ rule: none matched · asking human    [Allow] [Deny] │ DENIED 1                       │
│ 14:03:12  ▸ Agent     └ sub #2 "find scan report callers" ●     │ 14:01 Edit ../api/…    │
│                                                                 │   shared-tree-readonly         │
│ ▍ streaming…                                                    │                                │
├─────────────────────────────────────────────────────────────────┴────────────────────────────────┤
│ > say something to this agent…                                                     [send ⏎]      │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘

• Left: event log. One line per tool call with status and duration; assistant text collapsed to first line, expand on click; subagents render as nested rows, click to open their own Session view. Follows the tail unless you scroll up (then a "↓ 12 new" pill).
• Token deltas stream in place when --include-partial-messages is on; off by default to keep the log readable.
• Right: what the agent holds and what it has been denied — the same additionalContext the agent itself receives on SessionStart.
• Bottom input exists only for spawned sessions (writes to the run's stdin as a stream-json user message; Stop closes stdin then signals the pid). Interactive sessions have no box — type in your terminal.
• Pause = stop forwarding permission approvals (agent blocks at next ask). Stop = SIGTERM then SIGKILL, release resources, keep the claim as orphaned if dirty.

View 4 — Incidents

Shipped as the Incidents view: a data-grid feed (when, project, session, rule, asked/denied, command, reason, acked) with Open / All chips, per-row Ack and Ack all; the nav badge is the open count. Kinds: rule hits (denied / asked), orphaned_claim, gate_failed.

Chronological list of things that went wrong or were prevented. Each is one line + ack.

INCIDENTS                                                                 [ack all visible]
⚠ 14:01  web-app  owner ⌨   denied Edit outside worktree (shared-tree-readonly)              [ack]
⚠ 13:55  api   M0.7 ▶    claim M0.7 expired with dirty worktree → orphaned                 [open]
⚠ 13:40  web-app  M0.3 ▶    gate security failed: "open port in preview"                      [open]
⚠ 12:10  api   —         process 47001 (worker) alive but no session owns it               [stop] [ack]

Kinds: denied, orphaned, gate-failed, stray-process, port-conflict, daemon-restart. Acked incidents stay searchable.

Shipped views not in the wireframes

• Spend — cost by project, by model and by agent, today and all-time, with a stacked daily-cost chart (7/14/30/90-day range) and a weekday × hour activity heatmap. Per-project when a project is selected, machine-wide from Fleet.
• Stats — the long-horizon numbers: all-time spend / tokens / turns / streak KPIs, a 52-week activity calendar, tokens per day by class, cumulative spend, turns by hour of day, model mix, token composition, tool leaderboard and record holders. Fetched on open from GET /v1/stats, not part of the live snapshot. swarm stats --json prints the same numbers.
• Timeline — one lane per session grouped by project, coloured by agent, over a 3–72 h window; answers "who was working when" across every repo.
• PRs — one queue of open pull/merge requests across every tracked repo, read through the locally-authenticated gh / glab CLIs (GitHub + GitLab, no tokens stored). Shows checks, review state, draft and mergeability; a green row gets a Merge action (squash via the same CLI). Polled gently per project (about every two minutes).

Settings (a page, not a view)

Hook install status per scope (user / project) with install/uninstall buttons, rule toggles per project with the rule's one-line rationale, lease TTL, worktree root, task-source path, model/permission defaults for run, tested Claude Code version range vs installed.

B. CLI

swarm <noun> <verb> with a few top-level shortcuts. Human-readable by default, --json everywhere, exit codes: 0 ok, 1 refused (fail-closed), 2 error. Project resolved from cwd unless -p <name|path>.

Today — exactly what swarm --help prints:

swarm setup                        start the daemon, install hooks, open the dashboard (do this first)
swarm start | stop | restart       manage the background daemon
swarm status [-p]                  live sessions (whole machine, or one project)
swarm doctor                       check everything and print the fix for each gap (incl. per-event hook coverage and org-policy overrides, M8.1)
swarm add <path> [--name n]        register (pin) a project
swarm ls                           list projects
swarm ui                           open the dashboard
swarm tail [--project p] [--session id]   follow the live event stream
swarm install | uninstall          add/remove Swarm hooks (and the MCP server) in ~/.claude/settings.json
swarm install --statusline         also set Claude Code's statusLine to `swarm statusline` (never replaces one you set)
swarm statusline                   statusLine command: model · ctx % · cost · plan windows │ task · lease · budget · incidents · waiting (400 ms, fails open)

swarm claim <task> [--owner n]     claim a task in a fresh isolated git worktree (fail-closed); runs `[worktree]` copy/setup (M7.1)
swarm renew <task>                 extend the lease
swarm release <task> [--force]     release + remove worktree; refuses if dirty or unpushed
swarm claims                       list claims
swarm reap                         release abandoned claims (keeps ones holding work)
swarm wt [ls]                      every worktree with dirty / unpushed / behind / merged (M7.2)
swarm wt create <name> [--base r]  task-less worktree under ~/.swarm/worktrees, branch wt/<name>, bootstrapped
swarm wt open|rm <ref> [--force]   open via `[worktree] open` / remove (refuses dirty, unpushed, main, held)
swarm wt gc [--apply]              stale worktrees (merged branch / released claim); --apply removes the clean ones
swarm wt diff <ref> [--file f] [--patch]   what a worktree changed vs the main branch (M7.3)
swarm pr open <task|ref> [--title] [--body] [--draft] [--dry-run]   push + open a PR/MR prefilled from task, handoff, gates, files (M7.3)
swarm questions [--all] [--everywhere] · swarm answer <id> <text…>   questions agents parked for a human (M7.7)
swarm dispatch --ready | <task…> [--max N] [--parallel N]   claim + run per task, cap per project; status | clear (M7.5)

swarm res ls                                              held singletons (project + machine-global)
swarm res acquire <name> [--owner n] [--pid n] [--port n]  e.g. web, worker, db, port:3000
                                   pid → alive while the process is; else a lease (default 30m)
                                   port → auto-added to the protected-ports rule while held
swarm res release <name> [--force]                        refuses if another owner holds it
swarm serve start [--name web] [--from-port 3400] -- <cmd>   port-allocating, pid-tracked, PORT set, logs in ~/.swarm/logs
swarm serve ls | stop [name|pid]                          only processes this project started; by pid + start time
swarm proc start [--name n] -- <cmd> | ls | stop <name|pid>   same, without a port
swarm tasks [--ready]                                     the repo's task source
swarm gate record <task> <gate> pass|fail --rubric "…" [--evidence "…"]   rubric required; latest run wins
swarm gate ls [task]                                      required gates + verdicts (+ history for one task)
swarm gate run <task> [gate…]                             execute [gates.<name>] cmd gates in the held worktree, record verdicts (M7.4)
swarm handoff <task> --done "…" --remaining "…" [--files a,b] [--verify "…"]   notes for the next holder
swarm resume <task>                                       latest handoff (also injected on SessionStart)
swarm run --task <id> --prompt "…"|--prompt-file f [--model] [--permission-mode] [--allowed-tools a,b] [--max-turns n]
                                                          claim + spawn claude -p in the worktree (stream-json both ways)
swarm run ls | send <task|id> "text" | stop <task|id>     steer over stdin / stop by pid
swarm run resume <session-id> [--model] [--permission-mode]   spawn a run that picks up where a dead session stopped (handoff + tail)
swarm rules dryrun [--set rule=mode,…] [--limit n]        replay this repo's history under rule modes; what would fire + flaky signals
swarm search <query…> [-p] [--kind handoff|incident|gate|session]   memory over Swarm's own data (never the codebase)
swarm stats [-p] [--json]          the Stats view's numbers (totals, per-day classes, records)
swarm workflow <name> <task> | workflow ls | workflow stop <task>   run a [[workflows]] sequence on a task (M7.8)
swarm msg send <to> <text…> [-p] | msg ls [-p]   message a session id, a task's holder, or "lead" (M7.6)
swarm audit export [--since 30d|ISO] [-p] [--type t] [--format jsonl|csv|json]   the audit log to stdout (M8.2c)
swarm login [url] [--token t]      log in to the team daemon ([team].url) and register this machine (M8.3c)
swarm backup [dest] | restore <src>   snapshot ~/.swarm (VACUUM INTO, zero downtime) / restore it (daemon stopped)
swarm doctor --migrate             apply pending db migrations
swarm demo                         open a seeded demo dashboard (own home + port; real data untouched)

Env: SWARM_URL, SWARM_PORT (default 7777), SWARM_HOME (~/.swarm).

Planned — same grammar, not built:

swarm rm <name>                                  unregister a project
swarm wt ls|path <task>|adopt <task>

swarm run attach <session>          (use `swarm tail --session <id>` for now)

swarm status sample:

web-app  main@a1b2c3  3 live  1 incident
  ⌨ owner      —      Read docs/…                2s
  ▶ M0.6       M0.6   Bash bun run test         41s   wt/m0.6  web:3401
  ○ M0.4       M0.4   ended ok · orphan wt ⚠     1h
resources: web→owner:3000  web→M0.6:3401  db→owner:54320

C. MCP tools (what agents see)

Server name swarm (stdio, swarm-mcp, registered user-wide by swarm install); project inferred from the server's cwd. Tool names use underscores, as registered. Every tool returns a short human sentence plus a JSON block, and every failure explains who holds the thing and what to do instead.

Today

Planned

The permission broker is not a tool — it is the PreToolUse hook (section E), so it applies to every session without an agent having to opt in.

Context injection (shipped on SessionStart, built by store.sessionContext(cwd); per-prompt injection not built) — the hook returns additionalContext like:

[swarm] project web-app · you hold M0.6 (38m left) in ~/.swarm/wt/web-app/m0.6 · resources: web:3401
[swarm] rules: shared-tree-readonly, no-pattern-kill, claim-required-to-write
[swarm] handoff from previous holder: done=…, remaining=…, verify=…

D. HTTP routes (what the daemon serves today)

Everything above is a thin wrapper over these. Bound to 127.0.0.1 only; port discovered via ~/.swarm/daemon.json (SWARM_URL overrides). Source of truth: packages/daemon/src/app.ts.

Not built: a unix socket. Stdin for spawned runs is POST /v1/runs/:id/send.

E. In-session surfaces (what Claude Code shows while an agent works)

The fourth door, and the only one that reaches a session that never opens a dashboard. All of it rides Claude Code's own hook response fields — 33 hook events exist; Swarm installs 12 (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, SubagentStart, SubagentStop, Stop, SessionEnd, Notification, PreCompact, PermissionRequest) plus one asyncRewake waiter on Stop. Verify the field names against the current Claude Code reference before changing any of this; do not rely on memory. The permission surface reaches three more agents through their own pre-tool hooks (M12.4, core/src/agenthooks.ts): Codex PreToolUse, Gemini CLI BeforeTool, and Cursor, which runs these Claude Code hooks itself; none can ask, so an ask rule refuses there (OQ-29).

Every one of these shares the hook shim's contract: a fast budget (400 ms, SWARM_HOOK_TIMEOUT_MS), fails open on any error or timeout, and never starts the daemon — a hook must stay fast. Only the two surfaces that legitimately wait on a human or a gate get a longer one, and each asks first: Stop keeps the fast budget unless GET /v1/repair says this repo armed the loop, and PermissionRequest waits only while a dashboard is watching. A wedged or absent daemon therefore costs a session nothing but the loss of these surfaces.

Two consequences worth stating plainly:

• A rule is a denial, not a paragraph. Anything Swarm wants an agent to stop doing is a hook decision here, not prose in a CLAUDE.md it may or may not read. This is why the repo-agnostic constraint holds: none of the above needs a file inside the monitored repository.
• Discoverability is the open weakness. The status line is opt-in and bun run setup does not mention it, so a machine onboarded the normal way silently never gets a footer. swarm doctor reports the gap; nothing else does.

F. Design constraints shared by all four

• Same nouns, same verbs, same error texts. A denial in the session log, the CLI and the MCP result is the same sentence.
• Nothing destructive without a typed confirmation in the UI or --force in the CLI; both are logged as incidents.
• Every list is filterable by project and copyable as JSON.
• The dashboard never invents state the CLI can't show: if you can't get it from swarm status --json, it doesn't belong in the UI.
• Anything that has to reach a session mid-task goes in section E. A capability that only exists in the dashboard is a capability the agent doing the work will never see.

Source: docs/08-interface.md · v0.16.0.