One Open Source Project a Day (No. 174): herdr — The Runtime Your Coding Agents Live On

Introduction

"The runtime your coding agents live on."

This is the 174th article in the "One Open Source Project a Day" series. Today's project is herdr.

Have you run into this situation: you ask Claude Code to handle a large task, close the laptop lid, come back later, and find the entire session is gone — with no idea where the task got to? Or you have several agents running in parallel and have to manually check each terminal to figure out which one is stuck?

This is a systemic problem in AI coding workflows: existing agent tools are powerful, but they lack a persistent "runtime layer" — a foundation that keeps agent sessions alive, tracks agent states, and lets agents coordinate with each other.

herdr is that foundation.

A single Rust binary, no Electron, no extra dependencies. It works like a terminal multiplexer purpose-built for AI agents: sessions never disappear, every agent's status is visible in real time, and agents can coordinate through a Socket API.

34.5k Stars, 659K installs, 909 community plugins, Apache 2.0, YC 2026 backed.

What You Will Learn

• herdr's two agent state detection mechanisms (lifecycle hooks vs screen snapshot scanning)
• The design intent behind the working / blocked / idle three-state model
• The complete Socket API control surface: from splitting panes to cross-agent waiting
• How agent.prompt + agent.wait as an atomic operation prevents race conditions
• The plugin system's local executable + manifest design
• The environment variable injection mechanism

Prerequisites

• Experience with a terminal multiplexer (tmux or similar)
• Familiarity with AI coding agents (Claude Code, Codex, etc.)
• Optional: basic understanding of Unix sockets / inter-process communication

---

Project Background

What It Is

herdr positions itself as "the runtime for AI coding agents" — not a new agent, but the infrastructure that agents run on top of.

Its core claim: "nothing else about your setup changes." Your Claude Code, Codex, and Cursor work exactly as they did. herdr only provides a persistent environment underneath them, plus agent awareness and a coordination API.

From a technical standpoint, herdr is an "agent-native terminal multiplexer":

• Like tmux: manages terminal sessions, panes, and windows
• Added layer: agent status awareness (knows what each agent is doing)
• Socket API for agents to communicate and coordinate with each other
• Plugin system for extending with custom workflows

Author / Team

• Team: herdrdev
• Website: herdr.dev
• Backing: YC 2026
• License: Apache 2.0

Project Stats

• ⭐ GitHub Stars: 34,500+
• 🍴 Forks: 2,500+
• 📄 License: Apache 2.0
• 💻 Primary Language: Rust (single binary)
• 🌐 Website: herdr.dev
• 📦 Install: curl -fsSL https://herdr.dev/install.sh | sh
• 🔌 Community plugins: 909
• 📥 Total installs: 659K

---

Core Features

What Problem It Solves

herdr inserts a persistent scheduling layer between your development environment and your AI agents:

┌─────────────────────────────────────────────────────┐
│                herdr server (background daemon)       │
│                                                     │
│  Workspace 1                                        │
│    Tab: dev                                         │
│      ┌────────────────┬────────────────┐            │
│      │ Pane w1:p1     │ Pane w1:p2     │            │
│      │ Claude Code    │ Codex          │            │
│      │ status: working│ status: blocked│            │
│      └────────────────┴────────────────┘            │
│                                                     │
│  Socket API: ~/.config/herdr/herdr.sock             │
│  Env injection: HERDR_SOCKET_PATH / HERDR_PANE_ID   │
└─────────────────────────────────────────────────────┘
         ↑
    Agents control this layer via CLI or socket

Usage Scenarios

1. Long-running task persistence

   • Start a multi-hour refactoring job in Claude Code, close the laptop, reattach the next morning — the task is still running. No dependency on a terminal window staying open.

2. Multi-agent status monitoring

   • Five agents running in parallel; herdr's status bar shows in real time which ones are working, which are blocked (waiting for user approval), and which are idle. No manual terminal-hopping required.

3. Automated agent coordination

   • Agent A finishes its task, then notifies Agent B to begin the next step via the Socket API. Or an orchestrator agent waits for worker agents to reach done state before collecting results.

4. Remote development machine management

   • SSH into a remote machine and reattach to a running agent session as if you never disconnected.

5. Team workflow standardization

   • Use herdr's Layout API to declaratively define a workspace configuration; one command recreates the entire multi-agent dev environment.

Quick Start

# Install
curl -fsSL https://herdr.dev/install.sh | sh

# macOS (Homebrew)
brew install herdr

# Start the server
herdr start

# Open Claude Code inside herdr
herdr run "claude"

# Check all agent statuses
herdr agent list

# Split pane, run Codex in the new pane
herdr pane split w1:p1 --direction right
herdr pane run w1:p2 "codex"

Core Features

1. Session persistence

herdr is a background daemon that does not depend on any terminal window staying open. Persistence scenarios covered:

• Lid close / sleep and reopen
• Network disconnect and reconnect
• SSH session drop and reattach
• Machine reboot with session restore (session.snapshot mechanism)

# Reattach from any terminal
herdr attach
herdr attach --session my-project

# Attach directly to one agent
herdr agent attach claude-code-main
herdr agent attach claude-code-main --takeover  # claim input control

2. Agent three-state status tracking

Every pane's agent is always in one of three states:

State	Meaning
working	Agent is actively executing a task
blocked	Agent is waiting for user approval or input (permission requests, questions, etc.)
idle	Agent is free, waiting for the next task

State propagates upward: a blocked agent causes its pane, tab, and workspace to all display as blocked.

Two detection mechanisms:

• Lifecycle hooks: agents report state directly via plugins (authoritative source, highest priority)
• Screen snapshot scanning: herdr captures the terminal's bottom-buffer snapshot and matches it against TOML rule sets (fallback for most agents)

blocked detection is deliberately strict — it only triggers when the screen snapshot matches a known approval/permission UI. Unknown prompts default to idle rather than blocked, preventing false positives.

# Diagnose a pane's state detection result
herdr agent explain w1:p1

3. Socket API: complete control surface

herdr exposes a JSON-RPC API over a Unix domain socket (named pipe on Windows). The protocol is newline-delimited JSON:

// Request
{"id":"req_1","method":"ping","params":{}}
// Response
{"id":"req_1","result":{"type":"pong"}}

Socket paths:

• Default: ~/.config/herdr/herdr.sock
• Named session: ~/.config/herdr/sessions/<name>/herdr.sock

herdr automatically injects environment variables into all managed panes:

$HERDR_SOCKET_PATH     # socket address — agents use this to connect
$HERDR_ENV=1           # signals the process is running inside herdr
$HERDR_WORKSPACE_ID    # current workspace ID
$HERDR_TAB_ID          # current tab ID
$HERDR_PANE_ID         # current pane ID (agent knows where it is)

Agents need zero configuration to discover herdr — they just read their environment variables.

4. Cross-agent coordination: atomic prompt + wait

This is one of herdr's most valuable API capabilities. The naive approach — "send text, then wait for output" — has a race condition: if the agent's state changes between the send and the wait, the result is undefined.

herdr's solution is an atomic agent.prompt:

{
  "method": "agent.prompt",
  "params": {
    "pane_id": "w1:p1",
    "text": "Analyze the src/ directory and generate test cases",
    "wait": {
      "until": "done",
      "timeout_ms": 300000
    }
  }
}

The agent.prompt + wait object are submitted in a single request, eliminating the race between "send" and "wait for." If the agent is already in blocked state, the call returns agent_blocked immediately without blindly sending input.

# CLI equivalent
herdr agent wait w1:p1 --until done
herdr agent wait w1:p1 --until blocked --timeout 60000

5. Declarative layout API

Use layout.apply to declare an entire multi-agent workspace structure:

{
  "method": "layout.apply",
  "params": {
    "workspace_id": "w1",
    "tab_label": "dev",
    "root": {
      "type": "split",
      "direction": "right",
      "ratio": 0.65,
      "first": {"type": "pane", "label": "claude", "cwd": "/repo"},
      "second": {
        "type": "split",
        "direction": "bottom",
        "ratio": 0.5,
        "first": {"type": "pane", "label": "codex", "cwd": "/repo"},
        "second": {"type": "pane", "label": "tests",
                   "command": ["sh", "-c", "just test"]}
      }
    }
  }
}

One JSON file defines the entire layout. Version-control it, share it with the team, recreate the full environment with one command.

6. Plugin system

Plugins are "local executables + manifest":

• manifest actions: declare what actions the plugin can perform
• event hooks: subscribe to herdr events (pane.agent_status_changed, pane.output_matched, etc.)
• plugin.pane.open: plugins can open their own UI panes (overlay / popup / split / tab / zoomed)

Plugins are shared through GitHub repositories. The community currently has 909 of them.

---

Deep Dive

Why Rust + Single Binary

herdr deliberately avoids Electron:

Typical desktop AI tool (Electron):
  Node.js runtime + V8 + Chromium + tens of MB of deps
  → slow startup, high memory, can't run in headless environments

herdr (Rust single binary):
  One executable, zero external dependencies
  → millisecond startup, low memory, fully usable over SSH

For a "always-running background server" positioning, a Rust single binary is the correct technical choice.

How Screen Snapshot Detection Works

For agents without native lifecycle hooks, herdr uses screen scanning:

1. Capture the pane's "bottom-buffer snapshot" (not the scrolled viewport)
   ↓
2. Match against the TOML rule library
   Each agent has its own rules file (built-in + remote-updated + local overrides)
   ↓
3. Classify state:
   - Matches known blocked UI → blocked
   - Matches known working pattern → working
   - Anything else → idle (safe fallback)
   ↓
4. Report result to herdr server

Rule files can be updated remotely without a restart. Local ~/.config/herdr/agent-detection/<agent>.toml always takes precedence.

Event Subscription System

Beyond active queries, herdr supports event subscriptions:

{
  "method": "events.subscribe",
  "params": {
    "subscriptions": [
      {
        "type": "pane.agent_status_changed",
        "pane_id": "w1:p1",
        "agent_status": "blocked"
      }
    ]
  }
}

Subscribable event types:

• pane.created / updated / closed / focused / moved / exited
• pane.agent_detected: an agent enters a pane
• pane.agent_status_changed: agent state transitions
• pane.output_matched: pane output matches a specific pattern
• pane.scroll_changed: scroll position changes

This enables the "orchestrator agent" pattern: one agent listens to state events from other agents and sends instructions or collects results at the right moment.

Supported Agent List

herdr natively supports 21 AI coding tools:

Category	Tools
Major	Claude Code, Codex, GitHub Copilot CLI, Cursor Agent CLI, Grok CLI
Emerging	OpenCode, Kilo Code CLI, Amp, Qwen Code, Kimi Code CLI
Specialized	Pi, OMP, Devin CLI, MastraCode
Being tested	Gemini CLI, Cline

The Blocking State Design Philosophy

Most tools that detect agent status err toward false positives — it is safer to show "blocked" than to miss a stuck agent. herdr inverts this: blocked is deliberately strict.

The reasoning: if an agent is incorrectly flagged as blocked, automation scripts might halt unnecessarily, waiting for a state that isn't real. If an agent is incorrectly classified as idle when it's actually waiting for input, the user notices quickly because nothing is happening. The cost of a missed blocked is a human check; the cost of a false blocked is a halted pipeline.

This is the right trade-off for a runtime that automation scripts rely on.

---

Project Links & Resources

Official Resources

• 🌟 GitHub: https://github.com/herdrdev/herdr
• 📚 Docs: herdr.dev/docs
• 🌐 Website: herdr.dev
• 📦 Install: curl -fsSL https://herdr.dev/install.sh | sh
• 🔌 Plugins: 909 community plugins, browsable from within herdr

Related Projects

• tmux — the inspiration behind herdr; traditional terminal multiplexer
• Zellij — another modern Rust-based terminal multiplexer
• Claude Code — one of herdr's most deeply supported agents

---

Summary

Key Takeaways

1. Clear positioning: not a new agent, but a runtime that makes existing agents work better
2. Rust single binary: background daemon, instant startup, zero dependencies — the right fit for "always running"
3. Three-state tracking: working / blocked / idle accurately reflects real agent state; blocked is deliberately strict to prevent false positives in automated pipelines
4. Atomic prompt + wait: solves the classic race condition in multi-agent coordination
5. Declarative layouts: JSON-defined multi-agent workspaces, version-controllable, one-command reproducible

Who This Is For

• Developers running multiple AI coding agents simultaneously: herdr's status panel shows everything at a glance
• Engineers who need long-running agent tasks: persistent sessions, no interruption on lid close
• Teams building agent automation pipelines: Socket API + event subscriptions provide complete orchestration primitives
• Remote development machine users: reattach after SSH drops, experience identical to local

One-Line Verdict

herdr answers a simple question: when AI agents become part of daily development, you need something that can hold them — the way servers need an operating system.

---

Check out PrimeSkills — a curated marketplace of AI agents and skills that have been validated in real-world, enterprise-grade workflows. No fluff, just what actually works.

Find more useful knowledge and interesting products on my Homepage