herdr Guide: Manage All AI Coding Agents in One Terminal (2026)

Running Claude Code and Codex CLI simultaneously, how do you know which one is waiting for your approval? For most developers the answer is: tab-switch one by one and look for a prompt. That works with a single agent, but the mental overhead compounds fast once you're managing three or four agents at the same time.

herdr is an open-source runtime for coding agents. Its core idea is straightforward: keep agents in persistent terminal panes and surface their execution state in one workspace so you can see who is running, waiting, or idle.

TL;DR

• herdr is a Rust-built terminal agent multiplexer that lets you manage Claude Code, Codex, Devin, and more from one window, with real-time blocked/working/done/idle status for each agent
• The key difference from tmux: tmux is a general-purpose terminal multiplexer with no awareness of agent state; herdr is built for the AI agent era, with state awareness as a native feature
• One-line install (brew install herdr) and a familiar model for tmux users; stable v0.8.2 remains pre-1.0

---

How Are You Managing Multiple AI Agents Today?

With several coding agents open at once, every status check requires switching panes and rereading terminal output. A persistent runtime reduces that polling: the processes remain in their panes while herdr rolls their state up into one view.

Parallel multi-agent development is now part of many developers' daily routine, but the management tooling still dates from before AI agents existed. tmux solved session persistence and pane splitting, but it has zero awareness of whether Claude Code is currently waiting for your approval or still thinking.

The practical question is whether you need coding-agent state awareness in addition to pane splitting and session persistence. If you only need the latter two, tmux may already be enough.

If you want to understand the broader design of parallel multi-agent workflows, Claude Code Parallel Workflow Complete Guide covers git worktree isolation strategies in depth.

---

What herdr Is: From tmux to an AI-Native Terminal

herdr (pronounced "herd-er") is a terminal agent multiplexer written in Rust. It keeps each agent in a real terminal pane, then rolls working, blocked, and idle state into one workspace view.

Functionally: herdr = PTY multiplexer + agent state awareness + persistent session + Socket API. Each component has concrete meaning:

PTY multiplexer: Like tmux, you can split panes, create tabs, and detach or reattach while agent processes remain in their terminal panes.

Agent state awareness: This is the core capability tmux lacks. herdr's sidebar shows real-time status for each agent: blocked (waiting for input), working (actively running), done, idle. No tab-switching required.

Persistent session: Background server mode keeps sessions alive when you close your laptop or an SSH connection drops. Supports SSH remote attach so you can monitor agents on remote servers from your local machine.

Socket API: A local Unix socket lets agents call herdr directly to create panes, spawn sub-agents, read output from other agents, and subscribe to state change events. This is what elevates herdr from "viewer" to "orchestrator" (covered in detail below).

Feature	herdr	tmux
Pane splitting / Tab management	Yes	Yes
Session persistence (detach/reattach)	Yes	Yes
SSH remote reattach	Yes	Yes
Agent state tracking (blocked/working/done)	Yes	No
Agent Socket API	Yes	No
AI-agent-native design	Yes	No

One nuance worth noting: the Chinese-language community (moewah blog) frames herdr vs. tmux as "complementary, not a replacement." That's a fair read. herdr includes tmux's multiplexing features, so for tmux veterans it's an upgrade path; for newcomers, starting directly with herdr makes sense.

---

Set Up herdr and Run Your First Claude Code Session in Five Minutes

Step 1: Install (choose one)

On Mac via Homebrew (fastest, official formula confirmed):

brew install herdr

On Linux or any platform via install script:

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

From source (requires a Rust environment):

cargo install herdr

mise and Nix are also supported. See the herdr official install docs for details.

Step 2: Launch herdr

herdr

You'll see an interface similar to tmux, with an agent state sidebar added on the right. Basic keybindings:

• Ctrl+B prefix key (same as tmux)
• Ctrl+B V vertical pane split
• Ctrl+B C new tab
• Ctrl+B Q detach (session keeps running in background)

Step 3: Enable Claude Code Integration

Inside herdr, run:

herdr integration install claude

This installs a hook script for Claude Code so herdr can receive session identity information. Once installed, launching claude in any pane will surface Claude Code's status in the sidebar.

Step 4: Verify

Start Claude Code and give it a task. The herdr sidebar will update to show current state: blocked when waiting for your input, working when actively running.

Important: Opening a tmux session inside a herdr pane disables agent state detection. Run agents directly in herdr panes; don't nest tmux inside herdr.

---

Agent State Tracking: How Does herdr Know Claude Code Is Waiting for You?

herdr uses two distinct state detection mechanisms with different accuracy levels. Which agents you run directly affects the quality of the information you get.

Mechanism 1: Lifecycle hooks or plugins (accurate)

An agent integration reports lifecycle states such as idle, working, and blocked through a hook or plugin. Run herdr integration install <agent> to install the integration for that agent. Explicit lifecycle reporting is more reliable than screen inference.

Mechanism 2: Screen Manifest TOML Rules (automatic but less accurate)

herdr periodically reads a buffer screenshot of the terminal bottom and uses TOML rules to infer state from UI patterns. Zero configuration required, but accuracy is lower than lifecycle hooks. Blocked detection is intentionally strict to avoid misclassifying a running agent as blocked.

Which mechanism does each agent use?

Support Level	Representative Agents
Full lifecycle hooks or plugins (accurate)	Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, MastraCode
Screen manifest only (automatic, less precise)	Claude Code, GitHub Copilot CLI, Codex, Devin CLI, Cursor Agent CLI, Hermes Agent, Droid, Grok CLI, Amp
Partial/experimental	Gemini CLI, Cline

Claude Code currently uses screen manifest only. The hook installed by herdr integration install claude reports session identity (so herdr knows which pane is which Claude Code session), but blocked/working status is still inferred from visual screen analysis.

Screen-manifest detection is deliberately strict about marking a pane blocked. Unknown prompt shapes can initially appear idle until the manifest recognizes them, so timing-sensitive automation should use an authoritative lifecycle integration or explicit state reporting instead of assuming every visible prompt will be detected immediately.

---

herdr vs. tmux vs. Warp vs. Zellij: Which Should You Use?

Before choosing a tool, ask yourself one question: "Do I need to know in real time what each AI agent is doing?"

If the answer is "no, I just need pane splitting and session persistence," tmux is fully sufficient with no reason to switch. If the answer is "yes, I'm running multiple agents and need to know who's waiting for me," no amount of tmux expertise can fix that.

Capability	herdr	tmux	Zellij	Warp
Terminal native (works in CLI environments)	Yes	Yes	Yes	No (GUI app)
Session persistence / Detach-reattach	Yes	Yes	Yes (partial)	Yes
SSH remote reattach	Yes	Yes	No	No
Agent state tracking	Yes	No	No	No
Socket / Agent API	Yes	No	No	No
macOS / Linux support	Yes	Yes	Yes	Yes
Windows support	Yes (plugins preview; not a --remote target)	Yes	Yes	Yes

Recommendation guide:

• Only need terminal multiplexing -- tmux or Zellij is enough, no reason to switch
• Running multiple AI agents and care about state visibility -- herdr
• Prefer GUI, want a native macOS experience -- Warp (but no agent state tracking)
• Already proficient with tmux -- herdr shares similar syntax (same Ctrl+B prefix), so migration cost is low

For broader AI agent framework selection thinking, see AI Agent Framework Comparison: LangGraph vs CrewAI vs Google ADK 2026.

---

Socket API: Let Agents Manage Agents

Most articles about herdr focus on state visibility (seeing blocked/working in the sidebar), but the Socket API is herdr's most powerful and most underrated capability.

herdr exposes a local control interface. On Unix the default socket is ~/.config/herdr/herdr.sock; Windows uses a named pipe. Start with the CLI wrappers for ordinary automation, and use JSON-RPC when you need direct request/response control or long-lived event subscriptions. Supported operations include:

• spawn pane: create a new pane in a specified tab
• spawn agent: launch a specific agent in a new pane
• read pane output: read terminal output from any pane
• subscribe state events: subscribe to agent state change events (triggers when agent A enters done state)

This upgrades herdr from "multi-window monitor" to "agent orchestration layer."

A concrete use case: after Claude Code completes a collect task, it calls the socket API via a hook to tell herdr to start the next Claude Code instance for synthesize. No manual switching required; herdr handles the handoff.

# Create a pane, then start a Codex agent in it
herdr pane split w1:p1 --direction right
herdr agent start reviewer --kind codex --pane w1:p2

To be clear: the Socket API requires basic shell scripting or programming ability. It is not a point-and-click configuration. FossEngineer's hands-on write-up demonstrates specific call patterns, but end-to-end orchestration workflows require assembly on your part. For developers who want to turn herdr into a pipeline trigger, this is the most rewarding area to explore.

---

Limitations and What You Should Know

herdr v0.8.2 is still pre-1.0. These limits directly affect platform and automation choices:

1. Windows: supported as a client, not as a --remote target (affects: cross-platform remote workflows)

Windows supports local persistent sessions, ConPTY panes, and herdr --remote connections to Linux or macOS hosts. A Windows machine cannot currently be the remote target host. Windows plugins remain preview, so test the exact plugin and terminal combination before production use.

2. Pre-1.0 protocol version bumps (affects: production CI/CD)

If an upgrade encounters an incompatible protocol, herdr asks whether to stop the old running server. Stopping it also terminates pane processes, so save work and schedule downtime first. Unix users can separately evaluate the experimental herdr update --handoff, but it is not a general zero-downtime guarantee.

3. Claude Code is screen manifest only (affects: users who rely on precise blocked detection)

As described above, Claude Code's blocked state is inferred visually rather than reported through lifecycle events. An unknown prompt may initially appear idle, so this signal should not be the sole trigger for timing-sensitive automation.

4. tmux inside herdr panes breaks agent detection (affects: users with existing tmux workflows)

Opening a tmux session inside a herdr pane prevents herdr from inspecting its contents. Agents running inside Docker or VMs need HERDR_AGENT=<agent> set as an environment variable.

5. Apache-2.0 license (affects: teams modifying or distributing herdr)

The repository uses the Apache License 2.0. It permits use, modification, distribution, and commercial use, subject to its notice, attribution, and other license conditions. Check the licenses of any bundled dependencies or plugins separately.

---

Conclusion: Who Should Install herdr Today?

herdr solves a concrete problem: visibility chaos when running multiple agents in parallel, with a low installation barrier. But not everyone needs it.

Install it now if:

You're running two or more AI coding agents simultaneously and need to know which one is blocked waiting for your input. Especially relevant if you already run Claude Code + Codex in parallel, or are building an agent pipeline. herdr's state sidebar and Socket API both deliver direct value.

Wait and see if:

You need Windows to act as the remote target host, depend on preview Windows plugins, or plan to place a pre-1.0 tool in a long-lived CI/CD path. Test upgrade, reconnect, and recovery behavior in staging first.

You probably don't need it if:

You're running a single AI agent and tmux's session persistence is already enough. Or if you simply don't care which agent is waiting for you and your workflow is primarily synchronous.

---

Ready to try it? The fastest way is to just install it and experience the sidebar for yourself:

brew install herdr
herdr

Official docs are at herdr.dev/docs. Use the Socket API reference for automation, and run herdr api schema to inspect the protocol bundled with your installed release.