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 the open-source tool that went viral on GitHub Trending in late June 2026 (ranked #1 in Rust, #17 overall daily). Its core idea is straightforward: surface the execution state of every AI agent in a single terminal window so you can see at a glance who's running, who's waiting for you, and who's done. This guide walks through everything from installation to advanced usage, giving you an honest picture of herdr's real capabilities and limitations.

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), low learning curve for tmux users; currently v0.7.1 pre-1.0, Windows --remote support is limited

---

How Are You Managing Multiple AI Agents Today?

I've run scenarios with three Claude Code worktrees simultaneously: one handling collect, one running synthesize, one doing write. On the surface it looks efficient, but the reality is manually tab-switching every few minutes to check who's waiting for approval, who's stuck, and who's still running.

The cost of that tab-switching is higher than it looks. Every switch requires reading terminal output to assess state, then returning to your original work. If an agent just entered a waiting state, you need to respond the moment you switch over; if it's still running, the switch was wasted. Worse, if you close your laptop or lose network, the running session might disappear.

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 cognitive shift herdr offers: not "should I switch from tmux to herdr?" but "do I need to see each agent's execution state in real time?" If the answer is yes, no amount of tmux proficiency can solve that.

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," as in one who manages a herd) is a terminal agent multiplexer written in Rust that accumulated 12.2k stars and 728 forks on GitHub by late June 2026 (confirmed via direct fetch on 2026-07-06), and hit the front page of Hacker News (item #48714802).

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/reattach. Single binary, roughly 10MB, no external dependencies, 85.3% Rust.

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 (accurate)

The agent actively reports its own state to herdr's local socket. Requires running herdr integration install <agent> to install the hook script. When the agent enters blocked, working, done, or other states, the hook notifies herdr immediately. High accuracy.

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 (accurate)	Pi, OMP, Kimi Code CLI, OpenCode, Hermes Agent, Kilo Code CLI
Screen manifest only (automatic, lower accuracy)	Claude Code, GitHub Copilot CLI, Codex, Devin CLI, Cursor Agent CLI, 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.

This means Claude Code's state detection is less accurate than Pi's or OpenCode's. In practice, idle and working are reliably detected, but blocked can take a few seconds to update. That's fine for general monitoring, but if you need millisecond-level event-driven triggers, plan accordingly.

---

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	beta	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 Unix socket (default path ~/.local/share/herdr/herdr.sock). Any program that can call a socket can communicate with herdr via JSON-RPC. 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.

# Send a spawn agent command via socket API (illustrative)
echo '{"jsonrpc":"2.0","method":"pane.spawn_agent","params":{"agent":"claude","args":["--task","synthesize"]},"id":1}' \
  | nc -U ~/.local/share/herdr/herdr.sock

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.7.1 is a pre-1.0 tool. Official documentation on limitations is somewhat scattered; here's a summary ordered by impact:

1. Windows: no --remote support (affects: Windows developers)

The Windows version uses a ConPTY backend that currently lacks --remote support, so SSH remote attach is unavailable. Basic local operations work fine, but it is not recommended for remote management or production use.

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

When herdr upgrades and the protocol version changes, old clients cannot attach to the new server directly. A herdr server restart is required before reattaching. Minimal impact for daily development, but CI/CD environments that detach for long periods before reattaching need a corresponding runbook (e.g., a restart script).

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, not via events. Detection is deliberately strict and can take a few extra seconds to update. Adequate for most scenarios, but not suitable for timing-sensitive automated triggers.

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. AGPL-3.0 license (affects: developers embedding herdr in SaaS products)

How AGPL-3.0 applies to different use cases:

• Personal developer, local use: no restrictions, completely free
• Internal company tooling (employees use it, not offered externally as a service): no practical restrictions
• SaaS scenario (distributing a modified herdr as a service to external users): must open-source modifications, or negotiate a commercial license

The herdr GitHub repo also offers commercial licensing options. If your use case involves commercialization, contact the author directly to confirm.

---

Conclusion: Who Should Install herdr Today?

herdr reaching 12.2k GitHub stars (2026-07-06) is no accident. It 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're on Windows (missing --remote), or you're a DevOps engineer deploying multi-agent setups in production CI/CD environments with concerns about pre-1.0 stability. Try it in a staging environment first, get your protocol-bump runbook sorted, then evaluate.

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. The Socket API details are on the agents page. If you're planning to wire herdr into your own pipeline, that's the most important starting point.