---
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).

## Persistence model & reusable workspaces (researched 2026-07-15, docs dated 2026-07-14)

What survives what ([session-state docs](https://herdr.dev/docs/session-state)):

| Case | Processes live | Layout+cwd | Scrollback | Agent convo |
|---|---|---|---|---|
| Detach / close window | yes | yes | yes | yes |
| `workspace close` | **no — destroys that workspace's herdr state; cannot be reopened** | no | no | only via agent's own `--resume` |
| Server restart | no | yes (session.json snapshot restore) | only with `[experimental] pane_history = true` | yes if native resume integration installed |

- **Never "close" a workspace to pause work — detach instead.** Closing is removal, not suspension. Detach is the intended step-away path; the server keeps everything running.
- **No declarative workspace/layout config exists** (confirmed against full config reference). Reusable per-client/per-project layouts are built imperatively:
  ```bash
  herdr workspace create --cwd PATH --label "Name" [--no-focus]
  herdr tab create --workspace <id> --cwd PATH --label "Tab"
  herdr pane split --pane <id> --direction right --cwd PATH
  herdr pane run <pane_id> "command"
  ```
  Wrap these in a per-client bootstrap script, or package as a herdr plugin action (`[[actions]]` in `herdr-plugin-toml`, bindable to a key) — prior art: `dev-layout-bootstrap` in `ogulcancelik/herdr-plugin-examples`.
- Plugin `[[events]]` hooks exist only for events like `worktree.created` — no general "on workspace open, run X" hook.
- **Agent skill file**: `npx skills add ogulcancelik/herdr --skill herdr -g` installs a SKILL.md letting Claude Code *inside a herdr pane* drive herdr (split panes, run commands, read sibling pane output). Gated on `HERDR_ENV=1`.
- Agent detection can't see through tmux nested inside a pane; sandboxes may need `HERDR_AGENT=<agent>`.

## 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.
