Installing herdr: a basic guide

Goal

By the end you'll have herdr installed and running, with an active workspace on a real project and a coding agent showing up in the sidebar.

herdr is a terminal multiplexer built for working with coding agents (Claude Code, Codex, Cursor, opencode, and others). It keeps sessions alive in the background and shows each agent's state —working, blocked, done— so you don't have to check pane by pane.

Prerequisites

• macOS, Linux, or Windows x86_64 (Windows ARM64 runs under emulation).
• A terminal with permission to install binaries onto your PATH.
• A local project to work on.
• Optional: a coding agent already installed (for example Claude Code) so you can see it detected at the end.

This guide covers herdr v0.8.2.

Steps

1. Install the binary

Pick the method for your system.

macOS / Linux (script):

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

Windows (PowerShell):

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

Windows (CMD, if PowerShell is blocked):

curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del install.cmd

Homebrew:

brew install herdr

mise:

mise use -g herdr

Nix (flake): replace v0.x.y with the latest release tag.

nix profile install github:herdrdev/herdr/v0.x.y

Manual: download the binary for your system from the GitHub releases, make it executable, and add it to your PATH.

2. Verify the install

herdr --version

Expected check: it prints the installed version (for example herdr 0.8.2). If the shell says "command not found", open a new session so it picks up the updated PATH.

3. Start herdr on a project

cd path/to/your/project
herdr

This starts the background server and creates a workspace for that directory. You'll land in the herdr UI with an active terminal pane.

Expected check: you see the herdr sidebar and your shell prompt inside the pane.

4. Launch an agent and see it detected

Inside the pane, start your agent as usual:

claude

herdr detects it automatically and shows its state in the sidebar. Split the pane with prefix+v (split right) or prefix+- (split down); the default prefix is ctrl+b.

5. Detach and reattach

Press prefix+q or close the terminal. Everything keeps running in the background. To come back:

herdr

6. Stop the server

When you're done:

herdr server stop

Expected result

• herdr --version prints the version.
• herdr opens a workspace on your project and survives closing the terminal.
• An agent launched inside a pane shows up with its state in the sidebar.

Troubleshooting

Next step

Tune herdr by editing ~/.config/herdr/config.toml (or %APPDATA%\herdr\config.toml on Windows). See the defaults with herdr --default-config and reload without restarting via herdr server reload-config.