clanky-agent

---

What Clanky Is

Clanky is a good lead agent. It plans, spawns, watches, unblocks, harvests, verifies, and reports; the coding is done by worker harnesses running in the terminal multiplexer.

• A bundled product: agent + terminal multiplexer + CLI. One install (create-clanky → scripts/install.sh) delivers the clanky CLI, the clanky-agent brain (Eve runtime), and clanky-herdr — Clanky's own tmux. ClankVox (the media plane) and the cold-start supervisor are opt-in install flags.
• Visible by design. Every worker is a named, attributable pane (clanky:<slug>) on Herdr — no hidden background agents. The recorder, per-worker transcripts, and the orchestration graph make runs auditable after the fact: verify it worked, not just watch it work.
• Provider-neutral integrations Work tracking (Linear, GitHub Issues, Jira), design via Figma, and version control via GitHub. Structure is opt-in per integration role: bind a role and its behavior activates, leave it unbound and it stays inert. Switching platforms is cheap by design.
• iOS app is a window The private mobile app is a high-fidelity remote onto the always-on terminal multiplexer — live chat, pane read/steer, terminal attach/mirror, and push over the tailnet relay — plus 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 Clanky is on your desk or across the internet.
• ClankVox is the presence plane. A dedicated native media plane that puts Clanky where the humans are: Discord voice (Opus, E2EE, real 20ms pacing) and Go Live streaming today.

The brain host is portable by design. Today it runs on a Mac — the launchd supervisor and the Seatbelt host-command sandbox are the only macOS couplings; a small Linux box or a hosted deployment are planned shapes. The phone already treats the brain as remote, so hosting is a relocation, not a re-architecture.

This public monorepo contains the open system packages. The native iOS app is a private package in the internal full checkout, released through an internal TestFlight lane and intentionally absent from this public source tree and public Git history.

Ecosystem Map

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

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

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

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

• clanky-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.
• clanky-herdr is the bundled terminal multiplexer. It gives Clanky a persistent terminal workspace where every worker, mirror, and command host stays visible as a named pane. It is Clanky's own Herdr fork, shipped with the product.
• Worker harnesses are the coding agents. Claude Code, Codex, OpenCode, or Clanky's own clanky worker CLI do the actual coding, each in its own clanky:<slug> pane on Herdr.
• ClankVox is the presence plane. It keeps realtime audio/video work out of the Node process and speaks the Discord media protocols Clanky needs.
• clanky-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 multiplexer and consumes the same public contract package from the internal full checkout.

Install

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

npx create-clanky clanky
cd clanky
clanky up

That installs the clanky CLI, the clanky-agent brain, and the clanky-herdr terminal multiplexer; 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

Repository Model

GitHub visibility is repository-wide, so private mobile source cannot live in a public repository. Clanky therefore uses two checkouts:

• Public: Volpestyle/clanky, an iOS-free export that contains the open packages listed above.
• Internal: Volpestyle/clanky-internal, the private full checkout that also contains clanky-ios/ and the TestFlight workflow.

The export process is documented in docs/public-export.md. The architectural decision is recorded in docs/adr/0004-public-mirror-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 clanky-agent && pnpm check && pnpm lint
cd clanky-contract && pnpm typecheck
cd clankvox && cargo test --locked --all-features
cd clanky-ios && pnpm --filter @clanky/mobile check
cd herdr && just ci 'all()'

The public GitHub Actions workflow runs the public package gates. The internal full checkout runs the private iOS fast gate from .github/workflows/ios-testflight.yml; the TestFlight/EAS submission in that workflow is manual.

Public docs publish from the internal checkout into the shared GitHub Pages host at https://volpestyle.github.io/docs/. The current public Pages lane builds ClankVox docs at /docs/clankvox/; clanky-ios/ docs stay private. A future iOS landing page should be a curated public page, not an export of the private app package.

Docs Map

• docs/install.md is the full install and first-run guide.
• clanky-agent/SPEC.md is the authoritative Clanky architecture.
• AGENTS.md is the root package map and contributor orientation.
• docs/adr/0001-clanky-monorepo.md records the monorepo shape.
• docs/adr/0003-herdr-fork-in-monorepo.md records why clanky-herdr lives here.
• docs/adr/0004-public-mirror-private-ios.md records the public/private split and public docs lane.
• docs/adr/0005-clanky-ships-its-stage.md records shipping clanky-herdr as the bundled terminal-multiplexer binary (Proposed).
• docs/local-fleet.md is a proposed design for running the whole swarm — lead agent and every worker — fully local (Proposed).

Status

Clanky is alpha software built around a lead agent that keeps its swarm visible on a bundled terminal multiplexer. The public repository contains the open lead agent, terminal multiplexer, contract, and presence-plane packages; the private iOS package is the mobile window onto the running terminal multiplexer.