Config reference

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

  Copy text selected with the mouse.

• 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 macOS host input source to an ASCII-capable keyboard layout so prefix commands are read as ASCII even when a CJK IME is active, then restore the previous input source when prefix mode exits. macOS only; a no-op elsewhere and a best-effort no-op if the switch fails.