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