Installing Clankie

One install delivers the whole product: the clankie CLI, the clankie-agent brain (the lead agent that spawns, watches, and harvests your coding agents), and clankie-herdr, Clankie's bundled terminal, where those workers run as visible panes. The Discord voice / Go Live presence plane (ClankVox) and the always-on cold-start supervisor are opt-in install flags.

There are two ways in: the create-clankie bootstrapper, or running the root installer against a checkout you already have. Both end at the same place: scripts/install.sh builds Herdr, wires the CLI, and records the paths the brain needs.

Prerequisites

Platform: the core install (agent + Herdr + CLI) is portable. The --supervisor launchd daemon is macOS-only today; the brain host itself is portable by design, and the phone already treats the brain as remote, so a Linux box or a hosted deployment are supported shapes for the brain even though the supervisor flag is macOS-specific.

Install

With create-clankie (clone + install)

npx create-clankie clankie
cd clankie
clankie up

create-clankie [dir] clones into dir (default clankie) and runs scripts/install.sh. Pass installer flags after --:

npx create-clankie clankie -- --with-clankvox

See tools/create-clankie/README.md for --repo, --branch, and --use-existing.

Protocol only

If you only want Clankie's lead/worker protocol in an existing Herdr-backed harness, skip the product checkout:

npx create-clankie --protocol

That renders the five protocol skills into the Claude, Agents, and Codex skill roots and prints the repository AGENTS.md block to paste. See Use the Clankie Protocol Without Clankie.

From an existing checkout

If you already cloned the repo, run the installer directly:

git clone <clankie-repo-url> clankie
cd clankie
./scripts/install.sh
clankie up

Or drive the same path through the bootstrapper without re-cloning:

npx --yes ./tools/create-clankie --use-existing .

What the installer does

scripts/install.sh is idempotent: re-running it is safe. In order, it:

1. Checks prerequisites: git, Node >= 24, pnpm (or corepack), macOS Xcode Command Line Tools, free disk, and cargo (installing Rust via rustup if absent). Each missing tool fails with a fix hint.
2. Installs clankie-agent dependencies with pnpm install --frozen-lockfile.
3. Builds the terminal multiplexer: cargo build --release --locked --bin clankie-herdr → herdr/target/release/clankie-herdr. Skipped when the binary already exists (unless --force). The first build can take a few minutes.
4. Records Herdr paths: writes CLANKIE_REPO_DIR and CLANKIE_HERDR_BIN into clankie-agent/.env.local, the durable, gitignored config store every Clankie surface reads.
5. Installs the CLI: symlinks ~/.local/bin/clankie to this checkout's clankie-agent/bin/clankie.ts.
6. Optional extras: builds ClankVox (--with-clankvox) and/or installs the launchd supervisor (--supervisor).

flowchart TD
  A["npx create-clankie<br/>(or ./scripts/install.sh)"] --> B{clone needed?}
  B -->|yes| C["git clone --depth 1"]
  B -->|no| D["use existing checkout"]
  C --> E["scripts/install.sh"]
  D --> E
  E --> F["preflight: Node 24 / pnpm / cargo"]
  F --> G["pnpm install --frozen-lockfile"]
  G --> H["cargo build clankie-herdr"]
  H --> I["write CLANKIE_REPO_DIR + CLANKIE_HERDR_BIN<br/>to clankie-agent/.env.local"]
  I --> J["symlink ~/.local/bin/clankie"]
  J --> K{optional flags}
  K -->|"--with-clankvox"| L["build clankvox binary"]
  K -->|"--supervisor"| M["load launchd daemon"]
  K --> N["clankie up"]
  L --> N
  M --> N

Optional flags

First run

clankie up      # ensures the herdr session and the Clankie brain pane are running
clankie dev     # opens the interactive face (TUI); run it in a terminal or pane

clankie up is idempotent and non-interactive: it brings the terminal session and the headless command host (which owns the eve brain) online, or reports that they already are. clankie dev attaches the face; it needs a real TTY.

Configuration lives in clankie-agent/.env.local. You rarely edit it by hand: the face's slash commands (/model, /auth, /discord-scope, /voice, …) write it for you. Run /setup in the face for the guided setup wizard; choose developer mode when you also want it to run the local toolchain, ClankVox, supervisor, and CLI bootstrap steps. For a noninteractive bootstrap, clankie setup seeds .env.local and mints Clankie's relay/lifecycle tokens. The commented template is clankie-agent/.env.example; the full variable reference is clankie-agent/docs/env-reference.md (pnpm env:reference regenerates it).

The default brain route is OpenAI's API-key provider. Use /setup, or run /auth openai, to write CLANKIE_OPENAI_API_KEY before the first real turn. /model local, /model xai, and /model gemini are also API-key/local paths. /model codex and /model claude are advanced subscription-OAuth paths: they write CLANKIE_ALLOW_SUBSCRIPTION_AUTH=1 and are intended only for personal accounts that accept the provider ToS risk.

Discord uses bot credentials by default. The user-token path for private calls and Go Live is off by default; enable it only with /auth discord --user-token or CLANKIE_DISCORD_CREDENTIAL_KIND=user-token.

Connecting the iOS app is a separate step: see Troubleshooting below and clankie pair.

Updating

From inside the checkout:

clankie update          # git pull --ff-only, pnpm install, refresh the CLI symlink
clankie update --check  # also run pnpm check

Troubleshooting

clankie: command not found. ~/.local/bin is not on your PATH. Add it: export PATH="$HOME/.local/bin:$PATH" (the installer prints this note when it detects the gap). The CLI is a symlink into the checkout, so the checkout must stay in place.

pnpm install --frozen-lockfile fails. The lockfile is frozen so a fresh clone reproduces exactly. A failure means your working tree diverged from the committed lockfile: install from a clean clone, or reconcile the lockfile before re-running.

cargo still not found after the rustup install. The new toolchain is not on this shell's PATH. Run source "$HOME/.cargo/env" (or open a new shell) and re-run the installer.

Node too old. The installer requires Node >= 24 and stops with the version it found. Upgrade (nvm install 24 or nodejs.org) and re-run.

Xcode Command Line Tools missing. On macOS, run xcode-select --install and re-run the installer.

Not enough disk space. Free at least 3 GiB in the checkout volume and re-run. The first Herdr release build can use several GiB of working space.

The brain 503s ("Dev server is unavailable") after editing the repo. Editing watched files or building in the live checkout can trigger an eve dev rebuild that leaves the front returning 503. Restart with clankie up.

clankie pair says "no CLANKIE_RELAY_TOKEN set". The iOS app connects over the relay, which is fail-closed without a bearer token. Run /setup in the face, or run clankie setup from the checkout, then run clankie pair again for the QR (or clankie pair --link).

--supervisor fails off macOS. The supervisor is a launchd daemon and needs launchctl. On other platforms, skip the flag; the core install (agent + Herdr

• CLI) does not depend on it.

ClankVox source not found. --with-clankvox builds from the clankvox package in the checkout. If it is missing, point CLANKIE_CLANKVOX_DIR at the ClankVox source and re-run.

See also

• Root README: ecosystem map and package layout.
• tools/create-clankie/README.md: bootstrapper options.
• Use the Clankie Protocol Without Clankie: protocol-only install and exported skills.
• clankie-agent/docs/env-reference.md: every config variable.