Clankie

Walk away from a running swarm and still know what happened. Clankie is a lead agent that runs your coding agents as visible panes in a bundled terminal, watches them so you don't have to, and keeps a receipt for everything they did.

Why Clankie

Coding agents are good now. Running several of them is still miserable in three specific ways:

• You can't tell what any of them actually did. Output scrolls away, subagents run invisibly, and at the end you're left diffing blind.
• You burn your attention polling terminals. The agents work in minutes; you're the latency, checking tabs to see who needs you.
• They block while you're away. A worker hits a question at minute four and sits there until you come back.

Clankie attacks all three with one mechanism: everything runs on a visible stage, a lead agent watches the stage so you don't, and your phone collapses the distance between "worker blocked" and "human unblocks it." Your agents keep working when you close the laptop, and you can trust what they did because nothing ever ran where you couldn't see it.

Three rules shape the whole system:

1. If it runs, it's a pane. Every worker is a named, attributable terminal pane (clankie:<slug>) on the bundled clankie-herdr stage. No hidden in-process subagents, ever. The roster is a fact, not a reconstruction.
2. Verify it worked, not just watch it work. The lead harvests each worker, checks the result against the task, and reports with evidence — diffs, checks, transcripts — before anything is called done.
3. Keep the receipt. Per-worker transcripts, session-wide pane recordings, an orchestration graph, and a usage ledger survive the run. When a run ends you can answer: what was asked, who did what, what was verified, what it cost.

The full mental model — the stage, the lead loop, the windows, and the receipt — is in How Clankie Works.

The Ecosystem

flowchart TB
  subgraph host["always-on host"]
    subgraph stage["clankie-herdr — the visible stage"]
      direction TB
      lead["pane: clankie<br/>the lead"]
      w1["pane: clankie:auth-refactor<br/>Claude Code worker"]
      w2["pane: clankie:api-tests<br/>Codex worker"]
    end
    brain["eve brain<br/>channels · schedules · sessions · memory"]
    vox["clankvox<br/>presence plane"]
  end

  phone["Clankies iOS app<br/>garden + terminal window"]
  discord["Discord<br/>text · voice · Go Live"]
  tracker["work tracker<br/>Linear · GitHub Issues · Jira"]

  brain -->|spawn · watch · unblock · harvest| stage
  phone <-->|tailnet relay + lifecycle| brain
  discord <--> brain
  brain <-->|framed IPC| vox
  vox <--> discord
  brain <--> tracker

• Clankie Agent is the lead: the always-on brain (built on eve) that plans work, spawns workers, watches and unblocks them, harvests and verifies results, and reports with receipts.
• clankie-herdr is the bundled terminal stage — Clankie's own terminal multiplexer, shipped with the product, where every worker lives as a named pane you can attach to from any surface.
• Workers do the coding. Claude Code, Codex, OpenCode, or Clankie's own clankie worker CLI — your choice per spawn, on your existing subscriptions or on local models. Clankie stays harness-neutral.
• ClankVox is the presence plane: the Rust media plane that puts Clankie in Discord voice (Opus, E2EE via DAVE, real 20ms pacing) and Go Live.
• Clankie Contract is the shared wire vocabulary: the typed schemas the brain, the relay, and the iOS window all speak.
• The Clankies iOS app (private) is the window: your swarm as a garden of characters, live chat, push when a worker blocks, and a real terminal attach one tap behind the garden.

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

Install

One bootstrap, one bring-up:

npx create-clankie clankie
cd clankie
clankie up

The full guide — prerequisites, installer flags, first-run setup, and pairing the iOS app — is on the Install page.

The default brain route uses an OpenAI API key. Run /setup in the face or /auth openai to store CLANKIE_OPENAI_API_KEY; Codex and Claude subscription OAuth routes are advanced personal-use opt-ins.

Ways to Run It

Clankie is adoptable in layers; each one is a complete product on its own.

Everything runs on your own machine. Clankie is self-hosted by design: private, yours, no telemetry, real history. The brain runs on a Mac today and is portable by design — the phone already treats it as remote. For the fully local mode — lead and workers on one Apple Silicon box, no frontier API — see Local Fleet.

The Repository

The public monorepo (Volpestyle/clankie) carries Clankie's real commit history — not squashed bot snapshots. Honesty is a habit the product itself sells, so the repo practices it too. The iOS app lives in a separate private repo and consumes the public wire contract; everything else — lead, stage, contract, presence plane — is open, and the design decisions behind the shape are recorded as ADRs in the repo.

Clankie is alpha software, built and dogfooded daily by its own swarm.