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

# 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):

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

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.

8.0 KiB Raw Blame History