herdr/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
• 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
• 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"
split_vertical = "v"
split_horizontal = "-"
close_pane = "x"
fullscreen = "f"
resize_mode = "r"
toggle_sidebar = "b"

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

options

option	default	description
advanced.allow_nested	false	allow launching herdr from inside a herdr-managed pane

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

environment variables

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

logs are written to:

~/.config/herdr/herdr.log