herdr Deep Dive: A Terminal Runtime for Coding Agents

Key points

• What it is: herdr is a Rust-based terminal runtime built for coding agents. It does not wrap or replace agents; it owns their terminals. A single binary (~224,000 lines of Rust, 245 .rs files) runs a background server plus a TUI client built on ratatui and crossterm.
• Core distinction from tmux: tmux is a terminal multiplexer that keeps sessions alive. herdr adds a five-state semantics layer (blocked, working, done, idle, unknown) plus a socket API and an agent skill, so humans and agents can query and orchestrate work programmatically.
• Status detection, dual-track:
• Lifecycle hooks for natively integrated agents (Pi, OMP, Kimi, OpenCode, Kilo, MastraCode).
• Screen-manifest rules (TOML) for Claude Code, Codex, Cursor Agent CLI, Copilot, Devin, Grok, Qwen Code, and others. The detector reads the bottom-of-buffer snapshot, not the visible viewport.
• Detection covers ~20 agents. Unknown UIs fall back to idle rather than risk misclassification, a deliberate safety choice.
• Architecture rule: state is pure data (AppState) decoupled from PTY; rendering is a pure function. This enables detach/reattach, server restarts with layout recovery, and unit-testable detection logic. Enforced in AGENTS.md.
• Control plane: three layers share one socket (Unix socket / Windows named pipe):
• CLI for shell scripts and humans.
• --skill mode (requires HERDR_ENV=1) for agents.
• Raw socket API with JSON Schema export via herdr api schema --json.
• Agents receive HERDR_WORKSPACE_ID / TAB_ID / PANE_ID and can address their own pane with --current.
• Persistence tiers: detach/reattach preserves full state; server restart restores layout and pane history (off by default to avoid leaking secrets); update --handoff experimentally preserves sessions across upgrades. Native resume is supported for 17 agents.
• v0.8.0 performance work: removing the per-pane working spinner, skipping render for hidden panes, and dropping redraws on passive mouse motion cut total CPU by 89–95 percent across multi-client scenarios. The accompanying blog discloses where optimization does not help (50 panes writing heavily: only ~23.6 percent saved), with mechanism counters alongside every CPU number.
• Project facts (as of 2026-08-13): 28,337 stars, 2,009 forks, 156 open issues, 79 releases, 380,624 total downloads. Author Ogulcan (Can) Celik, solo, ~1,179 commits. License switched AGPL-3.0 → Apache-2.0 on 2026-07-22 (commit cd5ea1be), two weeks before the YC F26 announcement on 2026-08-06. DHH contributed 9 PRs starting 2026-08-09 (tab bar, window title sync, pane borders, shortcuts).
• Local-first: no accounts, no telemetry, no cloud relay. Sessions stored as plain JSON under ~/.config/herdr. The only network contact is manifest updates, which can be disabled with [update] manifest_check = false; local manifests always take precedence.
• Plugin model: a plugin is a directory + herdr-plugin.toml + any executable. The entire herdr CLI is the SDK (Bash, JS, Lua, or Rust). ~500+ community plugins exist. Plugins run with the user's full privileges; no sandbox. Review manifests and scripts before installing.
• Windows: beta. v0.8.0 ships an app-level ConPTY runtime; changelog density shows ongoing fixes (Escape handling, Shift+Enter, named pipes).
• Multi-machine orchestration (laptop + VPS + sandbox): stated YC roadmap; not yet implemented.
• Honest limits: screen-manifest detection is a cat-and-mouse game with upstream UIs (e.g., Claude's braille-to-half-circle spinner change in 2.1.228 required a herdr patch); remote manifest delivery is a trust surface even with SHA-256 verification; solo-to-startup transition risk remains.

Source artifacts referenced

• README.md, Cargo.toml, CHANGELOG.md (v0.1.0–v0.8.0), AGENTS.md, skills/herdr/SKILL.md, src/detect/manifests/claude.toml
• Docs: concepts, agents, agent-automation, session-state, socket-api, plugins
• GitHub API: api.github.com/repos/herdrdev/herdr
• herdr.dev blog posts: YC announcement (2026-08-06), "Ten agents, three clients, 95% less CPU" (2026-08-03), "Coding agents are becoming runtimes" (2026-06-10)
• Independent coverage: byteiota.com, runtimewire.com, dev.to (andrew-ooo), chaseai.io