Skip to content

Config reference

Browse every canonical key Herdsman reads from config.toml in a flat, filterable list. For setup guidance and the reasoning behind these options, see Configuration.

Print the full commented default config at any time:

Terminal window
herdsman --default-config

Custom command bindings ([[keys.command]]) are user-defined tables and are not listed per key here; see Custom command keybindings.

General

KeyTypeDefaultDescription
onboardingbooleanunsetShow first-run setup on startup. Missing or true shows onboarding; continuing from onboarding writes onboarding = false.

Server

KeyTypeDefaultDescription
server.allow_unelevated_clientsbooleanfalseWindows only: allow ordinary clients from the same account to control an elevated server and its administrator panes. Applies at server startup and requires a restart; config reload does not change access. The --allow-unelevated-clients startup flag enables sharing even when this setting is false.
server.headless_colsinteger120Virtual terminal width used for layout and newly created panes when no client is attached. Must be greater than zero.
server.headless_rowsinteger40Virtual terminal height used for layout and newly created panes when no client is attached. Must be greater than zero.

Theme

KeyTypeDefaultDescription
theme.namestring"catppuccin"Built-in theme name.
theme.auto_switchbooleanfalseFollow host terminal light/dark appearance and switch between theme names.
theme.dark_namestringunsetTheme name used when `auto_switch` selects a dark appearance.
theme.light_namestringunsetTheme name used when `auto_switch` selects a light appearance.
theme.custom.accentcolorunsetOverride the accent color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.panel_bgcolorunsetOverride the panel_bg color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.sidebar_bgcolorunsetSet the desktop sidebar background without changing other panel surfaces. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.active_row_bgcolorunsetSet the active Space and focused Agent row background without changing separators or scrollbar tracks. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.selection_bgcolorunsetSet the Navigate-mode cursor row background in the sidebar without changing other selection surfaces. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.surface0colorunsetOverride the surface0 color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.surface1colorunsetOverride the surface1 color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.surface_dimcolorunsetOverride the surface_dim color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.overlay0colorunsetOverride the overlay0 color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.overlay1colorunsetOverride the overlay1 color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.textcolorunsetOverride the text color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.subtext0colorunsetOverride the subtext0 color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.mauvecolorunsetOverride the mauve color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.greencolorunsetOverride the green color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.yellowcolorunsetOverride the yellow color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.redcolorunsetOverride the red color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.bluecolorunsetOverride the blue color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.tealcolorunsetOverride the teal color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.peachcolorunsetOverride the peach color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.accentcolorunsetOverride the accent color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.panel_bgcolorunsetOverride the panel_bg color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.sidebar_bgcolorunsetOverride the sidebar_bg color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.active_row_bgcolorunsetOverride the active_row_bg color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.selection_bgcolorunsetOverride the selection_bg color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.surface0colorunsetOverride the surface0 color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.surface1colorunsetOverride the surface1 color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.surface_dimcolorunsetOverride the surface_dim color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.overlay0colorunsetOverride the overlay0 color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.overlay1colorunsetOverride the overlay1 color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.textcolorunsetOverride the text color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.subtext0colorunsetOverride the subtext0 color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.mauvecolorunsetOverride the mauve color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.greencolorunsetOverride the green color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.yellowcolorunsetOverride the yellow color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.redcolorunsetOverride the red color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.bluecolorunsetOverride the blue color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.tealcolorunsetOverride the teal color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.light.peachcolorunsetOverride the peach color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.accentcolorunsetOverride the accent color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.panel_bgcolorunsetOverride the panel_bg color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.sidebar_bgcolorunsetOverride the sidebar_bg color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.active_row_bgcolorunsetOverride the active_row_bg color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.selection_bgcolorunsetOverride the selection_bg color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.surface0colorunsetOverride the surface0 color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.surface1colorunsetOverride the surface1 color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.surface_dimcolorunsetOverride the surface_dim color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.overlay0colorunsetOverride the overlay0 color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.overlay1colorunsetOverride the overlay1 color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.textcolorunsetOverride the text color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.subtext0colorunsetOverride the subtext0 color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.mauvecolorunsetOverride the mauve color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.greencolorunsetOverride the green color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.yellowcolorunsetOverride the yellow color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.redcolorunsetOverride the red color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.bluecolorunsetOverride the blue color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.tealcolorunsetOverride the teal color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.
theme.custom.dark.peachcolorunsetOverride the peach color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

Terminal

KeyTypeDefaultDescription
terminal.default_shellstring""Executable used for new interactive panes. Empty means SHELL, then /bin/sh; on Windows, pwsh.exe when present on PATH, otherwise powershell.exe.
terminal.shell_modeenum"auto"Startup mode for new interactive pane shells. One of auto, login, non_login.
terminal.new_cwdenum"follow"CWD policy for new interactive panes, tabs, and workspaces. One of follow, home, current, path.
terminal.kitty_graphicsbooleantrueRender pane images in Kitty graphics-compatible outer terminals. Applications use the standard Kitty graphics protocol through pane terminal output; the external socket pane-overlay API is no longer available. Set false to disable graphics rendering. Restart the server or reattach the client after changing it. In remote sessions, server configuration controls Kitty graphics parsing while local client configuration controls outer-terminal output.

Updates

KeyTypeDefaultDescription
update.channelenum"stable" ("preview" for Windows preview builds)Update channel used by background version checks and herdsman update. Stable Windows builds default to stable; existing Windows preview installs stay on preview until explicitly switched. Homebrew, mise, and Nix installs ignore the preview channel. One of stable, preview.
update.version_checkbooleantrueCheck remziduzagac.github.io/herdsman for new Herdsman versions in the background.
update.manifest_checkbooleantrueCheck remziduzagac.github.io/herdsman for remote agent-detection manifest updates in the background. Bundled manifests and local overrides still apply.

Keybindings

KeyTypeDefaultDescription
keys.prefixkeybinding"ctrl+b"Prefix key(s) to enter prefix mode (e.g. "ctrl+b", "f12", "esc", or an array to accept several).
keys.helpkeybinding"prefix+?"Open keybinding help.
keys.settingskeybinding"prefix+s"Open settings.
keys.new_workspacekeybinding"prefix+shift+n"Create a new workspace.
keys.new_worktreekeybinding"prefix+shift+g"Create a Git worktree from the selected workspace.
keys.open_worktreekeybindingunsetOpen an existing Git worktree from the selected workspace. Unset by default.
keys.remove_worktreekeybindingunsetDelete the selected managed worktree checkout after confirmation. Unset by default.
keys.rename_workspacekeybinding"prefix+shift+w"Rename the selected workspace.
keys.close_workspacekeybinding"prefix+shift+d"Close the selected workspace.
keys.workspace_pickerkeybinding"prefix+w"Open the workspace navigation surface.
keys.gotokeybinding"prefix+g"Open the session navigator.
keys.navigate_workspace_upkeybinding"up"Move workspace selection up in navigate mode.
keys.navigate_workspace_downkeybinding"down"Move workspace selection down in navigate mode.
keys.navigate_pane_leftkeybinding"h"Focus the pane to the left in navigate mode. Left arrow is always an alias.
keys.navigate_pane_downkeybinding"j"Focus the pane below in navigate mode.
keys.navigate_pane_upkeybinding"k"Focus the pane above in navigate mode.
keys.navigate_pane_rightkeybinding"l"Focus the pane to the right in navigate mode. Right arrow is always an alias.
keys.detachkeybinding"prefix+q"Detach the current client from its Herdsman server.
keys.reload_configkeybinding"prefix+shift+r"Reload config.toml in the running app/server.
keys.open_notification_targetkeybinding"prefix+o"Focus the currently visible notification target.
keys.previous_workspacekeybindingunsetSelect the previous workspace. Unset by default.
keys.next_workspacekeybindingunsetSelect the next workspace. Unset by default.
keys.previous_agentkeybindingunsetFocus the previous agent shown in the agent panel. Unset by default.
keys.next_agentkeybindingunsetFocus the next agent shown in the agent panel. Unset by default.
keys.focus_agentkeybindingunsetFocus an agent by index 1-9. Unset by default.
keys.focus_stackedkeybinding"prefix+alt+1..9"Show and focus member 1-9 of the focused pane's stack.
keys.next_stackedkeybinding"prefix+alt+n"Show the next member of the focused pane's stack, wrapping.
keys.previous_stackedkeybinding"prefix+alt+p"Show the previous member of the focused pane's stack, wrapping.
keys.remote_image_pastestring"ctrl+v"Local-client shortcut that sends a clipboard image to a remote Herdsman session.
keys.new_tabkeybinding"prefix+c"Create a new tab in the active workspace.
keys.rename_tabkeybinding"prefix+shift+t"Rename the active tab.
keys.previous_tabkeybinding"prefix+p"Select the previous tab.
keys.next_tabkeybinding"prefix+n"Select the next tab.
keys.move_tab_previouskeybindingunsetMove the active tab one position toward the front. Unset by default.
keys.move_tab_nextkeybindingunsetMove the active tab one position toward the back. Unset by default.
keys.switch_tabkeybinding"prefix+1..9"Switch to tab 1-9.
keys.switch_workspacekeybindingunsetSwitch to workspace 1-9 from prefix mode. Unset by default.
keys.close_tabkeybinding"prefix+shift+x"Close the active tab.
keys.rename_panekeybinding"prefix+shift+p"Rename the focused pane.
keys.edit_scrollbackkeybinding"prefix+e"Open the focused pane scrollback in $EDITOR.
keys.clear_panekeybindingunsetClear the focused pane screen and scrollback, keeping the current cursor line and its visible soft-wrapped rows. Sends no input to the running program and does nothing on the alternate screen (for example, Vim). Unset by default; for example, clear_pane = "prefix+ctrl+k".
keys.copy_modekeybinding"prefix+["Enter keyboard copy mode for the focused pane.
keys.focus_pane_leftkeybinding"prefix+h"Focus the pane to the left.
keys.focus_pane_downkeybinding"prefix+j"Focus the pane below.
keys.focus_pane_upkeybinding"prefix+k"Focus the pane above.
keys.focus_pane_rightkeybinding"prefix+l"Focus the pane to the right.
keys.swap_pane_leftkeybinding"prefix+shift+h"Swap the focused pane with the pane to the left.
keys.swap_pane_downkeybinding"prefix+shift+j"Swap the focused pane with the pane below.
keys.swap_pane_upkeybinding"prefix+shift+k"Swap the focused pane with the pane above.
keys.swap_pane_rightkeybinding"prefix+shift+l"Swap the focused pane with the pane to the right.
keys.cycle_pane_nextkeybinding"prefix+tab"Cycle to the next pane.
keys.cycle_pane_previouskeybinding"prefix+shift+tab"Cycle to the previous pane.
keys.last_panekeybindingunsetFocus the last focused pane across workspaces and tabs. Unset by default.
keys.split_verticalkeybinding"prefix+v"Split pane vertically (side by side).
keys.split_horizontalkeybinding"prefix+minus"Split pane horizontally (stacked).
keys.stack_panekeybinding"prefix+alt+c"Open a new pane in the focused pane's slot, one visible at a time.
keys.close_stackedkeybinding"prefix+alt+x"Close the focused pane, a stack's visible member; the same action as close_pane.
keys.close_panekeybinding"prefix+x"Close the focused pane.
keys.zoomkeybinding"prefix+z"Toggle zoom for the focused pane. The legacy key name `fullscreen` is accepted as an alias.
keys.resize_modekeybinding"prefix+r"Enter resize mode.
keys.resize_pane_leftkeybindingunsetResize the focused pane toward the left. Unset by default.
keys.resize_pane_downkeybindingunsetResize the focused pane downward. Unset by default.
keys.resize_pane_upkeybindingunsetResize the focused pane upward. Unset by default.
keys.resize_pane_rightkeybindingunsetResize the focused pane toward the right. Unset by default.
keys.equalize_widthskeybinding"prefix+|"Give every column in the focused tab the same width. Heights stay as they are.
keys.equalize_heightskeybinding"prefix+_"Give every row in the focused tab the same height. Widths stay as they are.
keys.presetskeybinding"prefix+t"Open the tab presets list: saved tab layouts to open as new tabs, edit, rename or delete.
keys.toggle_sidebarkeybinding"prefix+b"Toggle sidebar collapse.
keys.toggle_agent_panelkeybinding"prefix+a"Collapse the agents panel to its header, or open it again. Clicking the panel's title does the same.
keys.indexed.tabsstringunsetModifier combo for tab shortcuts 1-9. Unset by default.
keys.indexed.workspacesstringunsetModifier combo for workspace shortcuts 1-9. Unset by default.
keys.indexed.agentsstringunsetModifier combo for agent shortcuts 1-9. Unset by default.

UI and sidebar

KeyTypeDefaultDescription
ui.sidebar_widthinteger26Default expanded sidebar width in columns. Auto-scales based on workspace names.
ui.sidebar_min_widthinteger18Minimum sidebar width (columns) when expanded.
ui.sidebar_max_widthinteger36Maximum sidebar width (columns) when expanded.
ui.sidebar_start_collapsedbooleanfalseStart Herdsman with the sidebar collapsed. Changes take effect on the next launch.
ui.sidebar_collapsed_modeenumcompactCollapsed sidebar presentation. One of compact, hidden.
ui.mobile_width_thresholdinteger64Terminal width at or below which Herdsman uses the mobile single-column layout.
ui.mouse_capturebooleantrueCapture mouse input for Herdsman's mouse UI.
ui.copy_on_selectbooleantrueAutomatically copy text selected by mouse drag or double-click. When disabled, Ctrl+C or a host-forwarded Cmd+C copies and clears the retained selection.
ui.host_cursorenumautoHost cursor policy. One of auto, native, drawn.
ui.right_click_passthrough_modifierstring""Modifier that lets right-click gestures pass through to pane apps. Empty disables it. Accepts ctrl, alt, cmd, super, meta, hyper, or a + separated combination; shift is rejected because many terminals reserve Shift+mouse.
ui.redraw_on_focus_gainedbooleantrueForce a full host-terminal redraw when the outer terminal regains focus.
ui.mouse_scroll_linesinteger3Lines to scroll per mouse wheel notch.
ui.confirm_closebooleantrueAsk for confirmation before closing a workspace.
ui.prompt_new_tab_namebooleantrueAsk for a tab name before creating a new tab.
ui.prompt_new_workspace_namebooleanfalseAsk for a workspace name before interactive TUI creation.
ui.pane_bordersenum"auto"Draw borders around split panes. auto draws them only for split panes, always also frames a lone pane (only while pane_outer_borders is enabled, since every edge of a lone pane is an outer edge), off disables them. Legacy booleans still parse: true maps to auto and false maps to off. One of auto, always, off.
ui.pane_outer_bordersbooleantrueDraw borders along the outside edge of the pane area. Disable with pane gaps disabled for tmux-style internal splitters without an outside frame.
ui.pane_scrollbarsbooleantrueDraw interactive scrollbars beside terminal panes. Disable to reclaim the scrollbar column and keep it out of terminal-native selections.
ui.pane_gapsbooleantrueKeep split panes visually separated instead of sharing divider borders.
ui.show_agent_labels_on_pane_bordersbooleanfalseShow agent labels in split pane borders when no manual pane label is set.
ui.stack_strip_positionenum"bottom"Place the strip naming a stack's members at the top or bottom of its slot. One of top, bottom.
ui.stack_strip_separatorbooleantrueDraw a line between a stack's strip and the content of its visible member.
ui.hide_tab_bar_when_single_tabbooleanfalseHide the tab row when the workspace has one tab.
ui.tab_bar_positionenum"top"Place the desktop tab row above or below the terminal panes. One of top, bottom.
ui.tab_bar_rightarray[]Configure ordered right-aligned tab bar entries. Supported types are zoom, hostname, datetime, text, and command. One of zoom, hostname, datetime, text, command.
ui.tab_bar_right_separatorstring" "Text inserted between visible right-aligned tab bar entries.
ui.window_titlestring"{hostname}: {workspace}"Title Herdsman writes to the terminal it runs in. Tokens: {hostname}, {workspace}, {tab}, {pane}, {terminal_title}. Empty leaves the outer title alone.
ui.agent_panel_sortenum"spaces"Agent sidebar ordering. Saved values are "spaces" or "priority"; "workspaces" is accepted as an alias for "spaces". One of spaces, priority.
ui.agent_panel_start_collapsedbooleanfalseStart each client with the agents panel collapsed to its header, so the spaces list takes the sidebar's height. Click the title or press keys.toggle_agent_panel to open it.
ui.status_indicatorsenum"dots"Choose compact color dots or distinct static symbols for agent states. One of dots, symbols.
ui.sidebar.agents.row_gapinteger0Blank terminal rows between expanded Agent sidebar entries. Set to 1 to restore the previous spacing.
ui.sidebar.agents.rowslist of token rows[["state_icon", "machine", "workspace", "tab"], ["agent"]]Default expanded Agent sidebar layout. Entries may be token strings or inline { token, fg, bold, dim, rules } style tables. Text-valued built-ins and $name metadata tokens accept up to 16 ordered rules using equals, contains, starts_with, gt, or lt; the first match overrides specified styles. Text conditions optionally accept ignore_case for ASCII matching; numeric conditions require full finite numbers. state_icon accepts fixed styles only. At most 16 rows and 16 tokens per row.
ui.sidebar.agents.rows_by_agenttable of token rows{}Complete Agent-row overrides keyed by strict canonical agent id. Agents without an override use ui.sidebar.agents.rows.
ui.sidebar.spaces.row_gapinteger0Blank terminal rows between worktree groups and unrelated top-level Spaces. Worktree parents and their indented children remain packed.
ui.sidebar.spaces.rowslist of token rows[["state_icon", "workspace"], ["branch", "git_status"]]Expanded Space sidebar layout. Entries may be token strings or inline { token, fg, bold, dim, rules } style tables. Text-valued built-ins and $name metadata tokens accept up to 16 ordered rules using equals, contains, starts_with, gt, or lt; the first match overrides specified styles. Text conditions optionally accept ignore_case for ASCII matching; numeric conditions require full finite numbers. state_icon and git_status accept fixed styles only. At most 16 rows and 16 tokens per row.
ui.accentcolor"cyan"Accent color for highlights, borders, and navigation UI. Accepts hex (#89b4fa), named colors (cyan, blue), or RGB (rgb(137,180,250)).

Notifications

KeyTypeDefaultDescription
ui.toast.deliveryenum"off"Popup notification delivery. off disables popups, herdsman shows in-app toasts, terminal asks the outer terminal for a desktop notification, system asks the OS notification service directly. One of off, herdsman, terminal, system.
ui.toast.delay_secondsinteger1Seconds to wait before sending finished or needs-input agent notifications. Herdsman notifies only if the pane is still in the same state when the delay expires. 0 is instant; valid values are 0 through 3600.
ui.toast.herdsman.positionenum"bottom-right"In-app toast position, relative to the full Herdsman frame. One of top-left, top-right, bottom-left, bottom-right.
ui.toast.clipboard.enabledbooleantrueShow the copied-to-clipboard popup after a mouse copy.
ui.toast.clipboard.positionenum"bottom-center"Copied-to-clipboard popup position. One of top-left, top-center, top-right, bottom-left, bottom-center, bottom-right.

Sound

KeyTypeDefaultDescription
ui.sound.enabledbooleantruePlay sounds when agents change state in background workspaces.
ui.sound.pathpathunsetOptional mp3 file path used for all notification sounds. Relative paths are resolved from the config file's directory.
ui.sound.done_pathpathunsetOptional mp3 file path for "done" notifications. Relative paths are resolved from the config file's directory.
ui.sound.request_pathpathunsetOptional mp3 file path for "request" notifications. Relative paths are resolved from the config file's directory.
ui.sound.agents.pienum"default"Sound override for detected Pi agents. One of default, on, off.
ui.sound.agents.claudeenum"default"Sound override for detected Claude Code agents. One of default, on, off.
ui.sound.agents.codexenum"default"Sound override for detected Codex agents. One of default, on, off.
ui.sound.agents.geminienum"default"Sound override for detected Gemini CLI agents. One of default, on, off.
ui.sound.agents.cursorenum"default"Sound override for detected Cursor Agent CLI agents. One of default, on, off.
ui.sound.agents.devinenum"default"Sound override for detected Devin agents. One of default, on, off.
ui.sound.agents.agyenum"default"Sound override for detected Agy agents. One of default, on, off.
ui.sound.agents.clineenum"default"Sound override for detected Cline agents. One of default, on, off.
ui.sound.agents.open_codeenum"default"Sound override for detected OpenCode agents. One of default, on, off.
ui.sound.agents.github_copilotenum"default"Sound override for detected GitHub Copilot CLI agents. One of default, on, off.
ui.sound.agents.kimienum"default"Sound override for detected Kimi Code CLI agents. One of default, on, off.
ui.sound.agents.kiroenum"default"Sound override for detected Kiro agents. One of default, on, off.
ui.sound.agents.droidenum"off"Sound override for detected Droid agents. One of default, on, off.
ui.sound.agents.ampenum"default"Sound override for detected Amp agents. One of default, on, off.
ui.sound.agents.grokenum"default"Sound override for detected Grok CLI agents. One of default, on, off.
ui.sound.agents.hermesenum"default"Sound override for detected Hermes Agent agents. One of default, on, off.
ui.sound.agents.kiloenum"default"Sound override for detected Kilo Code CLI agents. One of default, on, off.
ui.sound.agents.qoderclienum"default"Sound override for detected Qoder CLI agents. One of default, on, off.
ui.sound.agents.qwenenum"default"Sound override for detected Qwen Code agents. One of default, on, off.
ui.sound.agents.lettaenum"default"Sound override for detected Letta Code agents. One of default, on, off.
ui.sound.agents.makienum"default"Sound override for detected Maki agents. One of default, on, off.
ui.sound.agents.museenum"default"Sound override for detected Muse agents. One of default, on, off.

Session

KeyTypeDefaultDescription
session.resume_agents_on_restorebooleantrueResume supported AI-agent panes into their native conversation sessions when restoring a Herdsman session.
session.startup_per_agent_delay_msinteger100Milliseconds between automatic agent restores after a server restart. The first agent starts without this delay; 0 disables spacing. Does not delay manual launches or explicit terminal attaches. Restart the server to apply.

Worktrees

KeyTypeDefaultDescription
worktrees.directorystring"~/.herdsman/worktrees"Root directory under which Herdsman creates <repo>/<branch-slug> checkouts.

Remote

KeyTypeDefaultDescription
remote.manage_ssh_configbooleantrueAdd keepalive fallbacks and private connection reuse for `herdsman --remote`. Set false to run plain ssh unchanged.

Advanced

KeyTypeDefaultDescription
advanced.scrollback_limit_bytesinteger10000000Maximum scrollback buffer size in bytes retained per pane terminal. The legacy key name `scrollback_lines` is accepted as an alias.

Experimental

KeyTypeDefaultDescription
experimental.allow_nestedbooleanfalseAllow launching herdsman inside an existing herdsman pane.
experimental.kitty_graphicsbooleanunsetDeprecated compatibility key for terminal.kitty_graphics. Existing true and false values remain supported; terminal.kitty_graphics takes precedence when both are set.
experimental.pane_historybooleanfalsePersist pane screen history to session-history.json.
experimental.reveal_hidden_cursor_for_cjk_imebooleanfalseExpose the focused pane's cursor anchor to the outer terminal even when the pane requested `?25l`, so macOS native input methods keep tracking the candidate window when TUIs paint their own cursor (Claude Code, pi, codex, etc.). Default: false. When the pane reports no cursor position, falls back to the pane's top-left so a stable IME anchor is always available. Trade-off when enabled: an extra hardware cursor will be visible in the outer terminal for apps that hide the cursor without painting a replacement (vim normal mode, etc.). See #149.
experimental.cjk_ime_agentslist of strings[]Restrict `reveal_hidden_cursor_for_cjk_ime` to focused panes whose detected agent matches one of these names (case-insensitive). Empty list means apply to any focused pane. Unknown agent names are ignored; if the list contains no valid names, the reveal does not apply. Accepted names: pi, claude, codex, gemini, cursor, devin, cline, opencode, copilot, kimi, kiro, droid, amp, grok, hermes, kilo, qodercli, qoder, qwen, qwen-code, letta, letta-code, maki.
experimental.cjk_ime_cursor_shapeenum"steady_block"Cursor shape rendered for the IME anchor when `reveal_hidden_cursor_for_cjk_ime` is enabled. One of block, steady_block, underline, steady_underline, bar, steady_bar.
experimental.switch_ascii_input_source_in_prefixbooleanfalseWhile prefix mode is active, temporarily switch the host input source to an ASCII-capable mode so prefix commands are read as ASCII even when an IME is active, then restore the previous input source when prefix mode exits. On macOS this selects the ASCII-capable keyboard layout; on Windows it switches the IME to English (ASCII) input. Windows support is currently limited to the Korean IME; with an IME for any other language, the input source is left unchanged. macOS and Windows only; a no-op elsewhere and a best-effort no-op if the switch fails.