clanky-herdr — Clanky's terminal multiplexer

clanky-herdr is Clanky's bundled terminal multiplexer: the terminal runtime that runs every Clanky worker as a named, visible, steerable pane (clanky:<slug>) you can watch go blocked → working → done, attach to, and drive — from the desk or from the iOS window. It is the component behind Clanky's "visible by design" promise: no hidden background agents, every worker on one terminal multiplexer that the always-on brain and the phone see the same way.

Under the hood it is a patch-stack fork of Herdr, the terminal-based agent runtime by @ogulcancelik. Clanky carries a thin stack of provider-specific mux patches on top of upstream and vendors the fork here in the monorepo so the mux API moves on the same commit timeline as the agent and iOS surfaces that consume it. From the product's seat it is simply Clanky's terminal multiplexer; the fork is how it is maintained, not what it is.

Role in the system

• Clanky is the lead agent; clanky-herdr is the terminal multiplexer its workers run on. Clanky plans, spawns, watches, unblocks, and harvests; the terminal multiplexer gives each worker a real terminal, rolls fleet state up at a glance, and keeps panes alive across detach.
• Product boundary. Clanky product semantics — orchestration edges, transcript policy, pane chat, work tracking, iOS behavior — stay in clanky-agent behind the StageProvider seam. This package carries only terminal-multiplexer mechanics and the fork-side capabilities those semantics need (clanky-agent ADR-0017).
• Decisions. Fork in the monorepo — ADR-0003. Patch-stack fork and its boundary — clanky-agent ADR-0017. Shipping the terminal-multiplexer binary version-locked with the brain (Proposed) — ADR-0005.

The terminal multiplexer engine

clanky-herdr inherits Herdr's runtime, so everything Herdr gives you is what Clanky's terminal multiplexer is built on:

• a real terminal per agent — each worker's own screen, not an app's imitation, so even full-screen TUIs render right.
• agent state at a glance — every pane rolls up to 🔴 blocked, 🟡 working, 🔵 done, or 🟢 idle. Detection works out of the box with process-name matching plus terminal-output heuristics; zero config, no hooks required.
• workspaces, tabs, panes — organize by repo or folder, click, drag, split; mouse-native throughout.
• nothing dies on detach — a background server keeps panes and agents alive; detach and reattach from any terminal, including the phone over the relay.
• runs anywhere — a single ~10MB Rust binary, Linux and macOS (Windows beta), no dependencies, inside the terminal you already use.
• scriptable — a local Unix socket API and CLI that agents drive to create workspaces, split or zoom panes, spawn helpers, read output, and subscribe to state changes instead of polling.

How Clanky drives it

Clanky reaches the terminal multiplexer over that local socket rather than by scraping a screen: it creates panes, spawns workers, reads their output, and subscribes to state changes. The agent-facing mechanics live in the bundled SKILL.md and the socket API docs. Inside Clanky, spawns funnel through the agent's transcript-run seam so every worker lands as a named clanky:<slug> pane on Herdr — see clanky-agent for that layer.

Supported workers

Clanky runs coding harnesses as workers on Herdr; detection classifies each pane's state without per-harness hooks.

Any other agent still works; Herdr runs it as a terminal multiplexer, and custom integrations can report labels and state over the socket API. Detected but not fully tested: gemini cli, cline. Detection tuning is evidence-based — the process and hot-reload loop is in AGENTS.md.

Fork and maintenance

clanky-herdr is maintained as a linear patch stack rebased onto upstream, never a merge fork:

• master mirrors upstream ogulcancelik/herdr and is never committed to directly.
• patch/NN-* branches each carry one reviewable, stacked patch, in NN order.
• fork is the stack tip — the branch built, installed, and run as Clanky's terminal multiplexer.
• upstream is fetch-only.

Rebase, verify, build, install, and push mechanics live in the herdr-fork-rebase host skill; do not reinvent them. Carried patches expose the StageProvider capabilities Clanky needs (request/render serialization, multi-client retained-render gating, pane/session metadata, watch/presence eventing) and are kept thin so they stay rebasable against upstream. Upstreaming a broadly-applicable fix stays useful but is no longer required before Clanky can depend on a fork-carried capability (ADR-0017).

Build

The fork source lives in this package; build the terminal-multiplexer binary from here.

cargo build --release
./target/release/herdr

just test        # unit tests
just check       # formatting, tests, and maintenance checks

The built herdr binary is Clanky's terminal multiplexer. When testing a fresh build from inside an existing mux session, use cargo run with the inherited Herdr socket overrides cleared so it talks to the debug server — see AGENTS.md for that and the full fork-work rules. ADR-0005 proposes shipping this binary version-locked and isolated under Clanky's data root; today it coexists with any user-installed upstream herdr.

Underlying runtime docs

These describe the upstream Herdr runtime this fork builds on and remain the reference for terminal-multiplexer mechanics:

• concepts: server and client, workspaces, tabs, and panes
• session state: detach, restart restore, agent restore, and live handoff
• configuration: keybindings, copy mode, themes, notifications, environment variables
• integrations: native session restore and semantic state per agent
• socket api: socket protocol and CLI reference
• SKILL.md: the reusable agent skill

Agent instructions

If you are an AI agent working on this package, read AGENTS.md before making changes — it is authoritative for fork work — and CONTRIBUTING.md before interacting with the upstream ogulcancelik/herdr repository.

Upstream and license

Herdr is built full-time, in the open, by @ogulcancelik. clanky-herdr tracks it as the rebase source; support upstream development via GitHub Sponsors (see SPONSORS.md) and reach the maintainer at hey@herdr.dev.

Herdr is dual-licensed, and this fork inherits those terms:

1. Open source: GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
2. Commercial: commercial licenses are available for organizations that cannot comply with AGPL.

Distributing or hosting a build of this fork is AGPL distribution and requires keeping the license in sync with the published fork; personal or local use adds no distribution obligation. See ADR-0005 for the shipping posture.