How Clankie Works

Clankie's job is trust in absentia: you hand work to a swarm of coding agents, walk away, and still know what happened — steer it from your phone, and check what it did when you're back. This page is the mental model behind that: the stage, the lead loop, the windows, and the receipt.

flowchart LR
  you["you<br/>phone · Discord · tracker · terminal"]
  lead["the lead<br/>clankie-agent"]
  stage["the stage<br/>clankie-herdr panes"]
  receipt["the receipt<br/>transcripts · graph · ledger"]

  you -->|ask| lead
  lead -->|spawn · watch · unblock · harvest| stage
  stage -->|everything it did| receipt
  lead -->|verified result + evidence| you
  receipt -.->|audit any time| you

The Stage: If It Runs, It's a Pane

Every agent Clankie runs is a real terminal pane on clankie-herdr, Clankie's bundled terminal multiplexer — named, labeled, and attributable. There are no hidden in-process subagents. When the lead has background or inbound work, it does not answer invisibly; it routes the work to a pane where you (or any other agent) can watch it.

This is containment by construction, not convention. Because Clankie ships its own stage, the roster of running agents and the orchestration graph are facts the system owns — not best-effort reconstructions of someone else's terminal. A persistent named session survives restarts and disconnects, so "always on" is the stage's job, and any window can attach to the same live panes.

Workers are whichever harnesses you already use: Claude Code, Codex, OpenCode, or Clankie's own clankie worker CLI, each chosen explicitly per spawn, on your existing subscriptions or on local models. Clankie is deliberately harness-neutral — it owns the layer above the harness, so whatever the model vendors ship next slots in as another performer on the same stage.

The Lead Loop

The lead agent (clankie-agent, an always-on brain built on eve) runs one loop over the stage:

flowchart LR
  plan["plan"] --> spawn["spawn"]
  spawn --> watch["watch"]
  watch --> unblock["unblock"]
  unblock --> watch
  watch --> harvest["harvest"]
  harvest --> verify["verify"]
  verify --> report["report"]

• Plan. Work arrives from any channel — chat, phone, Discord, or the work tracker. The lead scopes it into tasks, files them in the tracker when one is bound, and decides what fans out.
• Spawn. Every spawn goes through one seam: it names the pane (clankie:<slug> plus a human-readable label), wraps the worker so a durable transcript is captured from the first byte, and arms a completion watcher on the pane. Model and effort are selectable per spawn, so mechanical work rides a cheap or local model while judgment-heavy work gets a top tier.
• Watch. The lead does not poll. Watchers block on the stage's agent-status events, classify the outcome against the run's completion sentinels, and deliver exactly one wake — [worker done], [worker blocked] — into the lead's pane. Milestone watches ("wake me when it prints X") ride the same machinery.
• Unblock. When a worker asks a question the lead can answer, it answers — reading the pane, steering it, or pulling in a consultant pane for a bounded second opinion. When only a human can answer, the run surfaces needs_human and your phone gets a push. Unblocking a stuck worker from the couch is the core interaction Clankie exists for.
• Harvest. When a worker settles, the lead pulls the result — the diff, the branch, the findings — back together with every other worker's, and closes the pane. Scrollback is disposable once the tracker and transcripts hold the truth.
• Verify. Claimed is not done. The lead checks the result against the task — runs the checks, reads the diff, exercises the change — and only then calls it verified. Merge authority is a policy flag: once you trust the loop, the lead can merge its own workers' green, reviewed PRs autonomously; until then, it hands you the evidence and waits.
• Report. The result lands where you asked from, with receipts attached: what was asked, who did what, what was verified, what it cost.

Each lead's state is legible from outside at every step — working, awaiting, harvest_ready, needs_human, blocked — so the windows can show you at a glance whether the swarm needs you.

The Windows

The stage runs headless on an always-on host. The windows are how you reach it:

• The Clankies iOS app (private) is the primary consumer window: your swarm as a garden of characters you can check on, with live chat, push notifications on blocked/done, and — one tap behind the garden — a real terminal attach onto any pane. The cute skin never hides the truth; the terminal is the trust escape hatch. It reaches the host over your tailnet through two narrow doors: a lifecycle supervisor that can cold-start a stopped brain, and a bearer-token relay for everything live.
• Discord is presence: Clankie chats in your server, joins voice (through ClankVox, the Rust presence plane — Opus, E2EE via DAVE, real 20ms pacing), and can watch or publish Go Live streams. Talking to your swarm lead in voice while it screen-shares its work is exactly as fun as it sounds. Voice is opt-in and off the critical path.
• The work tracker — Linear, GitHub Issues, or Jira — is the durable window: the lead files the issues, workers keep the threads current, and status means something (In Review has a named verifier). Integrations are opt-in by role; the ones you skip stay off.
• The terminal itself is always a window. clankie dev opens the face; or just attach to the stage and look.

Naming doctrine, for reading the docs: Clankie is the lead you talk to; clankies are the swarm; Clankies is the window where you watch them.

The Receipt

"Watch your agents work" is table stakes. Clankie's bet is that the durable product is the receipt: after a run, you can audit — not just recall — what happened.

This is why autonomous behavior is acceptable at all: the lead only earns authority (like merging its own workers' PRs) because every action it took is inspectable after the fact. Trust is downstream of legibility.

Where It Runs

Clankie is the self-hosted personal swarm: your machine, your credentials, your history, no telemetry. The brain runs on a Mac today; the only macOS-specific pieces are the launchd supervisor and the host-command sandbox. The phone already treats the brain as remote, so relocating it — a small Linux box, eventually a hosted deployment — changes where it runs, not what it is.

Two deliberate modes bracket the cost/privacy spectrum:

• Subscription workers (default): Claude Code and Codex on the subscriptions you already pay for, coordinated instead of babysat.
• Local Fleet: the whole swarm — lead and workers — on one Apple Silicon box, no frontier API. Slower and less sharp, but private, offline-capable, and free per token.

Ways In

Adopt as much or as little as you want; every tier is a shippable stopping point:

1. The protocol — Clankie's coordination grammar (named visible workers, completion sentinels, lead/worker skills) inside your existing harness and mux. Install it with npx create-clankie --protocol. No product install, no trust required.
2. The stage — run clankie-herdr and get the fan-out grammar with every agent visible.
3. Clankie — the always-on lead and the full loop above. Install guide.
4. The windows — pair the phone, add Discord, bind the tracker.

Start where you're comfortable; the loop is the same at every tier.