Herding parallel agents on a remote box with herdr

My personal coding setup is a remote Ubuntu box that I connect to via ssh. Claude Code does the work and i scope down access so i can use the --dangerously-skip-permissions flag, with Neovim and lazygit for review and git and yazi when I need to move around the filesystem. tmux and mosh holds things all together so nothing dies when my connection drops, and it’s been good to me. The Mac in front of me is basically a thin client unless i am working on projects with a heavy focus on UI.

The one thing that layer never did well was tell me which agent needed me as i scaled up how many agents I run concurrently. I’ve been trialling herdr as a replacement for tmux, both on the box and locally on the Mac, and it’s good enough that I’m writing it up.

I also have been using a bit of [CMUX] (https://cmux.com/) which is similar but mac specific and has a capability to open a web browser window in the terminal which is nice.

As I’ve leant towards herdr more than CMUX, i wanted to dive in and share my findings so far. Herdr is an agent multiplexer that lives in the terminal: a single Rust binary with no Electron (yey as i save ram and get better performance!) and no hosted control plane or account behind it. It sits in the gap that recently wasn’t working well for me with tmux, having awareness that pane 2 is a blocked Claude session waiting on me, which herdr does well natively.

The problem it solves #

When you run three or four agents in parallel on a remote box, the work that slows you down is figuring out which one needs you right now. In tmux I cycle through windows. One finished ten minutes ago, one is blocked on a question, one is still churning, and the only way to find out is to go and look at each. That checking is the tax you pay for running things in parallel.

herdr puts a sidebar next to your terminal that rolls each workspace up to its most urgent agent state, whether that’s blocked, working, done or idle, so you scan one column and jump to whichever workspace is asking for a decision. That’s the whole pitch, and after a couple of weeks I think it’s the right one.

Installing it #

It’s only a few simple commands to get started:

curl -fsSL https://herdr.dev/install.sh | sh
herdr integration install claude   # session identity + state detection for Claude Code
herdr --version

There’s also brew install herdr (which i personally use) and cargo install herdr and the quick start walks the first session if you want to follow along. The Claude integration is what lets herdr restore your Claude Code sessions natively and read their state without any hooks.

The layout I run #

It maps cleanly onto the worktree-per-task flow I already use. One herdr workspace per git worktree, with three panes inside each that do the jobs I’d otherwise split across separate tools.

┌─ workspace: feat/billing ──────────────┬─ sidebar ──┐
│  pane 0: claude (agent, root pane)      │ ● billing  │  working
│  ─────────────────────────────────     │ ◐ auth     │  blocked
│  pane 1: nvim (review diffs / edits)    │ ○ infra    │  idle
│  ─────────────────────────────────     │ ✓ docs     │  done
│  pane 2: lazygit (live git state)       │            │
└─────────────────────────────────────────┴────────────┘

The agent writes in pane 0, I read and edit the diffs in nvim in pane 1, and lazygit in pane 2 gives me the live git picture when i need. I have one workspace per worktree and the sidebar is effectively showing me per-branch state at a glance.

Walking through the keybindings #

The prefix is ctrl+b, the same as tmux, so the muscle memory carries over.

herdr                              # starts or attaches the background session server

# ctrl+b, shift+n   -> new workspace, name it after the branch

cd ~/code/myrepo-billing           # your worktree dir
claude -w feat/billing             # herdr auto-detects Claude Code

# ctrl+b, v   -> split a pane (or minus)
nvim .                             # pane 1
# ctrl+b, v   -> split again
lazygit                            # pane 2

# ctrl+b, w   -> switch workspaces
# ctrl+b, c   -> new tab within a workspace for another lane

The part that wins me over on a flaky ssh connection is detach and reattach:

# ctrl+b, q   -> detach. server and every agent keep running on the box
herdr          # reattach later from any terminal, or your phone

I run herdr on the box and reattach over ssh and herdr has fallback keepalives by default, so a dropped connection doesn’t take the session with it. There’s also a herdr --remote mode that points a local client at an ssh host and streams the remote TUI back, if you’d rather drive it that way.

Letting the agent drive its own panes #

herdr exposes a socket and a CLI API, so an agent can create panes, run commands, and wait on output by itself, which is something tmux never could do. There’s an official agent skill for it: you install it as a skill named herdr, and it’s guarded behind HERDR_ENV=1, so an agent only acts when it’s genuinely running inside a herdr pane and won’t touch a session it doesn’t own. That’s the hook for letting an orchestrator fan its work out into fresh panes instead of you shuffling terminals by hand, and the agent skill docs cover the setup.

What to keep in mind before you commit #

It’s brand new, v0.1.x, and the project only got going this year. It does what it claims, but you’re betting on something young, so I’ve kept my tmux config around as a fallback while I trial it. Logs live in ~/.config/herdr/ which helps troubleshooting things as herdr is soo new.

The bigger thing to be clear on is what herdr doesn’t do: it’s a multiplexer, and it does not sandbox your agents. If you’re running Claude in any kind of auto-accept mode, the egress allowlist and the least-privilege IAM are still yours to decide how to control on the machine or around each pane’s session depending on what you want to isolate. herdr buys you awareness and persistence, but isolation is a separate job and it’s still on you.

Who it’s for #

If you live in VS Code remote-ssh and you only ever have one or two agents going, you probably don’t need this, since the problem it solves isn’t one you have. But if your setup is remote-box-centric like mine and the thing slowing you down is tracking a herd of agents across worktrees, herdr is the most natural fit I’ve come across. The code is on GitHub if you want to read it first, but it’s worth an afternoon to try.