# The Beginner's herdr Handbook: If You Just Started with Claude Code or Codex, Here's How to Put Several AI Agents in One Window

> Readers who just started with Claude Code or Codex kept asking how herdr works. This assumes you've only ever opened a terminal and have no feel for folders or config files yet: five terms in plain words, one install path, three keystrokes for the first session, and a second agent opened from the keyboard alone. Scripting sits at the end and can be skipped. A technical tutorial, not investment content.

Published: 2026-09-10
Locale: en
Tags: herdr, AI agents, terminal, tooling, beginners

TL;DR: herdr is an office for AI agents to live in: close the window and the agents keep working; it knows whether each one is working, waiting on you, or done. After installing, three keystrokes are enough: ctrl+b then c for a new tab, then v to split the screen in two, then q to leave. Type claude or codex in the new half and your second agent is running. Scripting, remote access and config files are at the end for when you need them.


![Baroque oil painting cover: on a dark hillside at night, a shepherd seen from behind holds a single lantern; a dozen sheep glowing from within are scattered below him, city lights far in the distance](/covers/herdr-complete-guide.png)

> *Affairs lie in the four quarters; the pivot lies at the center. The sage holds the pivot, and the four quarters come to serve.*<br/>
> —— Han Feizi, *Yang Quan* (Warring States period; translation mine)

## Who this is for

You've just started with Claude Code or Codex. You've opened that black window and typed a few commands, but "which folder am I in" and "what's a config file" don't mean much yet. Then one day you want two agents at once, one writing code and one checking it, and the windows get messy. This is written for that stage.

I've written two earlier pieces that touch herdr: what I borrowed from its design ([herdr: who is working, who is stuck](/blog/herdr-agent-automation/)) and taking over your PC from a phone ([Tailscale + Herdr + Moshi](/blog/phone-to-pc-agent-tailscale-herdr-moshi/)). Both assumed you already knew your way around. This one doesn't.

## Five words first

These five come up all the way through. Skip this if you know them.

- Terminal: the black window with white text where you type commands. On a Mac it's called Terminal; on Windows people use PowerShell or Windows Terminal. Claude Code and Codex both run inside it.
- Command: a line you type into the terminal and run with Enter. Anything in a grey box in this piece is a command to paste into the terminal.
- Folder and working directory: a folder is where your computer keeps files. The working directory is the folder your terminal is standing in right now. Whichever folder you type `claude` in, that's the only folder it can see.
- Config file: a plain text file a program reads when it starts, to decide colors and keys. You can use herdr without ever touching it, and the beginner part of this piece never does.
- Agent: an AI program that does things on its own, like Claude Code, Codex, or Gemini CLI. It runs in one slot of the terminal, talks to you, and edits files for you.

## What herdr is

One sentence: an office for AI agents to live in.

Think of it this way. You're the boss, each agent is an employee, and each employee has a seat. The office does three things. First, you turn off the lights and go home, and the staff keep working; open the door tomorrow and everything is where it was. Second, you can tell at a glance whether each person is working, waiting for your nod, or finished and idling. Third, you don't have to walk to every seat to talk; you can hand out work and read results from where you sit.

It's open source under Apache 2.0, made by Herdr, Inc., with thirty-odd thousand stars on GitHub.

## Install: one path only

Mac or Linux, open the terminal, paste this line, press Enter:

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

Windows, open PowerShell, paste this line, press Enter:

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

Close the terminal, open it again, and type:

```bash
herdr --version
```

A version number like `0.8.2` means it worked. "Command not found" almost always means the terminal wasn't reopened; close and open it once more.

Other install routes (Homebrew, downloading the zip by hand) are in the advanced section at the end.

## Opening it the first time

In the terminal, type:

```bash
herdr
```

The screen splits into two parts. A narrow strip on the left is the sidebar. The big area on the right is your terminal, same as before; you can type commands as usual.

![Five boxes nested from largest to smallest, from the outermost session down to the innermost agent; the first four layers are grey empty containers, while the innermost agent is solid blue, showing that only it is a living thing.](/figures/herdr-five-layers-nested-en.svg)

herdr organizes things in layers. A building is the quickest way to picture it:

1. The whole building is a session. Typing `herdr` walks you into the default one. Beginners only ever use this one building.
2. Each floor is a workspace. One project per floor.
3. Each room on a floor is a tab.
4. Each seat in a room is a pane. One seat is one terminal.
5. The person sitting in the seat is an agent.

The first four are containers. Only the fifth is alive. At this stage you only need to open rooms and split seats. The rest can wait.

## Three keystrokes to remember

Every herdr key works as "press a leader key, let go, then press a letter." The leader key is ctrl plus b by default. When I write `ctrl+b, c`, it means: hold ctrl and press b, let go, then press c.

| What you want | Keys |
|---|---|
| Open a new room (tab) | ctrl+b, c |
| Split the current seat into left and right | ctrl+b, v |
| Leave the office (agents keep running) | ctrl+b, q |

Just these three for now. Others you'll want soon: ctrl+b then 1 through 9 switches rooms, ctrl+b then x closes the current slot, ctrl+b then ? lists every key.

## A second agent from the keyboard

No scripting needed.

1. In the right-hand area type `claude` (or `codex`). Your first agent is running in this slot.
2. Press ctrl+b, v. The screen splits into left and right, and the cursor jumps to the new half.
3. In the new half type `codex` (or another `claude`). Your second agent is running.

Now look at the sidebar. Two agent names appear, each with a state next to it. There are five states; think of them as what a colleague is doing:

- working: busy.
- blocked: waiting on you. It has a question, or needs you to approve something.
- idle: nothing in hand, waiting for a job.
- done: finished in the background, you haven't looked yet.
- unknown: recognized as an agent, can't tell what it's doing.

![A two-axis chart where the horizontal axis is whether the process is running or has stopped and the vertical axis is whether you have to step in; working sits at the lower left, blocked at the upper right, done at the middle right with an arrow pointing down to idle labelled you looked, and unknown is drawn outside the axes in a dashed box.](/figures/herdr-agent-states-two-axes-en.svg)

The one to watch is blocked. It means a colleague is waiting for you, and until you go over, it stays stopped. The sidebar exists so you don't have to click into every slot; one glance tells you who's waiting.

Two to be careful with: done isn't "closed," only "finished, unseen." And unknown doesn't mean finished; it means unreadable.

## Leaving, then coming back

Press ctrl+b, q. You're back in a plain terminal, but both agents are still running. You can close the terminal window and go to sleep.

Tomorrow, open a terminal and type `herdr`. Both agents are in their seats, the finished work is finished, and whoever was waiting on you is still waiting. This is the single best reason I know to install it: turn off the lights, and people are still inside working late.

![Two panels side by side: on the left your window connects to the server and three running agents; on the right your window is a dashed outline and gone, while the server and the same three agents underneath keep running exactly as before.](/figures/herdr-detach-server-keeps-running-en.svg)

One caution: after a full reboot, the seating layout comes back but the agents don't restart themselves. You type `claude` or `codex` again. So it's not a backup.

That's everything a beginner needs. What follows is advanced; read it when you need it.

## Advanced: commands instead of keys

Once you start wanting "one agent opens another agent on its own," you move to commands. Every herdr action has a matching command, all shaped like `herdr something something`.

Split a slot first, then put the agent in it. The order can't be reversed:

```bash
# 1. Split a new slot to the right of this one
herdr pane split --current --direction right --no-focus
# It prints some text that includes the new slot's ID, like w1:p2

# 2. Start an agent in that slot, named reviewer
herdr agent start reviewer --kind codex --pane w1:p2

# 3. Give it a job and wait
herdr agent prompt reviewer "Review the current diff and report only what needs changing" --wait --timeout 120000

# 4. Read the result back
herdr agent read reviewer --lines 120
```

![Two panels side by side: on the left an agent is started with no slot to hold it and falls through; on the right an empty slot is split first and the agent placed inside, sitting firmly in its container.](/figures/herdr-pane-before-agent-en.svg)

The line I use most means "call me only when it's stuck and needs me":

```bash
herdr agent wait reviewer --until blocked --timeout 120000
```

![Two timelines stacked: the upper one is packed with more than ten tick marks for empty checks and only the last one hits the block, while the lower one stays blank all the way and lights up a single dot at the moment of the block.](/figures/herdr-poll-versus-wait-en.svg)

Reading results has a ceiling: if raising `--lines` still doesn't return the full answer, it's because the part of that agent's screen that scrolled away isn't kept. My workaround is to have it write the full reply to a file and return only the path, then I read the file.

![A long bar of an answer runs past the top edge of a pane; the part inside the frame is readable, the part outside is greyed and marked as gone once scrolled off, while a second path on the right writes the whole answer to a file and reads all of it back.](/figures/herdr-alt-screen-scrollback-ceiling-en.svg)

A few more useful commands, one line each:

- `herdr notification show "Title" --body "text"`: pop a notification.
- `herdr --remote some-machine`: attach to herdr on another machine, provided you can already reach it over SSH.
- `herdr update`: update.
- `herdr --default-config`: print the full default config; copy from here if you want to change keys or colors. `herdr --help` prints the config file's location in its last few lines.
- `herdr --skill`: print the complete operator's manual written for agents. It's more complete than the website, and it matches the version you installed.

## How I use it

The first use is a three-seat adversarial review. I had a design for validating technical indicators, and I'd already had Codex read it and pick holes, three rounds. Then I opened three slots in herdr: one as the designer, one as a statistical adversary, one whose only question was "is this even the question he's asking." Each ran numbers. Two of them caught holes Codex had missed three times. What I took away: a review that only reads can't catch the holes you only see by running the numbers.

The second is taking over the PC from my phone, covered in the earlier piece. herdr's role there is just a room where people keep working after the door closes.

The third happened before I installed it. I read the docs, borrowed the lens "stuck is its own state," pointed it at my own machine, and immediately found a process that had been hanging for fifty-one hours with nobody watching.

Honestly: not everything deserves three slots. I evaluated three tasks and only one was worth it. Opening seats for the other two would only have cost money.

## Where beginners get stuck

- `herdr` says command not found right after install: the terminal wasn't reopened. Close and reopen.
- ctrl+b does nothing: let go before pressing the next key; it's not three keys at once.
- The second agent opened in the same slot: press ctrl+b, v to split first, then type `codex`.
- done never goes away in the sidebar: it only means "you haven't looked." Click in once.
- On Windows, ctrl+b gets swallowed by the terminal: change the leader key to f12 in the config. How: look at the `[keys]` section that `herdr --default-config` prints.
- The website has a page telling you to install an agent-facing manual with npx, but that copy's version may not match yours, and mismatched syntax fails silently. Use `herdr --skill` to print the one for your version.

Two advanced Windows notes, only for people coming in over SSH: a session arriving over SSH can't see shortcuts, so install paths should use the real folder; and Git Bash treats slash-prefixed strings like `/effort` as paths, so prefix commands with `MSYS_NO_PATHCONV=1`.

## Learning resources

- Quick start https://herdr.dev/docs/quick-start/
- Core concepts https://herdr.dev/docs/concepts/
- Configuration and keys https://herdr.dev/docs/configuration/
- Automation with commands https://herdr.dev/docs/agent-automation/
- GitHub https://github.com/herdrdev/herdr

Once installed, `herdr --skill` and `herdr --default-config` are the two best documents, and they're already on your machine.

Questions go in the comments below; a GitHub login is all you need. I read the ones on Vocus too. I'll collect the frequent ones into a follow-up.

## The one thing to take with you

After a month with it, the thing I keep coming back to: a tool like this helps you only if you can first say which agent is waiting on you right now.

Here's what I tried. Tonight, after installing, skip the keys. Open two slots with one agent each, give each a small job, then look only at the sidebar and copy each state onto paper: working, blocked, idle, done, unknown. Do it again tomorrow at the same time. If neither day produces a name next to blocked, your agents don't need an office yet, and there's no rush to move.