Config reference

Next docs describe unreleased work from master. Stable docs remain at /docs/.

Every canonical key PK-Herdr reads from config.toml, flat and filterable. For guided setup and the reasoning behind these options, see Configuration.

Print the full commented default config at any time:

pk-herdr --default-config

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

148 keys

General

• onboardingbooleandefault unset

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

Theme

• theme.namestringdefault "catppuccin"

  Built-in theme name.

• theme.auto_switchbooleandefault false

  Follow host terminal light/dark appearance and switch between theme names.

• theme.dark_namestringdefault unset

  Theme name used when `auto_switch` selects a dark appearance.

• theme.light_namestringdefault unset

  Theme name used when `auto_switch` selects a light appearance.

• theme.custom.accentcolordefault unset

  Override the accent color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

• theme.custom.panel_bgcolordefault unset

  Override the panel_bg color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

• theme.custom.surface0colordefault unset

  Override the surface0 color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

• theme.custom.surface1colordefault unset

  Override the surface1 color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

• theme.custom.surface_dimcolordefault unset

  Override the surface_dim color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

• theme.custom.overlay0colordefault unset

  Override the overlay0 color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

• theme.custom.overlay1colordefault unset

  Override the overlay1 color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

• theme.custom.textcolordefault unset

  Override the text color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

• theme.custom.subtext0colordefault unset

  Override the subtext0 color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

• theme.custom.mauvecolordefault unset

  Override the mauve color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

• theme.custom.greencolordefault unset

  Override the green color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

• theme.custom.yellowcolordefault unset

  Override the yellow color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

• theme.custom.redcolordefault unset

  Override the red color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

• theme.custom.bluecolordefault unset

  Override the blue color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

• theme.custom.tealcolordefault unset

  Override the teal color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

• theme.custom.peachcolordefault unset

  Override the peach color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases.

Terminal

• terminal.default_shellstringdefault ""

  Executable used for new interactive panes. Empty means SHELL, then /bin/sh.

• terminal.shell_modeenumdefault "auto"

  Startup mode for new interactive pane shells.autologinnon_login

• terminal.new_cwdenumdefault "follow"

  CWD policy for new interactive panes, tabs, and workspaces.followhomecurrentpath

Updates

• update.channelenumdefault "stable" ("preview" on Windows)

  Update channel used by background version checks and pk-herdr update. Homebrew, mise, and Nix installs ignore the preview channel.stablepreview

• update.version_checkbooleandefault true

  Check herdr.dev for new PK-Herdr versions in the background.

• update.manifest_checkbooleandefault true

  Check herdr.dev for remote agent-detection manifest updates in the background. Bundled manifests and local overrides still apply.

Keybindings

• keys.prefixstringdefault "ctrl+b"

  Prefix key to enter prefix mode (e.g. "ctrl+b", "f12", "esc").

• keys.helpkeybindingdefault "prefix+?"

  Open keybinding help.

• keys.settingskeybindingdefault "prefix+s"

  Open settings.

• keys.new_workspacekeybindingdefault "prefix+shift+n"

  Create a new workspace.

• keys.new_worktreekeybindingdefault "prefix+shift+g"

  Create a Git worktree from the selected workspace.

• keys.open_worktreekeybindingdefault unset

  Open an existing Git worktree from the selected workspace. Unset by default.

• keys.remove_worktreekeybindingdefault unset

  Delete the selected managed worktree checkout after confirmation. Unset by default.

• keys.rename_workspacekeybindingdefault "prefix+shift+w"

  Rename the selected workspace.

• keys.close_workspacekeybindingdefault "prefix+shift+d"

  Close the selected workspace.

• keys.workspace_pickerkeybindingdefault "prefix+w"

  Open the workspace navigation surface.

• keys.gotokeybindingdefault "prefix+g"

  Open the session navigator.

• keys.navigate_workspace_upkeybindingdefault "up"

  Move workspace selection up in navigate mode.

• keys.navigate_workspace_downkeybindingdefault "down"

  Move workspace selection down in navigate mode.

• keys.navigate_pane_leftkeybindingdefault "h"

  Focus the pane to the left in navigate mode. Left arrow is always an alias.

• keys.navigate_pane_downkeybindingdefault "j"

  Focus the pane below in navigate mode.

• keys.navigate_pane_upkeybindingdefault "k"

  Focus the pane above in navigate mode.

• keys.navigate_pane_rightkeybindingdefault "l"

  Focus the pane to the right in navigate mode. Right arrow is always an alias.

• keys.detachkeybindingdefault "prefix+q"

  Detach from server/client mode, or exit --no-session mode.

• keys.reload_configkeybindingdefault "prefix+shift+r"

  Reload config.toml in the running app/server.

• keys.open_notification_targetkeybindingdefault "prefix+o"

  Focus the currently visible notification target.

• keys.previous_workspacekeybindingdefault unset

  Select the previous workspace. Unset by default.

• keys.next_workspacekeybindingdefault unset

  Select the next workspace. Unset by default.

• keys.previous_agentkeybindingdefault unset

  Focus the previous agent shown in the agent panel. Unset by default.

• keys.next_agentkeybindingdefault unset

  Focus the next agent shown in the agent panel. Unset by default.

• keys.focus_agentkeybindingdefault unset

  Focus an agent by index 1-9. Unset by default.

• keys.remote_image_pastestringdefault "ctrl+v"

  Local-client shortcut that sends a clipboard image to a remote PK-Herdr session.

• keys.new_tabkeybindingdefault "prefix+c"

  Create a new tab in the active workspace.

• keys.rename_tabkeybindingdefault "prefix+shift+t"

  Rename the active tab.

• keys.previous_tabkeybindingdefault "prefix+p"

  Select the previous tab.

• keys.next_tabkeybindingdefault "prefix+n"

  Select the next tab.

• keys.switch_tabkeybindingdefault "prefix+1..9"

  Switch to tab 1-9.

• keys.switch_workspacekeybindingdefault unset

  Switch to workspace 1-9 from prefix mode. Unset by default.

• keys.close_tabkeybindingdefault "prefix+shift+x"

  Close the active tab.

• keys.rename_panekeybindingdefault "prefix+shift+p"

  Rename the focused pane.

• keys.edit_scrollbackkeybindingdefault "prefix+e"

  Open the focused pane scrollback in $EDITOR.

• keys.copy_modekeybindingdefault "prefix+["

  Enter keyboard copy mode for the focused pane.

• keys.focus_pane_leftkeybindingdefault "prefix+h"

  Focus the pane to the left.

• keys.focus_pane_downkeybindingdefault "prefix+j"

  Focus the pane below.

• keys.focus_pane_upkeybindingdefault "prefix+k"

  Focus the pane above.

• keys.focus_pane_rightkeybindingdefault "prefix+l"

  Focus the pane to the right.

• keys.swap_pane_leftkeybindingdefault "prefix+shift+h"

  Swap the focused pane with the pane to the left.

• keys.swap_pane_downkeybindingdefault "prefix+shift+j"

  Swap the focused pane with the pane below.

• keys.swap_pane_upkeybindingdefault "prefix+shift+k"

  Swap the focused pane with the pane above.

• keys.swap_pane_rightkeybindingdefault "prefix+shift+l"

  Swap the focused pane with the pane to the right.

• keys.cycle_pane_nextkeybindingdefault "prefix+tab"

  Cycle to the next pane.

• keys.cycle_pane_previouskeybindingdefault "prefix+shift+tab"

  Cycle to the previous pane.

• keys.last_panekeybindingdefault unset

  Focus the last focused pane across workspaces and tabs. Unset by default.

• keys.split_verticalkeybindingdefault "prefix+v"

  Split pane vertically (side by side).

• keys.split_horizontalkeybindingdefault "prefix+minus"

  Split pane horizontally (stacked).

• keys.close_panekeybindingdefault "prefix+x"

  Close the focused pane.

• keys.zoomkeybindingdefault "prefix+z"

  Toggle zoom for the focused pane. The legacy key name `fullscreen` is accepted as an alias.

• keys.resize_modekeybindingdefault "prefix+r"

  Enter resize mode.

• keys.toggle_sidebarkeybindingdefault "prefix+b"

  Toggle sidebar collapse.

• keys.indexed.tabsstringdefault unset

  Modifier combo for tab shortcuts 1-9. Unset by default.

• keys.indexed.workspacesstringdefault unset

  Modifier combo for workspace shortcuts 1-9. Unset by default.

• keys.indexed.agentsstringdefault unset

  Modifier combo for agent shortcuts 1-9. Unset by default.

UI and sidebar

• ui.sidebar_widthintegerdefault 26

  Default expanded sidebar width in columns. Auto-scales based on workspace names.

• ui.sidebar_min_widthintegerdefault 18

  Minimum sidebar width (columns) when expanded.

• ui.sidebar_max_widthintegerdefault 36

  Maximum sidebar width (columns) when expanded.

• ui.sidebar_start_collapsedbooleandefault false

  Start PK-Herdr with the sidebar collapsed. Changes take effect on the next launch.

• ui.sidebar_collapsed_modeenumdefault compact

  Collapsed sidebar presentation.compacthidden

• ui.mobile_width_thresholdintegerdefault 64

  Terminal width at or below which PK-Herdr uses the mobile single-column layout.

• ui.mouse_capturebooleandefault true

  Capture mouse input for PK-Herdr's mouse UI.

• ui.copy_on_selectbooleandefault true

  Automatically 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_cursorenumdefault auto

  Host cursor policy.autonativedrawn

• ui.right_click_passthrough_modifierstringdefault ""

  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_gainedbooleandefault true

  Force a full host-terminal redraw when the outer terminal regains focus.

• ui.mouse_scroll_linesintegerdefault 3

  Lines to scroll per mouse wheel notch.

• ui.confirm_closebooleandefault true

  Ask for confirmation before closing a workspace.

• ui.prompt_new_tab_namebooleandefault true

  Ask for a tab name before creating a new tab.

• ui.prompt_new_workspace_namebooleandefault false

  Ask for a workspace name before interactive TUI creation.

• ui.pane_bordersbooleandefault true

  Draw borders around split panes.

• ui.pane_gapsbooleandefault true

  Keep split panes visually separated instead of sharing divider borders.

• ui.show_agent_labels_on_pane_bordersbooleandefault false

  Show agent labels in split pane borders when no manual pane label is set.

• ui.hide_tab_bar_when_single_tabbooleandefault false

  Hide the tab row when the workspace has one tab.

• ui.agent_panel_sortenumdefault "spaces"

  Agent sidebar ordering. Saved values are "spaces" or "priority"; "workspaces" is accepted as an alias for "spaces".spacespriority

• ui.sidebar.agents.row_gapintegerdefault 0

  Blank terminal rows between expanded Agent sidebar entries. Set to 1 to restore the previous spacing.

• ui.sidebar.agents.rowslist of token rowsdefault [["state_icon", "workspace", "tab"], ["agent"]]

  Default expanded Agent sidebar layout. Entries may be token strings or inline { token, fg, bold, dim } style tables. Supports built-in and $name metadata tokens; at most 16 rows and 16 tokens per row.

• ui.sidebar.agents.rows_by_agenttable of token rowsdefault {}

  Complete Agent-row overrides keyed by strict canonical agent id. Agents without an override use ui.sidebar.agents.rows.

• ui.sidebar.spaces.row_gapintegerdefault 0

  Blank terminal rows between expanded Space sidebar entries. Set to 1 to restore the previous spacing. Consecutive indented worktree children remain packed as one group.

• ui.sidebar.spaces.rowslist of token rowsdefault [["state_icon", "workspace"], ["branch", "git_status"]]

  Expanded Space sidebar layout. Entries may be token strings or inline { token, fg, bold, dim } style tables. Supports built-in and $name metadata tokens; at most 16 rows and 16 tokens per row.

• ui.accentcolordefault "cyan"

  Accent color for highlights, borders, and navigation UI. Accepts hex (#89b4fa), named colors (cyan, blue), or RGB (rgb(137,180,250)).

Notifications

• ui.toast.deliveryenumdefault "off"

  Popup notification delivery. off disables popups, herdr shows in-app toasts, terminal asks the outer terminal for a desktop notification, system asks the OS notification service directly.offherdrterminalsystem

• ui.toast.delay_secondsintegerdefault 1

  Seconds to wait before sending finished or needs-input agent notifications. PK-Herdr 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.herdr.positionenumdefault "bottom-right"

  In-app toast position, relative to the full PK-Herdr frame.top-lefttop-rightbottom-leftbottom-right

• ui.toast.clipboard.enabledbooleandefault true

  Show the copied-to-clipboard popup after a mouse copy.

• ui.toast.clipboard.positionenumdefault "bottom-center"

  Copied-to-clipboard popup position.top-lefttop-centertop-rightbottom-leftbottom-centerbottom-right

Sound

• ui.sound.enabledbooleandefault true

  Play sounds when agents change state in background workspaces.

• ui.sound.pathpathdefault unset

  Optional mp3 file path used for all notification sounds. Relative paths are resolved from the config file's directory.

• ui.sound.done_pathpathdefault unset

  Optional mp3 file path for "done" notifications. Relative paths are resolved from the config file's directory.

• ui.sound.request_pathpathdefault unset

  Optional mp3 file path for "request" notifications. Relative paths are resolved from the config file's directory.

• ui.sound.agents.pienumdefault "default"

  Sound override for detected Pi agents.defaultonoff

• ui.sound.agents.claudeenumdefault "default"

  Sound override for detected Claude Code agents.defaultonoff

• ui.sound.agents.codexenumdefault "default"

  Sound override for detected Codex agents.defaultonoff

• ui.sound.agents.geminienumdefault "default"

  Sound override for detected Gemini CLI agents.defaultonoff

• ui.sound.agents.cursorenumdefault "default"

  Sound override for detected Cursor Agent CLI agents.defaultonoff

• ui.sound.agents.devinenumdefault "default"

  Sound override for detected Devin agents.defaultonoff

• ui.sound.agents.agyenumdefault "default"

  Sound override for detected Agy agents.defaultonoff

• ui.sound.agents.clineenumdefault "default"

  Sound override for detected Cline agents.defaultonoff

• ui.sound.agents.open_codeenumdefault "default"

  Sound override for detected OpenCode agents.defaultonoff

• ui.sound.agents.github_copilotenumdefault "default"

  Sound override for detected GitHub Copilot CLI agents.defaultonoff

• ui.sound.agents.kimienumdefault "default"

  Sound override for detected Kimi Code CLI agents.defaultonoff

• ui.sound.agents.kiroenumdefault "default"

  Sound override for detected Kiro agents.defaultonoff

• ui.sound.agents.droidenumdefault "off"

  Sound override for detected Droid agents.defaultonoff

• ui.sound.agents.ampenumdefault "default"

  Sound override for detected Amp agents.defaultonoff

• ui.sound.agents.grokenumdefault "default"

  Sound override for detected Grok CLI agents.defaultonoff

• ui.sound.agents.hermesenumdefault "default"

  Sound override for detected Hermes Agent agents.defaultonoff

• ui.sound.agents.kiloenumdefault "default"

  Sound override for detected Kilo Code CLI agents.defaultonoff

• ui.sound.agents.qoderclienumdefault "default"

  Sound override for detected Qoder CLI agents.defaultonoff

• ui.sound.agents.makienumdefault "default"

  Sound override for detected Maki agents.defaultonoff

Session

• session.resume_agents_on_restorebooleandefault true

  Resume supported AI-agent panes into their native conversation sessions when restoring a PK-Herdr session.

Worktrees

• worktrees.directorystringdefault "~/.herdr/worktrees"

  Root directory under which PK-Herdr creates <repo>/<branch-slug> checkouts.

Remote

• remote.manage_ssh_configbooleandefault true

  Add keepalive fallbacks and private connection reuse for `pk-herdr --remote`. Set false to run plain ssh unchanged.

Advanced

• advanced.scrollback_limit_bytesintegerdefault 10000000

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

Experimental

• experimental.allow_nestedbooleandefault false

  Allow launching herdr inside an existing pk-herdr pane.

• experimental.kitty_graphicsbooleandefault false

  Experimental local Kitty graphics rendering for attached clients.

• experimental.pane_historybooleandefault false

  Persist pane screen history to session-history.json.

• experimental.reveal_hidden_cursor_for_cjk_imebooleandefault false

  Expose 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 stringsdefault []

  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, maki.

• experimental.cjk_ime_cursor_shapeenumdefault "steady_block"

  Cursor shape rendered for the IME anchor when `reveal_hidden_cursor_for_cjk_ime` is enabled.blocksteady_blockunderlinesteady_underlinebarsteady_bar

• experimental.switch_ascii_input_source_in_prefixbooleandefault false

  While 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.