---

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.

How Clankie Works

Stage, lead, workers, windows.

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/>native · Linear · GitHub Issues"]

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

• The stage is clankie-herdr, Clankie's own terminal multiplexer, shipped with the product. Every worker, mirror, and command host lives there as a named pane you can attach to from any surface.
• The lead is clankie-agent, an always-on brain built on eve. It plans the work, spawns workers, arms a completion watcher on each spawn, reads and steers panes, answers worker questions, harvests and verifies results, and reports back on the channel you asked from.
• 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: whatever ships next slots in as another performer.
• The windows are where you live. The private Clankies iOS app is a real remote for the swarm — live chat, pane read and steer, full terminal attach, push when a worker blocks or finishes — wrapped in a garden where your clankies show up as characters you can check on from the couch. The real terminal is always one tap behind the garden. Discord text and voice, and your work tracker, are windows too.

The deeper mental model — the lead loop, the receipt, and the trust architecture — is in docs/how-clankie-works.md.

Install

One bootstrap, one bring-up:

Prerequisites are Node 24 or newer, git, Xcode Command Line Tools on macOS, and enough disk for native builds. The installer enables Corepack/pnpm when available and can fetch Rust through rustup; a tailnet is only needed when you pair the iOS app.

npx create-clankie clankie
cd clankie
clankie up

That installs the clankie CLI, the clankie-agent brain, and the clankie-herdr terminal. ClankVox (Discord voice / Go Live) and the always-on cold-start supervisor are opt-in flags. The full guide — prerequisites, installer flags, first-run setup, and pairing the iOS app — is docs/install.md.

The default brain route is the OpenAI API-key path. Run /setup in the face or /auth openai to store CLANKIE_OPENAI_API_KEY; alternatives are local models, xAI, and Gemini. Subscription-auth paths for Codex and Claude are advanced, personal-use opt-ins, not part of the default setup.

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, so moving it to a small Linux box or a hosted deployment is a relocation, not a rewrite. For the fully local mode — lead and workers on one Apple Silicon box, no frontier API — see docs/local-fleet.md.

Agent Protocol

How much Clankie does on its own is configuration, not vibes. Behavior config is wizard-owned: /setup walks it on a fresh install, each piece keeps its own command afterward, and state persists as JSON under ~/.clankie with per-flag CLANKIE_* environment overrides. Secrets stay separate in .env.local.

Delegation profile — who does the work (/profile). Five roles — implementer, designer, scribe, tester, investigator — are assigned to the lead or to workers. Three presets cover the common modes: solo keeps work inline, lead is the default split, and hands-off delegates every role; any other mix is custom. When a role belongs to workers, Clankie spawns named, visible clankie:<slug> panes and runs the spawn/watch/harvest loop over them. The worker harness set (Claude Code, Codex, OpenCode, clankie worker) is itself policy: /harness selects the allowlist profile.

Behavior policies — how work lands (/policies, ADR-0023). Seven flags are labeled by whether Clankie can enforce them at runtime:

Guarantee-class flags have runtime teeth at chokepoints Clankie owns; advisory flags inject guidance into brain turns and worker briefs. Presets direct, autonomous (default), and approval are stored in ~/.clankie/policy-flags.json and can be overridden with CLANKIE_POLICY_*.

ToS-gray paths are off by default (ADR-0025). The default pnpm/installer path uses API keys and bot credentials. Two advanced paths are explicit personal-use opt-ins:

Integration roles — which platforms (/integrations). The provider-neutral protocol binds per role: work tracking to Clankie's native tracker, optionally mirrored to Linear or GitHub Issues; design to Figma; version control to GitHub. Binding a role activates its protocol — tracker-first planning and status, design routing, PR lanes, and review — while unbound roles stay inert.

Packages

Repository Model

This public monorepo carries Clankie's real commit history — not squashed bot snapshots. Honesty is a habit the product itself sells, so the repo practices it too:

• Volpestyle/clankie (public, this repo): the open system packages with their true history. iOS source is removed from every commit.
• Volpestyle/clankies (private): the iOS app, which consumes @volpestyle/clankie-contract through a submodule of this repo and owns its own TestFlight/EAS lane.

The split is recorded in docs/adr/0004-public-real-history-private-ios.md; all monorepo-level decisions live in docs/adr/.

Run Checks

Each package keeps its own toolchain and lockfile; run checks from the package directory:

cd clankie-agent && pnpm check && pnpm lint
cd clankie-contract && pnpm typecheck
cd clankvox && cargo test --locked --all-features
cd herdr && just ci 'all()'

Docs Map

Public docs are hosted at docs.clankie.bot, built from this repo (each package's apps/docs site renders its own markdown through the shared @volpestyle/night-compiler theme, consumed from npm like any other dependency). The docs hosting and theme-packaging decision is recorded in docs/adr/0009-docs-in-monorepo-night-compiler-npm.md.

• docs/how-clankie-works.md — the mental model: stage, lead loop, windows, receipts.
• docs/install.md — install and first run.
• docs/local-fleet.md — the all-local swarm mode.
• docs/adr/ — monorepo architecture decisions.
• clankie-agent/docs/spec.md — the authoritative lead-agent architecture (contributor-depth).
• CONTRIBUTING.md — package boundaries, checks, and PR expectations.
• AGENTS.md — package map and contributor orientation.

Status

Clankie is alpha software, built and dogfooded daily by its own swarm. The public repository contains the open lead agent, terminal, contract, and presence-plane packages; the private iOS package is the mobile window onto the running terminal.