---
type: howto
title: Herdr Setup, Concepts, and My Config Customizations
summary: How to install, drive, and configure Herdr (the mouse-first, agent-aware terminal multiplexer) — core concepts, essential commands, and the specific config.toml customizations I chose with the reasoning behind each.
tags:
  - type/howto
  - tool/herdr
  - domain/dev-tooling
scope: global
last_updated: 2026-07-15
date: 2026-07-15
update_note: experience-driven
source: servers
---

# Herdr Setup, Concepts, and My Config Customizations

Herdr (herdr.dev) is a **terminal workspace manager for AI coding agents** — a tmux-like
multiplexer, but **mouse-first** and **agent-aware**: it detects agents like `claude`/`codex`
running in panes and shows their live state (working / blocked / done). Agent guide:
https://herdr.dev/agent-guide.md · Docs: https://herdr.dev/docs/

## Core Concepts

- **Session** — persistent background server namespace (survives closing the window).
- **Workspace** — one per project directory; owns its tabs/panes.
- **Tab** — a layout inside a workspace.
- **Pane** — a real terminal that survives detach.
- **Agent** — a recognized process shown with a live status in the sidebar.
- **Modes** — terminal mode, prefix mode (`ctrl+b` then a key), navigate mode.

## Install

```bash
# Linux/macOS
curl -fsSL https://herdr.dev/install.sh | sh
# Windows (preview beta)
powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
```
Installs to `~/.local/bin/herdr`. Also available via Homebrew / mise / Nix (see docs).

## Essential Commands

| Do this | Command / keys |
|---|---|
| Launch / attach session (from a project dir) | `herdr` |
| Start an agent in a pane | `claude` (or `codex`, …) — auto-detected |
| Split right / down | `prefix+v` / `prefix+minus`, or right-click menu |
| New tab | `prefix+c` |
| See all keybindings | `prefix+?` |
| Open settings (live theme browser!) | `prefix+s` |
| Detach (leaves agents running) | `prefix+q`, or close the window |
| List detected agents | `herdr agent list` |
| Local/server status | `herdr status` |
| Reload config in running server | `herdr server reload-config` |
| Stop background server | `herdr server stop` |
| Print default config | `herdr --default-config` |
| Attach a workspace to a remote host | `herdr --remote <ssh-target>` |

Config lives at `~/.config/herdr/config.toml` (override via `HERDR_CONFIG_PATH`).
Logs: `~/.config/herdr/herdr.log` (+ `herdr-client.log`, `herdr-server.log`).

**Adoption note:** don't force keybindings before you're used to the tool — it makes adoption
harder. Learn via mouse + right-click menu first, pick up a few bindings organically.
Don't carry tmux muscle memory in — it's a different tool despite the shared `ctrl+b` prefix.

## Themes

There is **no CLI theme preview**. To browse: open Herdr and press **`prefix+s`** (settings) —
built-in themes apply **live and instantly**, no reload. Built-ins: `catppuccin`, `terminal`,
`tokyo-night`, `dracula`, `nord`, `gruvbox`, `one-dark`, `solarized`, `kanagawa`, `rose-pine`,
`vesper`. Persist a choice via `[theme] name = "..."` + `herdr server reload-config`.

My kitty theme (DMS "dank" generator) is **Catppuccin-Macchiato-derived** (`background #24273a` /
`foreground #cad3f5` = Macchiato base/text, warm Material-You peach accent `#f5a97f`). So I set
Herdr's built-in `catppuccin` + a `[ui] accent` override of the peach to echo the terminal look.
`[theme] auto_switch` + `dark_name`/`light_name` can follow the host terminal's light/dark mode.
`[theme.custom]` overrides individual color tokens (hex / named / rgb) on top of a base theme.

## My config.toml Customizations (2026-07-15) — and why

Only behavior/notification settings were changed; keybindings left at defaults on purpose.

| Setting | Value | Why |
|---|---|---|
| `[theme] name` | `"catppuccin"` | Closest built-in to my Catppuccin-Macchiato kitty theme. Browse alternatives live via `prefix+s`. |
| `[ui] accent` | `"#f5a97f"` | My kitty/dank palette's warm peach accent, replacing Herdr's default cyan on borders/nav. Delete to use the theme's own accent. |
| `[ui] show_agent_labels_on_pane_borders` | `true` | I run `claude` AND `codex`, often side by side — labels tell me which agent is in which pane at a glance. |
| `[ui] agent_panel_sort` | `"priority"` | I run several agents across projects; "priority" is an attention queue (blocked/done float to top) — answers "who needs me now?" vs. "spaces" grouping. |
| `[ui.toast] delivery` | `"herdr"` | Long agent runs + I step away. In-app toasts always work, zero deps. `"system"` (real desktop popups) needs a notification daemon (mako/dunst/swaync) — my Hyprland/DMS setup is mid-migration, so avoid until a daemon is confirmed. |
| `[ui.sound] enabled` | `true` | Reliable audible "agent done / needs input" cue while I'm in another window — works regardless of the desktop-notification-daemon situation. |
| `[session] resume_agents_on_restore` | `true` (pinned) | Both my agents support it; after a server restart/reboot their conversations reload instead of starting cold. Default, pinned for clarity. |
| `[remote] manage_ssh_config` | `true` (pinned) | I manage a fleet over SSH; layers keepalives over my `~/.ssh/config` aliases so long remote agent sessions survive NAT/idle drops. `herdr --remote <host>` gives remote panes that survive detach. |

Apply live after editing: `herdr server reload-config` (returns `status: applied` with a
`diagnostics` array — empty means the config is valid).

## Gotchas / notes

- **Notification popups need a daemon on Wayland/Hyprland.** `delivery = "system"` (and often
  `"terminal"`) depend on a running notification daemon. Start with `"herdr"` + sound; only move
  to `"system"` after confirming mako/dunst/swaync is up.
- **Config edits vs dotfiles:** `~/.config/herdr/config.toml` is a real file (NOT a stow symlink
  into `~/.dotfiles`), so it's directly editable — unlike kitty/hypr configs which are dotfile-managed.
- `herdr config reset-keys` backs up config.toml and strips custom keybindings if bindings get tangled.

## Related

- Terminal/desktop context: my Hyprland migration (Fedora 43) and kitty use the DMS "dank"
  Catppuccin-Macchiato palette — the source of the accent color reused above.