How to Run an AI Agent Fleet on Herdr: Setup Guide

Last updated: August 23, 2026

Herdr is a Rust terminal multiplexer built for a specific job: being the runtime your coding agents live on. The first post in this series covered what Herdr is and why it exists. This one is the practical layer - every install command, the config format, three fleet patterns people actually run, and an honest look at what it does not handle yet.

Everything printed here was verified against the official README, the herdr.dev docs (latest version 0.8.2 at time of writing), and each project's own repository. Where something is composed from documented flags rather than quoted verbatim, we say so.

Official Sources#

One naming note: older links point at ogulcancelik/herdr. That repository was moved into the herdrdev organization, and GitHub redirects the old URL automatically.

Quickstart#

Install#

The README lists four supported paths:

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

or Homebrew, mise, or Windows PowerShell:

brew install herdr
mise use -g herdr
powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

It is a single Rust binary - no npm, no Electron shell. If you prefer not to pipe scripts into a shell, the release page publishes standalone binaries, and Homebrew is the most auditable of the four routes.

First run#

Start Herdr from any project directory:

herdr

That launches or attaches to your default background session. Split a pane (ctrl+b, then v for right or - for down), open a new tab (ctrl+b, then c), then run your agent inside a pane:

claude

Herdr detects Claude Code automatically. The same goes for codex, pi, opencode, gemini, cursor, and about sixteen other CLIs - the CLI reference names 22 supported agent kinds in total, from Amp to Qwen Code.

Detach with ctrl+b q or just close your terminal window. The server keeps every process alive; type herdr again to reattach. To stop everything cleanly:

herdr server stop

Config: TOML, opt-in#

Herdr works with no config file. When you want one, it lives at ~/.config/herdr/config.toml. The fastest start is dumping the full defaults and editing from there:

herdr --default-config > ~/.config/herdr/config.toml

Three snippets worth knowing early. Toast notifications when a background agent finishes or blocks:

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

Custom keybindings, tmux-style:

[keys]
prefix = "ctrl+b"
new_tab = "prefix+c"
next_tab = "prefix+n"
split_horizontal = "prefix+minus"

And per-agent sound overrides (the Droid agent is muted by default):

[ui.sound.agents]
claude = "on"

Apply changes to a running server without restarting panes:

herdr server reload-config

The basics: one agent per pane#

The core model is workspace > tab > pane > agent. A workspace is a project container; give each active project its own so the sidebar stays readable. Create one headlessly if you like:

herdr workspace create --cwd ~/project --label api --no-focus

Every agent across every workspace shows its state in the sidebar: working, blocked, done, or idle. One semantic matters for fleet work - done is the same underlying idle state after background work you have not looked at yet, while idle means ready after its tab has been seen in the UI. blocked means Herdr recognized an approval prompt or question.

Two features carry most multi-agent weight:

Git worktrees built in. herdr worktree create checks out a branch under [worktrees] directory, opens it as a grouped workspace, and never deletes branches. On the launch thread, several commenters described running exactly this shape: one worktree per concern - UI fixes, feature A, feature B - one active write-capable agent per worktree, plus cheaper read-only agents doing research in plan mode.

Scriptable orchestration over the socket API. Agents are first-class CLI targets. These flags come straight from the CLI reference (composed into one example):

# split the current pane, right side, half width
herdr pane split --current --direction right --ratio 0.5

# wait until output matches before proceeding
herdr pane wait-output <pane_id> --match "Listening on" --timeout 15000

# prompt an agent by name and block until it finishes
herdr agent prompt reviewer "Review the diff against main" --wait --until done --timeout 600000

Name rules for scripted agents: lowercase, up to 32 characters, matching [a-z][a-z0-9_-]{0,31}. Before scripting anything, wire up the official integrations - herdr integration install claude (or codex, opencode, kimi, and so on) is what upgrades status detection from screen-scraping guesses to native session reporting. Check with herdr integration status.

Pattern 1: the adversarial review rig#

The most interesting community project is overflowy's adversarial review skill: Claude Code writes the code, then spawns GPT as a hostile reviewer in a live Herdr split pane, and finally interrogates every finding against the actual code before relaying a verdict of Confirmed, Disputed, or Unverified.

The setup has four layers, in order:

1. Herdr itself - the skill splits a sibling pane next to your session and drives the reviewer through it.
2. CLIProxyAPI - a local proxy that exposes an Anthropic-compatible endpoint backed by your OpenAI login, which is how stock claude talks to a GPT model. You configure it at ~/.config/cli-proxy-api/config.yml, log in once with cli-proxy-api --config ~/.config/cli-proxy-api/config.yml --codex-login, then leave the server running on port 8317.
3. agent-safehouse, installed with brew install eugene1g/safehouse/agent-safehouse - a macOS kernel-level sandbox. The reviewer runs with --dangerously-skip-permissions, so the sandbox is what confines it to the project directory.
4. A safecodex shell function that wraps claude with proxy env vars, a throwaway config directory, and the sandbox wrapper, so the reviewer starts without touching your real Claude sessions.

Install the skill from inside Claude Code:

/plugin marketplace add overflowy/herdr-adversarial-review
/plugin install adversarial-review@herdr-adversarial-review

Then run /adversarial-review from any session living in a Herdr pane. The repo ships a smoke test worth running first:

curl -s http://localhost:8317/v1/models -H "x-api-key: $CLI_PROXY_API_KEY"
safecodex -p "Say ok"

Why this pattern works in a multiplexer at all: the reviewer is visible in its own pane, so you can watch or steer it, and Herdr's blocked-state detection surfaces its permission prompts instead of hiding them behind a spinner. One commenter on the launch thread described essentially the same producer-critic shape - a no-coding producer agent delegating to sub-agents, with results passed through a file to a separate critic - noting that keeping the producer's context lean made long sessions tractable.

Pattern 2: the watcher/notifier layer#

Once you run more than two or three agents, the bottleneck shifts from driving them to noticing them. A commenter who runs over ten agents on multi-hour workstreams put it bluntly on the launch thread: under plain tmux they occasionally lost agents entirely, only to find one sitting idle waiting for approval days later.

Herdr's answer is the sidebar plus notifications. NotchAgent takes it further: a native macOS app that turns the MacBook notch into a fleet control surface. It is a socket client over Herdr's JSON API - Herdr remains the state authority - showing color-coded status (amber working, coral blocked, green done), opening the actual approval prompt when an agent blocks, and letting you approve, deny, reply, or jump straight back to the owning pane.

brew install --cask ykushch/tap/notchagent

It also tracks remote hosts over SSH - point it at an SSH alias where ssh -o BatchMode=yes workbox 'herdr session list --json' already works non-interactively, and it tunnels the remote socket to a private loopback port. Releases are ad-hoc signed rather than notarized, so expect xattr -dr com.apple.quarantine /Applications/NotchApp.app on first install. For headless setups there is notchctl, a CLI that lists agents, streams status changes, and can resolve prompts programmatically.

You do not need the notch app for a basic version of this layer: the [ui.toast] delivery modes include system and terminal (which works over SSH), and herdr notification show <title> pushes a notification from any script.

Pattern 3: the policy-gated fleet#

Handing ten agents shells means trusting ten agents with rm -rf, cloud credentials, and git push --force. herdr-guard is a cross-agent command policy layer that watches every pane, audits risky commands against a rule set, notifies you, and best-effort interrupts dangerous input:

herdr plugin install StructuPath/herdr-guard

Its shipped policy covers destructive filesystem and Git commands, cloud resource deletion across AWS/GCP/Azure, Kubernetes teardown, database DROP statements, secret-file reads, package publishing, data exfiltration patterns like scp of key directories, and evasion tricks such as stty -echo or base64-to-shell decoding. Rules support three severities - audit, alert, interrupt - with regex or substring matching, and live in $HERDR_PLUGIN_CONFIG_DIR/rules.json.

The more durable half is pre-execution enforcement: an agent harness reports each tool call to guard over a local unix socket before running it and gets back deny, warn, or allow under the same policy. A ready-made Claude Code PreToolUse hook ships in the repo - wired into settings.json, a deny verdict blocks the tool call outright rather than racing it after the fact.

Guard's own README is unusually honest about limits, and it is worth reading in full: pane-watching interrupts are requests, not guarantees; popup panes are blind spots in v1; and a process that can disable the plugin can evade it. Treat it as a policy and audit layer, not a sandbox.

The extension ecosystem today#

All counts pulled live from the GitHub API on August 23, 2026:

A note on HerdrPlus, since its name suggests more than it is: it is not a marketplace or plugin hub. It is one open-source plugin suite from Cloudmanic Labs with two features - Projects, which builds a whole workspace (every tab, split, and startup command) from one TOML file, and Quick Actions, a fuzzy launcher bound to your prefix keys. Both are worth adopting early; the Projects format is the cleanest answer yet to "how do I get my five-pane layout back every morning":

name = "Options Cafe"
description = "The main monorepo"
working_dir = "~/Development/options-cafe/options.cafe"

[[tabs]]
name = "claude"
command = "claude"

[[tabs]]
name = "lazygit"
command = "lazygit"

Plugins all install the same way - herdr plugin install owner/repo[/subdir], with plugin link for local development and plugin action invoke for scripting. Note that Herdr does not curate a central registry; discovery currently happens through HN show threads and the main repo's ecosystem mentions, and plugins run with your privileges - inspect source before installing, as herdr-guard's own security section recommends.

Failure modes and honest gaps#

• Detach is not reboot-proof. Closing the lid or the terminal is safe because the server keeps processes alive. A full server restart loses every running process; Herdr restores layout, cwd, and focus, but panes come back as fresh shells unless an official integration reported a native session reference, in which case conversations resume via claude --resume <id> and equivalents.
• Screen history is off by default, on purpose. Replaying recent pane output after a restart requires enabling experimental pane_history, and the docs warn plainly that saved output can contain secrets and tokens. Treat the config directory accordingly.
• Detection is probabilistic for un-integrated agents. Without an official integration, state comes from reading the terminal buffer. One commenter noted that an agent waiting on a long-running shell command showed as idle when they expected otherwise - the state machine classifies agent prompts, not arbitrary subprocess behavior.
• Git-centric. Worktree tooling assumes Git. Commenters raised Mercurial and Jujutsu support on the launch thread; both remain open discussions.
• No secrets management. Herdr moves env vars around (workspace create --env KEY=VALUE) but stores nothing encrypted. Your credential story stays whatever it already was.
• Live handoff is experimental. herdr update --handoff can migrate live panes across a server replacement, but only for installs managed by Herdr's own updater - Homebrew and mise installs update through their package managers.
• Ecosystem immaturity. The extension table above spans about 360 combined stars outside core Herdr. These are early, fast-moving projects; pin versions and read diffs when updating.

None of these are disqualifying - most are the honest edges of a project whose repository was created in late March 2026 and which already counts roughly 31,800 stars and 2,200 forks. But a fleet plan that assumes crash-proof process state everywhere will eventually lose an afternoon to assumption number one.

FAQ#

Which coding agents does Herdr support?#

Twenty-two named kinds per the CLI reference: pi, claude, codex, gemini, cursor, devin, agy, cline, omp, mastracode, opencode, copilot, kimi, kiro, droid, amp, grok, hermes, kilo, qodercli, qwen, and maki. Anything else runs fine as an ordinary terminal process - you just lose automatic status detection and native session restore.

Is Herdr a tmux replacement?#

It overlaps heavily and deliberately: prefix keybindings, detach/attach, splits, remote attach. Commenters split on the question - some use it as a general-purpose tmux swap and like it; others note it is pitched as an agent runtime first. The differentiators are agent state detection, the sidebar, worktree management, and the socket API.

How do I update Herdr?#

herdr update downloads and installs from your configured channel (herdr channel set preview to move to preview builds). Homebrew, mise, and Nix installs must update through their own package managers.

Where does Herdr keep its config and logs?#

Config at ~/.config/herdr/config.toml on Linux and macOS (%APPDATA%\herdr\config.toml on Windows); logs including herdr.log, herdr-client.log, and herdr-server.log in the same directory, rotated automatically. herdr --default-config prints every setting with defaults.

Will my agents survive closing my laptop?#

Yes - that is the design center. The server owns the PTYs; detach, network loss, and lid-close change nothing. Only stopping the server (herdr server stop, machine shutdown, or crash) ends processes, and that path falls back to snapshot restore plus optional conversation resume.

What happens to agent conversations after a reboot?#

Layout always comes back. Conversations resume only for agents whose integration reported a native session reference - Claude Code needs integration version 6 or newer, Codex version 5, OpenCode version 5, and so on per the compatibility table. Unsupported agents restore as plain shells in their old directories.

How do I install plugins, and are they safe?#

herdr plugin install owner/repo[/subdir] clones, previews the manifest, builds, and registers. Safety is on you: Herdr does not sandbox or review plugins, they run with your user privileges, and the socket API has no plugin-specific read-only ACL in the current release.

Is Herdr free?#

Yes - Apache-2.0 licensed, self-hosted, no accounts. Everything in this article, including every extension listed, is open source under Apache-2.0 or MIT.

This is part two of a four-post series. Start with the deep dive on Herdr's architecture in Herdr deep dive, compare the harness landscape in Herdr vs Pi vs tmux, see where the money is heading in Herdr's YC-era plugin economy, and pair fleet orchestration with scheduled runs via our OpenCode cron automation guide.