Clankie

Run a swarm of coding agents you can actually watch. Clankie is a lead agent that runs your coding agents as visible panes in a bundled terminal, and plugs into the trackers, design tools, and repos you already use.

What it is | Ecosystem | Install | Packages | Repository model | Checks | Docs

---

What Clankie Is

Clankie is the lead agent. It plans the work, spawns coding agents to do it, keeps an eye on them, unblocks them when they stall, and pulls the results back together. The coding itself is done by worker harnesses running as panes in the terminal.

• One bundled product: agent, terminal, and CLI. A single install (create-clankie → scripts/install.sh) gives you the clankie CLI, the clankie-agent brain (Eve runtime), and clankie-herdr, Clankie's own terminal workspace. ClankVox (the media plane) and the cold-start supervisor are opt-in install flags.
• Everything runs in the open. Every worker is a named pane you can attribute (clankie:<slug>). Nothing runs hidden in the background. The recorder, per-worker transcripts, and the orchestration graph let you go back and check what each worker actually did.
• Works with the tools you already use. Work tracking through Linear, GitHub Issues, or Jira; design through Figma; version control through GitHub. Each integration is opt-in by role. Bind the roles you want; the ones you skip stay off. Swapping one platform for another is cheap.
• The iOS app is a real remote for your swarm. The private mobile app is a high-fidelity window onto the always-on terminal: live chat, pane read and steer, terminal attach and mirror, and push over the tailnet relay. It also has a gamified garden view where the swarm shows up as characters you can check on and steer. It works the same whether the machine running Clankie is on your desk or across the internet.
• ClankVox is the presence plane. A native media plane that gets Clankie into Discord voice (Opus, E2EE, real 20ms pacing) and Go Live streaming, so Clankie can show up where the humans already are.

The brain is built to move. Today it runs on a Mac, and the only macOS-specific pieces are the launchd supervisor and the Seatbelt host-command sandbox. A small Linux box or a hosted deployment are planned shapes. The phone already treats the brain as remote, so moving where it runs is a relocation you can do without rewriting anything.

This public monorepo holds the open system packages and carries its real commit history. The iOS app lives in a separate private repo (Volpestyle/clankies), ships through its own TestFlight lane, and is intentionally kept out of this public source tree and Git history.

Ecosystem Map

Lead agent, bundled terminal, workers, presence plane, contract, and window.

flowchart TB
  subgraph public["Public Clankie monorepo"]
    agent["clankie-agent<br/>lead agent brain, command host, relay, face"]
    contract["clankie-contract<br/>zod schemas and TS wire types"]
    vox["clankvox<br/>presence plane: Discord voice and Go Live"]
    herdr["clankie-herdr<br/>bundled terminal workspace"]
  end

  ios["clankies<br/>private iPhone and iPad window"]
  workers["worker harnesses<br/>Claude Code, Codex, OpenCode, clankie worker"]
  discord["Discord<br/>text, voice, Go Live"]

  agent --> contract
  ios --> contract
  agent <-->|pane and session API| herdr
  agent -->|spawn, watch, harvest| workers
  herdr -.->|"hosts as clankie:slug panes"| workers
  agent <-->|gateway, REST, sessions| discord
  agent <-->|framed IPC| vox
  vox <-->|RTP, Opus, DAVE, video| discord
  ios <-->|tailnet lifecycle and relay| agent

Loading

• clankie-agent is the lead. It owns the Eve agent brain, runtime channels, schedules, custom TUI face, relay, supervisor, memory, and the spawn/watch/harvest loop that drives a run.
• clankie-herdr is the bundled terminal. It gives Clankie a persistent terminal workspace where every worker, mirror, and command host stays visible as a named pane. It is Clankie's own Herdr fork, shipped with the product.
• Worker harnesses do the coding. Claude Code, Codex, OpenCode, or Clankie's own clankie worker CLI do the actual coding, each in its own clankie:<slug> pane.
• ClankVox is the presence plane. It keeps realtime audio and video work out of the Node process and speaks the Discord media protocols Clankie needs.
• clankie-contract is the shared vocabulary. It defines the relay, lifecycle, session, presence, pairing, and app-facing schemas.
• The iOS app is the window. It is the private mobile remote onto the running terminal (the clankies repo) and consumes clankie-contract from this monorepo via a submodule.

Install

New-user install is one bootstrap and one bring-up:

npx create-clankie clankie
cd clankie
clankie up

That installs the clankie CLI, the clankie-agent brain, and the clankie-herdr terminal. ClankVox and the supervisor are opt-in flags. For the full guide (private bring-up from an unpublished bootstrapper, running against an existing checkout, install flags, and first-run pairing), see docs/install.md.

Packages

Dir	Role	Start here
clankie-agent/	Eve brain, command host, custom face, relay, supervisor, Discord channels, bundled operator skills	clankie-agent/README.md, clankie-agent/SPEC.md
clankie-contract/	Shared TypeScript wire schemas for relay, lifecycle, sessions, pairing, presence, and tracker shapes	clankie-contract/README.md
clankvox/	Rust realtime media plane for Discord voice, RTP/RTCP, Opus, DAVE, and Go Live streams	clankvox/README.md, clankvox/docs/architecture.md
herdr/	clankie-herdr, the Clankie-owned Herdr fork used as the terminal workspace runtime and pane/session API	herdr/README.md, herdr/AGENTS.md

Repository Model

GitHub visibility is repository-wide, so private mobile source cannot live in a public repository. Clankie therefore splits across repos:

• Volpestyle/clankie (public, this repo): the monorepo with its real commit history. iOS source is removed from every commit.
• Volpestyle/clankies (private): the iOS app. It carries this monorepo as a git submodule to consume @clankie/contract, and owns the TestFlight/EAS lane.
• Volpestyle/clanky-internal (private archive): the pre-split full history, retained untouched as the archive of record.

The architectural decision is recorded in docs/adr/0004-public-real-history-private-ios.md.

Run Checks

Each package keeps its own toolchain and lockfile. Run package checks from the package directory unless a package README says otherwise:

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

The public GitHub Actions workflow runs the public package gates. The iOS fast gate and its manual TestFlight/EAS submission live in the private Volpestyle/clankies repo.

Public docs live in this monorepo, co-located with each package under <package>/apps/docs. They render through the shared @volpestyle/night-compiler theme, consumed from the docs-shell submodule (Volpestyle/docs) rather than a sibling checkout, so a fresh clone builds them with git submodule update --init docs-shell. The Docs workflow publishes to Clankie's own AWS static hosting (S3 + CloudFront) at docs.clankie.bot, one path per package (ClankVox at /clankvox/). iOS docs stay private in the Clankies repo. A future iOS landing page should be a hand-built public page.

Docs Map

• docs/install.md is the full install and first-run guide.
• clankie-agent/SPEC.md is the authoritative Clankie architecture.
• AGENTS.md is the root package map and contributor orientation.
• docs/adr/0001-clankie-monorepo.md records the monorepo shape.
• docs/adr/0008-herdr-fork-as-submodule.md records clankie-herdr as a submodule (supersedes 0003, which vendored it).
• docs/adr/0009-docs-in-monorepo-night-compiler-submodule.md records public docs co-located in the monorepo, the night-compiler theme as the docs-shell submodule, and docs.clankie.bot hosting.
• docs/adr/0004-public-real-history-private-ios.md records the public real-history / private-iOS repo split.
• docs/adr/0005-clankie-ships-its-stage.md records shipping clankie-herdr as the bundled terminal binary (Proposed).
• docs/local-fleet.md is a proposed design for running the whole swarm, lead agent and every worker, fully local (Proposed).

Status

Clankie is alpha software built around a lead agent that keeps its swarm visible in a bundled terminal. 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.