111 lines
6.2 KiB
Markdown
111 lines
6.2 KiB
Markdown
---
|
|
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.
|