CONFIGURATION.md

configuration

herdr reads config from:

~/.config/herdr/config.toml

print the full default config with:

herdr --default-config

if a config value is invalid, or two navigate actions use the same keybinding, herdr falls back to a safe default and shows a startup warning in the UI.

onboarding

onboarding = true

option	default	description
onboarding	unset	show first-run notification setup; set false after choosing

notes:

• missing onboarding currently behaves like true
• set onboarding = true to force the setup screen again for testing
• after onboarding, herdr writes onboarding = false plus the chosen sound/toast settings

keybindings

keybindings live under [keys].

supported syntax:

• plain keys: n, x, -, `
• modifiers: ctrl+b, shift+n, alt+x
• special keys: enter, esc, tab, backspace, left, right, up, down
• function keys: f1, f12
• uppercase letters also imply shift: D works like shift+d

notes:

• most reliable bindings are plain keys, ctrl+letter, esc/tab/enter, and function keys
• alt+... and punctuation-with-modifiers may vary depending on terminal/tmux setup
• bindings marked unset in the key reference are supported actions with no default key assigned
• for navigate-mode actions, duplicate keybindings are treated as config errors; later conflicting bindings fall back to defaults

example:

[keys]
prefix = "ctrl+b"
new_workspace = "n"
rename_workspace = "shift+n"
close_workspace = "d"
new_tab = "c"
split_vertical = "v"
split_horizontal = "-"
close_pane = "x"
fullscreen = "f"
resize_mode = "r"
toggle_sidebar = "b"
previous_workspace = "ctrl+alt+["
next_workspace = "ctrl+alt+]"
previous_tab = "alt+["
next_tab = "alt+]"
focus_pane_left = "alt+h"
focus_pane_down = "alt+j"
focus_pane_up = "alt+k"
focus_pane_right = "alt+l"

key reference

key	default	action
prefix	ctrl+b	enter or leave navigate mode
new_workspace	n	create a new workspace
rename_workspace	shift+n	rename selected workspace
close_workspace	d	close selected workspace
previous_workspace	unset	switch to the previous workspace directly from terminal mode
next_workspace	unset	switch to the next workspace directly from terminal mode
new_tab	c	create a new tab
rename_tab	unset	rename the active tab
previous_tab	unset	switch to the previous tab directly from terminal mode
next_tab	unset	switch to the next tab directly from terminal mode
close_tab	unset	close the active tab
focus_pane_left	unset	focus the pane to the left directly from terminal mode
focus_pane_down	unset	focus the pane below directly from terminal mode
focus_pane_up	unset	focus the pane above directly from terminal mode
focus_pane_right	unset	focus the pane to the right directly from terminal mode
split_vertical	v	split pane vertically (side by side)
split_horizontal	-	split pane horizontally (stacked)
close_pane	x	close focused pane
fullscreen	f	toggle focused pane fullscreen
resize_mode	r	enter or leave resize mode
toggle_sidebar	b	collapse or expand the sidebar

theme

herdr ships with 9 built-in color themes. set one in config:

[theme]
name = "tokyo-night"

built-in themes

name	description
catppuccin	soft pastel mocha palette (default)
tokyo-night	blue-purple aesthetic
dracula	purple/pink/green classic
nord	frosty scandinavian blues
gruvbox	warm retro browns/oranges
one-dark	atom's beloved palette
solarized	ethan schoonover's classic
kanagawa	hokusai-inspired
rose-pine	muted, elegant

theme names are flexible: tokyo-night, tokyonight, and tokyo_night all work.

custom overrides

override individual color tokens on top of any base theme:

[theme]
name = "dracula"

[theme.custom]
accent = "#f5c2e7"
red = "rgb(255, 85, 85)"
green = "#a6e3a1"

all tokens are optional — only set what you want to change.

available tokens

token	used for
accent	highlights, active borders, navigation UI
surface0	selected item background
surface1	hover/active backgrounds
surface_dim	active workspace background, separators
overlay0	muted text, secondary info
overlay1	slightly brighter secondary text
text	primary text
subtext0	workspace names, dimmed labels
mauve	git branch names, special labels
green	idle/done states
yellow	busy/running states
red	waiting/needs attention states
blue	unseen notifications
teal	done notification accents
peach	interrupted/warning states

tokens accept the same color formats as accent: hex (#rrggbb), named colors, or rgb(r,g,b).

ui

[ui]
sidebar_width = 26
confirm_close = true
accent = "cyan"

options

option	default	description
sidebar_width	26	base sidebar width before auto-scaling
confirm_close	true	ask before closing a workspace
accent	cyan	highlight and border color

accent accepts:

• named colors like cyan, blue, magenta
• hex like #89b4fa
• rgb like rgb(137,180,250)

toast notifications

[ui.toast]
enabled = false

options

option	default	description
ui.toast.enabled	false	show top-right visual toasts for background agent events

current v1 behavior:

• informational only
• one toast at a time
• top-right placement
• shown for background agent events like needs attention and finished
• suppression is tab-aware: the active tab stays quiet, but background tabs in the same workspace can still notify
• no keyboard action or temporary key semantics

sound

[ui.sound]
enabled = true

[ui.sound.agents]
claude = "default"
droid = "off"

options

option	default	description
ui.sound.enabled	true	enable background agent sounds

per-agent values:

• default
• on
• off

available agent keys:

• pi
• claude
• codex
• gemini
• cursor
• cline
• open_code
• github_copilot
• kimi
• droid
• amp

advanced

[advanced]
allow_nested = false
scrollback_limit_bytes = 10000000

options

option	default	description
advanced.allow_nested	false	allow launching herdr from inside a herdr-managed pane
advanced.scrollback_limit_bytes	10000000	maximum scrollback buffer size in bytes retained per pane terminal

notes:

• by default, herdr blocks nested launches when HERDR_ENV=1 is already present
• this is mainly an escape hatch for debugging or intentionally weird setups
• this matches Ghostty's default scrollback-limit value
• set scrollback_limit_bytes = 0 to disable pane scrollback entirely
• the old advanced.scrollback_lines key is still accepted as a compatibility alias, but it uses the same byte-based value

environment variables

variable	description
HERDR_LOG	log level filter (default: herdr=info)

logs are written to:

~/.config/herdr/herdr.log