Herdr in Practice: The Terminal Multiplexer for Managing Multiple CLI AI Coding Agents

If you have ever run Claude Code and Codex side-by-side in your terminal, you know the pain. You are waiting for one to finish, but you are not sure if it is stuck on a confirmation prompt, thinking, or already done. You have to alt-tab through a mess of windows to check. If your SSH connection drops, one of them is gone for good.

Herdr solves exactly this set of problems.

It is not a new AI model. It does not replace Claude Code or Codex. It is a terminal multiplexer and runtime for AI coding agents that does three things: preserves agent processes, organizes multiple projects, displays agent statuses, and allows agents to call each other.

Here is the one-sentence summary from the official docs:

Herdr does not hire another AI for you; it gives your existing AI employees a desk, a nameplate, a status light, and a control panel.

The project was founded in 2026 (YC Fall 2026). As of August 2026, the GitHub repository has 26.4k stars, and v0.8.0 is the latest stable release. It is written in Rust, ships as a single binary, does not rely on Electron, does not require a user account, and has zero telemetry.

Who Should Install It (And Who Should Not)

Install it if: You regularly run two or more command-line AI coding agents (Claude Code, Codex, OpenCode, etc.) on macOS or Linux, and your tasks usually take longer than ten minutes. You want to close your terminal or lose your SSH connection without killing the agents. For this workflow, Herdr significantly reduces the time you spend switching windows just to check status.

Skip it if: You only run one Claude Code session at a time and finish within ten minutes, or you mainly work inside graphical AI editors like Cursor or Windsurf. In these cases, the Workspace, Tab, and status panel concepts add more cognitive load than they are worth.

Windows Users Beware: The native Windows version is still an experimental Beta (based on ConPTY). Known limitations include: no native herdr --remote, no direct terminal Attach, no Live Handoff, incomplete clipboard image bridging, and unresolved CJK IME cursor positioning. The binary has not passed SmartScreen signing yet either. The official recommendation for Windows users is to SSH into a Linux server and run Herdr there, or test it within WSL first.

The Real Difference Between Herdr and tmux

If you have used tmux, Herdr will feel familiar: a background server retains your terminal sessions so you can detach and reattach anytime. But Herdr adds one big thing that tmux does not do:

It identifies whether a pane is running an AI coding agent and what state that agent is in.

Herdr aggregates the status of each agent:

Status	Meaning
`blocked`	Waiting for input, confirmation, authorization, or a selection
`working`	Actively executing the task
`done`	Finished, but you have not viewed the output yet
`idle`	Finished or waiting, and you have already viewed it
`unknown`	Herdr cannot reliably determine the state

These statuses bubble up from the individual Pane to the Tab, and then to the Workspace. If just one agent in a project is stuck on an authorization screen, the entire Workspace label will show that it needs your attention.

This is Herdr’s core value proposition over tmux. When you go from one coding agent to several, the bottleneck stops being generation speed and becomes your own attention management.

State detection is not 100% accurate, though. Herdr primarily detects agents via foreground processes and terminal screen parsing. Even with integrations installed, status judgments largely rely on screen detection rather than native lifecycle events. New agent versions with updated UI prompts might temporarily show as idle.

If you find a misclassification, run this to debug:

herdr agent explain <agent-name-or-pane-id>

This shows the detected processes, screen-matching rules, evidence, and the final judgment. It is a debugging tool, not something you will use daily.

Installation and First Boot

macOS (Homebrew):

brew install herdr
herdr --version

Linux or macOS (install script):

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

Windows Beta (experimental):

powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
herdr --version

The installer automatically picks the correct binary for your OS and architecture and verifies the SHA-256 checksum.

If you primarily use Claude Code and Codex, install the integrations right away:

herdr integration install claude
herdr integration install codex
herdr integration status

These integrations install a Herdr hook in the agent’s configuration directory. The hook records the native Session ID, which allows Herdr to restore the original conversation after the background server restarts. Uninstalling the integration removes the hook entirely.

Now start Herdr from your project root:

cd ~/Projects/my-project
herdr

On first launch, Herdr creates or connects to the default background Session, then auto-creates one Workspace, one Tab, and one root Pane.

Getting Started: Forget the Keyboard Shortcuts First

Herdr is beginner-friendly in one specific way: you can use your mouse for almost everything right away. No shortcut memorization required.

Once inside, you can:

Type claude in the current pane to start Claude Code.
Right-click the current pane and select “Split Right”.
Type codex in the new pane on the right.
Create another Tab.
Run your test suite or dev server in the new Tab.
Watch the Agents panel on the left update with real-time status changes.

All mouse interactions work out of the box: click to switch panes, tabs, workspaces, or agents; drag dividers to resize; right-click to create tabs or split panes; drag to select and copy text; double-click to copy a word.

Once you are comfortable with the layout, gradually introduce keyboard shortcuts. prefix means: press Ctrl+B, release, then press the next key.

Action	Shortcut
Help	`Ctrl+B`, then `?`
New Tab	`Ctrl+B`, then `C`
Split Right	`Ctrl+B`, then `V`
Split Down	`Ctrl+B`, then `-`
Move between Panes	`Ctrl+B`, then `H/J/K/L`
Next/Previous Tab	`Ctrl+B`, then `N/P`
Workspace navigation	`Ctrl+B`, then `W`
New Workspace	`Ctrl+B`, then `Shift+N`
New Git Worktree	`Ctrl+B`, then `Shift+G`
Toggle sidebar	`Ctrl+B`, then `B`
Zoom current pane	`Ctrl+B`, then `Z`
Copy mode	`Ctrl+B`, then `[`
Detach client	`Ctrl+B`, then `Q`

For a complete list, press Ctrl+B then ? inside Herdr.

The Killer Feature: Your Agents Keep Running When You Close the Terminal

A normal terminal window kills everything inside when closed. Herdr runs these processes inside real terminals owned by a background server. This means you can close your terminal, drop your SSH connection, and later run herdr again to reattach exactly where you left off.

Test it yourself: Run an agent or long-running command in a pane, then press Ctrl+B, Q to detach. The Herdr UI exits, but the background processes keep running. Run herdr again and you are back in your session.

This is useful in several scenarios:

Claude Code running a long refactoring task.
Codex scanning a large codebase.
Background test runners, build processes, or dev servers.
Running agents on remote GPU machines, cloud servers, or Mac Minis.
Switching machines, terminals, or checking status from your phone mid-task.

But there is a hard limit: Herdr resists terminal closures and SSH disconnections, but it cannot keep computing if your machine goes to sleep or shuts down. If the Herdr background server itself stops, or if the host reboots, normal shell processes, tests, and servers will not survive. Herdr can only restore Workspaces, Tabs, Panes, directories, and layouts. It can restore the original conversation session only for agents with official integrations installed.

For multi-hour or multi-day tasks, run Herdr on a remote server or always-on host that does not sleep.

To completely terminate all panes and agents, run:

herdr server stop

This kills all processes owned by the server. Do not run this while critical long-running tasks are active.

Recommended Workspace Layout for Claude Code + Codex

For the Claude Code and Codex combination, here is a pragmatic layout:

Workspace: your-current-project
│
├── Tab: agents
│   ├── Left Pane: Claude Code (implementation)
│   └── Right Pane: Codex (independent review)
│
├── Tab: runtime
│   ├── Left Pane: Dev server
│   └── Right Pane: Tests or type checker
│
└── Tab: review
    ├── git diff
    └── lazygit or another code review tool

Assign fixed roles to avoid confusion:

Role	Task
Claude Code	Reads context, implements the main feature
Codex	Checks the diff, finds edge cases, validates the implementation
Test Pane	Runs tests, linters, and builds continuously
You	Controls task boundaries, handles approvals, reviews the final diff

Do not start a dozen agents at once. A practical concurrency limit is:

1 primary implementation agent.
1 independent reviewer agent.
1 test or server pane.
At most 1 additional research agent.

Beyond that, the time saved on execution gets eaten up by context switching and human coordination.

Git Worktree: Why Multiple Agents Cannot Share One Directory

When multiple agents modify code simultaneously, they cannot safely share the same working directory. Herdr’s built-in Git Worktree workflow is designed to solve exactly this.

Create an isolated Worktree from your main repository:

cd ~/Projects/my-app

herdr worktree create \
  --cwd "$PWD" \
  --branch feat/search \
  --base main \
  --label search

Herdr will:

Create or check out the feat/search branch.
Create an independent checkout in the default Worktree directory.
Create a new Workspace for it.
Group it with the main repository Workspace.

The default Worktree root is ~/.herdr/worktrees. You can change this in the configuration.

Pay attention to the deletion behavior: Closing a Workspace only removes it from the Herdr UI. It does not delete the checkout. Only an explicit herdr worktree remove triggers Git to remove the Worktree, and even then, it does not delete the Git branch—it only removes the Worktree checkout.

The recommended rule: one code-writing task equals one Worktree. Read-only reviewer agents can safely share a Worktree with the implementation agent.

Configuration for macOS Users (with CJK IME Fixes)

The configuration file is located at ~/.config/herdr/config.toml. Here is a complete configuration you can copy and paste directly:

mkdir -p ~/.config/herdr

cat > ~/.config/herdr/config.toml <<'EOF'
onboarding = false

[theme]
name = "catppuccin"
auto_switch = true
light_name = "catppuccin-latte"
dark_name = "catppuccin"

[terminal]
new_cwd = "follow"

[ui]
agent_panel_sort = "priority"
show_agent_labels_on_pane_borders = true

[ui.toast]
delivery = "system"
delay_seconds = 1

[ui.sound]
enabled = true

[session]
resume_agents_on_restore = true

[worktrees]
directory = "~/.herdr/worktrees"

[experimental]
pane_history = false
reveal_hidden_cursor_for_cjk_ime = true
cjk_ime_agents = ["claude", "codex", "pi"]
switch_ascii_input_source_in_prefix = true
EOF

herdr server reload-config

What this configuration does:

Automatically switches themes based on your system’s light/dark mode.
Sorts the agent list by urgency (blocked > done > working).
Displays agent names directly on pane borders (so you do not have to look at the Agents panel to know what is running where).
Uses macOS system notifications (change delivery to terminal if using remote SSH).
Restores original conversations for supported agents after a server restart.
Fixes the CJK IME candidate window positioning issue inside Claude Code and Codex TUI.
Switches to the English input source when entering prefix mode (prevents IME conflicts with shortcuts).
Keeps pane_history = false to avoid writing API keys, tokens, prompts, or logs to disk unnecessarily.

Advanced Workflow: One Agent Orchestrating Another

Herdr is not just a dashboard for humans. It exposes a CLI, a Socket API, and an Agent Skill. This means agents themselves can:

Create Workspaces and Tabs.
Split Panes.
Start another agent.
Send prompts to another agent.
Read output from another pane.
Wait for tests to finish.
Wait for an agent to enter a done or blocked state.
Collect review results from other agents.

Here is a simplified version of the official orchestration pattern. It creates a new pane to the right of the current one, starts a Codex reviewer agent, sends it a task, and reads the result.

Requires jq to be installed locally:

split=$(
  herdr pane split \
    --current \
    --direction right \
    --no-focus
)

review_pane=$(
  printf '%s\n' "$split" |
  jq -r '.result.pane.pane_id'
)

herdr agent start reviewer \
  --kind codex \
  --pane "$review_pane"

herdr agent prompt reviewer \
  "Read-only review of the current Git diff. List issues by severity. Do not modify files." \
  --wait \
  --timeout 600000

herdr agent read reviewer \
  --source recent-unwrapped \
  --lines 160

This script demonstrates Herdr’s four most distinctive capabilities:

split – creates a new workspace location.
start – launches a specific type of agent.
prompt – sends a task and waits for the state to change.
read – fetches the agent’s terminal output.

The automation layer distinguishes between Layout, Pane, and Agent objects. The CLI returns structured JSON, making it suitable for stable shell scripts or for a primary agent to orchestrate helpers.

v0.8.0 can also output the built-in Agent Skill:

herdr --skill

After installing or injecting this Skill, agents like Claude Code and Codex can recognize that they are running inside Herdr via HERDR_ENV=1 and use the Herdr CLI to manage adjacent panes, tests, and helper agents.

Remote Servers and Mobile Access

Three ways to connect:

# Local
herdr

# SSH into the server, then run Herdr
ssh you@server
herdr

# Local Herdr as a thin remote client
herdr --remote workbox

For the third option, configure your ~/.ssh/config:

Host workbox
  HostName server.example.com
  User you
  Port 22

Then run herdr --remote workbox. Your local Herdr connects to the remote server via SSH, prioritizes the matching remote binary version, and interactively prompts for installation if needed. This mode uses your local keyboard shortcuts and bridges local clipboard images to the remote agent.

Mobile usage is even simpler: install any SSH client on your phone, connect to the server running Herdr, run herdr, view the responsive narrow-screen interface, enter any blocked pane to authorize, and detach again. Herdr does not require a separate mobile app or a web dashboard.

Privacy, Security, and Plugins

“No telemetry” does not mean “completely offline.” The official site explicitly states “no account required, no telemetry.” However, by default, Herdr will:

Check for new versions.
Fetch agent detection rule updates from the official site.
Access GitHub when installing plugins.
Access remote servers via SSH when using --remote.

In a strictly air-gapped environment, you can disable these checks:

[update]
version_check = false
manifest_check = false

But note: disabling manifest_check means Herdr will rely only on its built-in rules and may fail to recognize new authorization screens introduced in updated agent versions.

Pane History is disabled by default. Do not enable it casually. When you detach normally, terminal contents remain in the running background server. If you enable [experimental] pane_history = true, Herdr writes recent terminal content to session-history.json. This file might contain API keys, tokens, file paths, prompts, command outputs, and private code. This feature remains off by default for a reason.

The plugin marketplace is not a curated security review. The Herdr plugin marketplace automatically indexes public repositories tagged with the herdr-plugin GitHub topic. It is not an official security audit. Plugins are executable programs that can run build commands, respond to events, open panes, and call the Herdr CLI or Socket API.

Before installing a plugin, at least check:

The repository owner.
Recent commit history.
herdr-plugin.toml.
Build scripts.
Entry points (Shell, JavaScript, or Rust).
Whether it accesses the network.
Whether it reads environment variables or local files.
Whether you can pin it to a specific Git commit or tag.

Do not use --yes for non-interactive installation from untrusted sources.

Herdr is not a security sandbox. It manages terminals but does not restrict agent permissions. Claude Code, Codex, plugins, and regular shell commands all run with your current system user privileges.

Recommended practices for production environments:

Use a dedicated non-admin system account.
One task equals one Git Worktree.
Do not inject production secrets into experimental machines.
Keep agent authorization confirmations enabled.
Use containers or VMs for destructive commands.
Always manually review the Git diff before merging.

Updating, Diagnostics, and Uninstallation

Update via Homebrew:

brew upgrade herdr

Update via the install script:

herdr update

Check your current channel:

herdr channel show

Do not switch to Preview or run an update that requires a server restart while critical long-running tasks are active. If the client and server protocols are incompatible, Herdr will ask you to stop the old server—and stopping the server kills all processes in the panes. The experimental herdr update --handoff attempts to migrate running terminals, but the official docs label it as “Best Effort.”

Common diagnostic commands:

herdr -V
herdr status
herdr integration status
herdr agent list
herdr agent explain <agent-or-pane>
herdr server agent-manifests
herdr server reload-config

Log file locations:

~/.config/herdr/herdr.log
~/.config/herdr/herdr-client.log
~/.config/herdr/herdr-server.log

For verbose debug logs:

HERDR_LOG=herdr=debug herdr

Complete uninstallation on macOS:

First, uninstall integrations to avoid leaving hooks in Claude Code and Codex configs:

herdr integration uninstall claude
herdr integration uninstall codex
herdr server stop

If installed via Homebrew:

brew uninstall herdr

If installed via the install script (binary located at ~/.local/bin/herdr):

rm -f ~/.local/bin/herdr

Back up your configuration (optional):

mv ~/.config/herdr ~/.config/herdr.backup

Do not blindly delete ~/.herdr/worktrees—it may contain uncommitted code.

Quick Operations Summary

Install (Mac): brew install herdr
Install (Linux): curl -fsSL https://herdr.dev/install.sh | sh
Install integrations: herdr integration install claude and codex
Start: cd ~/Projects/my-project && herdr
Detach: Ctrl+B, then Q
Reattach: herdr
Stop server: herdr server stop
Config file: ~/.config/herdr/config.toml
Logs: ~/.config/herdr/herdr*.log
Default Worktree directory: ~/.herdr/worktrees

FAQ

How does Herdr compare to tmux?
Herdr builds on the terminal multiplexer concept but adds AI agent state detection and inter-agent orchestration. If you just need persistent shell sessions, tmux or Zellij is sufficient. If you are running multiple AI coding agents simultaneously, Herdr’s status aggregation and remote persistence save more attention than tmux.

What if Herdr misclassifies my agent’s state?
Run herdr agent explain <agent-name-or-pane-id> to see the detected processes, screen-matching rules, and evidence. If a new agent version changed its UI, Herdr may need an updated detection rule (fetched automatically by default). You can also open an issue on GitHub.

Can agents resume conversations after a restart?
Agents with official integrations installed (e.g., herdr integration install claude) can restore the original conversation session after the Herdr server restarts. Agents without integrations only restore the terminal layout and directory; conversation history is not preserved.

What should I know about running Herdr on a remote server?
Use an always-on host that does not sleep. Set ui.toast.delivery = "terminal" instead of "system" so notifications appear in your terminal session, not on the remote host’s local desktop. The herdr --remote mode requires a correctly configured SSH config.

Are plugins safe to install?
The plugin marketplace is auto-indexed, not audited. Check the repository owner, commit history, herdr-plugin.toml, and entry points before installing. Pin plugins to a specific Git commit or tag. Do not use --yes to bypass interactive confirmation for untrusted sources.

How do I uninstall completely?
First, uninstall integrations: herdr integration uninstall claude && herdr integration uninstall codex. Then herdr server stop. Remove the binary according to your installation method, and optionally back up and delete ~/.config/herdr. Be careful with ~/.herdr/worktrees—it contains code checkouts.

Can I use Herdr on Windows?
The native Windows version is still an experimental Beta with significant limitations. The official recommendation is to SSH into a Linux server and run Herdr there, or test it inside WSL. Not recommended for production use on Windows yet.

Is Herdr free?
As of v0.8.0, the core software is free to install and use. The official repository lists only enterprise contact information and does not currently show any public subscription tiers for individual users.

Herdr Terminal Multiplexer: The Ultimate Guide to Managing Multiple CLI AI Coding Agents