---
title: herdr
description: herdr, an agent-aware terminal multiplexer, with its keys, theme, plugins and Claude Code hook.
---

herdr is a terminal multiplexer with workspaces, tabs and panes, a sidebar, a prefix key (`ctrl+b`), and a plugin system. It tracks coding agents running in its panes: agent-state colors, next/previous agent keys, and an integration that reports Claude Code sessions to it.

| | |
| --- | --- |
| Source | `dot_config/herdr/config.toml`, `dot_config/herdr/plugins.json`, `dot_config/herdr/plugins/config/`, `dot_config/herdr/empty_dot_plugins.lock`, `dot_config/herdr/kitty.conf`, `dot_config/herdr-nvim/config.toml` |
| Target | `~/.config/herdr/`, `~/.config/herdr-nvim/config.toml` |
| Install | Not in `packages.yaml`; updated by topgrade (`herdr update`) |
| Launch | kitty `super+a` (see [kitty](/terminal/kitty)); Ghostty keys send the same prefix bytes |

## config.toml

`onboarding = false`.

### UI and theme

| Setting | Value |
| --- | --- |
| `ui.pane_borders`, `ui.pane_outer_borders` | `false` (panes separated by gaps only) |
| `ui.prompt_new_tab_name` | `false` |
| `ui.accent` | `#5ea1ff` |
| `ui.status_indicators` | `symbols` |
| `ui.toast.delivery` | `system` |
| `theme.name` | `terminal`, `auto_switch = false` |
| `theme.custom.panel_bg` | `reset` (keeps kitty's translucency and compositor blur) |
| `sidebar_bg` / `active_row_bg` / `selection_bg` | `#16181a` / `#1e2124` / `#3c4048` |
| `accent` / `surface_dim` | `#243348` / `#5ea1ff` (active tab plate matches kitty's tab bar) |
| Agent-state colors | green `#5eff6c`, yellow `#f1ff5e`, red `#ff6e5e`, peach `#ffbd5e`, mauve `#bd5eff` |
| `experimental.kitty_graphics` | `true`; `pane_history = false` |
| `switch_ascii_input_source_in_prefix` | `true` |

These are cyberdream colors.

### Keys

| Key | Action |
| --- | --- |
| `prefix %` | Split vertical |
| `prefix "` | Split horizontal |
| `prefix d` | Detach |
| `prefix s` | Workspace picker |
| `prefix shift+s` | Settings |
| `k` / `j` | Move up / down in the workspace picker (pane up/down in navigate mode unbound) |
| `prefix .` / `prefix ,` | Next / previous agent |
| `prefix j` / `prefix k` | Next / previous workspace |
| `prefix up/down/left/right` | Focus pane |
| `ctrl+h/j/k/l` | `vim-herdr-navigation` left/down/up/right |
| `prefix e` | `chmarax.herdr-nvim.toggle` (nvim sidebar) |
| `prefix o` | `chmarax.herdr-nvim.pick-file` (open file from agent output) |
| `prefix t` | `switchboard.menu` |
| `prefix shift+p` | `switchboard.commands` |
| `prefix shift+l` | `switchboard.git` |
| `prefix shift+k` | `switchboard.projects` |
| `prefix y` | Open `official.browser` plugin in a right split |
| `prefix shift+o` | Open `official.browser` as an overlay |

## Plugins

`plugins.json` is herdr's plugin registry. `.plugins.lock` is created empty. `plugins/config/official.browser/` and `plugins/config/vim-herdr-navigation/` hold placeholder `.keep` files for per-plugin config.

| Plugin | Description (from its manifest) |
| --- | --- |
| `chmarax.herdr-nvim` | Full-height nvim sidebar with agent annotations |
| `herdr-automatic-rename` | Names tabs after the foreground program, adds 1–9 jump numbers |
| `io.github.salemsayed.omaherd` | Tells the Omarchy bar when an agent changes state |
| `official.browser` | Open and inspect real browser pages from herdr |
| `oh-my-opencode-slim` | OpenCode agent orchestration with a herdr adapter |
| `persiyanov.reviewr` | Review agent-written diffs beside the chat |
| `rjyo.window-title-sync` | Syncs the outer terminal title to the focused workspace, tab and agent |
| `switchboard` | Command palette: projects, commands, ports, git, clone, settings |
| `vim-herdr-navigation` | Vim-aware `ctrl+h/j/k/l` pane movement |

[fish](/shell/fish) sources `herdr-automatic-rename`'s `shell/hook.fish` if present.

## herdr-nvim

```toml ~/.config/herdr-nvim/config.toml
[sidebar]
position = "left"
```

The nvim sidebar opens to the left of existing panes (default is right).

## Claude Code integration

`dot_claude/hooks/executable_herdr-agent-state.sh` is installed and managed by herdr (integration id `claude`, version 7) and registered in `dot_claude/settings.json` with the `session` argument. It runs only inside herdr (`HERDR_ENV=1`, `HERDR_SOCKET_PATH`, `HERDR_PANE_ID` set), ignores subagent events, and sends a `pane.report_agent_session` JSON request over herdr's Unix socket with the pane id, Claude session id and transcript path. See [Claude Code](/ai/claude-code).

## herdr/kitty.conf

A legacy kitty config kept in the herdr folder. It runs `tmux new-session -A -s main`, listens on `unix:@mykitty`, includes `current-theme.conf`, maps `super`/`alt` keys to tmux prefix bytes, and has a copy of an older `tmux.conf` appended. The active herdr host is `~/.config/kitty/herdr.conf`.