Running several Claude Code agents side by side with herdr

Step 1 of 5

Once Claude Code became part of my day, the bottleneck stopped being the agent and became me. One session is refactoring, another is writing tests, a third is waiting for an answer, and I can’t tell which without clicking through terminal tabs. herdr fixed that. It’s a terminal multiplexer, like tmux, with one addition that matters: a sidebar showing whether each agent is working, blocked, idle or done. The project now calls this Herdr TUI, to tell it apart from a newer desktop app; this post is about the terminal one. About 20 minutes.

TL;DR

  • herdr is a terminal multiplexer, like tmux, with a sidebar that shows whether each agent is working, blocked, idle or done.
  • Install the Claude Code integration (herdr integration install claude) so the sidebar shows real state and sessions can resume.
  • Give each agent its own git worktree.
  • Detach with ctrl+b q; run herdr to reattach. After a server restart the conversation comes back, the processes don’t.

You’ll need

  • Linux or macOS (I run it inside WSL Ubuntu, set up as in my WSL setup for Claude Code)
  • Claude Code installed and signed in
  • A repository you’re happy to run two agents on

Install herdr

herdr is a single binary. The install script puts it on your path.

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

Tip: Read any install script before piping it to a shell. It’s a good habit, and it takes a minute.

Turn on the Claude Code integration

herdr detects Claude Code and offers to install its integration. That’s what lets the sidebar show each agent’s real state, and lets herdr restore agent sessions later. You can also run it yourself.

herdr integration install claude

Lay out a workspace per task

I keep one workspace per piece of work, with panes for the agents and one for me. The prefix is ctrl+b, as in tmux: v or - splits a pane, c opens a tab, shift+n creates a workspace and w switches between them.

Give each agent its own working copy

Two agents editing the same files will trip over each other. I give each one its own git worktree, then start Claude Code inside it.

git worktree add ../shop-tests -b ai/tests
git worktree add ../shop-refactor -b ai/refactor

Detach and come back later

Sessions survive closing the terminal or losing an SSH connection. Detach with ctrl+b then q, and run herdr again to reattach. If the herdr server itself restarts, the layout comes back and supported agents, Claude Code included, resume their conversations. That’s on by default. If you ever want it off, this is the setting:

[session]
resume_agents_on_restore = false

Tip: The processes themselves don’t survive a server or machine restart; what comes back is the agent’s conversation history. herdr integration status shows whether your integration is new enough to do it.

My layout

I run herdr 0.9.5 in WSL with the Tokyo Night theme and the Claude Code integration installed. Each project gets its own workspace. My client Adobe Commerce (Magento 2) project usually has four tabs: two Claude Code agents, one shell for bin/magento and one for git. Smaller repositories, like this blog, get a single tab with one agent. The sidebar shows all of them, so I only switch when an agent says it’s waiting for me.

The one plugin I’ve added is herdr-file-viewer, a read-only, git-aware file viewer that opens in a split. I use it to read what an agent changed without leaving herdr. Install it from its GitHub repository (smarzban/herdr-file-viewer) and bind its actions in ~/.config/herdr/config.toml.

herdr keys I use

The prefix is ctrl+b. The last four are my own bindings for the file viewer plugin.

KeysWhat it does
ctrl+b v / -Split the pane side by side / top and bottom
ctrl+b cNew tab
ctrl+b shift+n / wNew workspace / switch workspace
ctrl+b qDetach (run herdr to reattach)
ctrl+b fFile viewer in a split (plugin)
ctrl+b shift+fFile viewer in its own tab (plugin)
ctrl+b dFile viewer at a directory you type, in a split (plugin)
ctrl+b alt+dSame, in a new tab (plugin)

The four plugin keys are custom bindings. Each one maps a key to a plugin action:

[[keys.command]]
key = "prefix+f"
type = "plugin_action"
command = "herdr-file-viewer.open-file-viewer"
description = "open file viewer in split"

Done!

You can now run agents in parallel and see at a glance which one needs you. Next: why Claude Code's LSP tool silently did nothing on Adobe Commerce.

Written by Vishwas Bhatnagar

Technical Architect. Adobe Commerce, marketplaces and AI-assisted engineering.

More about me →

More