Picker configuration¶

The native picker runs in both the Herdr TUI plugin and the Herdr app's sesh mod. Picker controls and settings are shared; host-specific behavior is noted below.

Use the Settings editor or edit config.toml. For example, add these settings to a native file with version = 1; if [picker] already exists, edit its values instead of adding another table:

[picker]
show_icons = true
workspace_sort = "agent"
preview_mode = "pane"

[picker]¶

These settings affect the native picker, except separator_aware, which also applies to fzf. Picker sorting does not change JSON output.

Search ranking¶

Names and paths match case-insensitively; name matches precede path-only matches. Each group retains its existing order, including workspace_sort for Herdr rows. An exact home query also finds the actual home directory regardless of its name: prioritize_home = true puts it first; false keeps it among path matches. The fzf picker uses its own ranking.

Agent sorting uses blocked → done → working → idle → unknown/no agent, retaining Herdr order for ties and unrecognized states. Live updates preserve the selected workspace. Sorting rearranges only Herdr rows within their list.source_order slots; it cannot move them ahead of sources ordered first. Linked worktrees sort as families.

Preview controls¶

command uses the configured preview command or built-in fallback. pane shows the selected running workspace's active pane, refreshing once per second without changing focus or running preview commands. Configured sessions and directories without running panes show an unavailable message.

show_preview = false disables both modes and cycling. preview_mode does not change the herdr-sesh preview command. With show_path = false, side-by-side previews initially take 50% of the width; narrow terminals keep stacked previews. See Keybindings for toggling modes and resizing the divider; these adjustments last only until the picker closes.

[keys]¶

[keys]
cycle_preview_mode = "alt+p" # default: "ctrl+o"; "" disables cycling

Add this table to your native config, or edit the existing [keys] table. The shortcut overrides other native picker bindings, so choose an unused key. An empty value hides the shortcut hint, leaves preview_mode in effect, and returns keys to normal handling. This does not configure fzf or Herdr shortcuts.

Picker colors¶

With herdr_theme_inherit = true, the picker reads Herdr's config from HERDR_CONFIG_PATH, then $XDG_CONFIG_HOME/herdr/config.toml, then ~/.config/herdr/config.toml. Set [theme] name and optional [theme.custom] colors in Herdr's config, not the plugin config.

Both integrations read this Herdr TUI theme configuration. The app mod does not read the Herdr app's theme settings.

With Herdr's [theme] auto_switch = true, the picker checks the terminal background when it opens and uses light_name or dark_name, plus [theme.custom.light] or [theme.custom.dark], like Herdr does. When the background can't be read, it uses the dark theme. Omitted mode names are derived from name: for example, tokyo-night uses tokyo-night in dark terminals and tokyo-night-day in light terminals. Themes without a sibling, such as nord, use the same theme in both modes. Explicit empty or unknown mode names use the default for that mode: catppuccin for dark and catppuccin-latte for light. The startup appearance is captured even when inheritance is disabled, so enabling it in settings uses that appearance without querying the terminal again.

Cursor and status indicators¶

Set these environment variables in the environment inherited by Herdr. HERDR_SESH_SMEAR_PRESET selects the cursor animation:

Set HERDR_SESH_REDUCE_MOTION=1 (or true) for instantaneous movement without trails.

Herdr agent indicators are amber animated spinner (working), red ◉ (blocked), green ✓ (idle), and teal ● (done). Unknown states have no indicator.

Workspace history¶

The installed Herdr TUI plugin automatically tracks switches through the picker, Herdr controls, and CLI for last, recent sorting, and the footer. History is separate per Herdr session; closed workspaces are removed. No extra setup is required. See Workspace history tracking for storage, migration, lifecycle hooks, and reconnect limitations.

The app mods keep separate history and record Sesh switches by default. Recording sidebar navigation and other app switches requires a sesh-last layout block. The app does not run the TUI plugin's lifecycle hooks.

Sidebar marker¶

This marker is available only in Herdr TUI. The app mods do not add a sidebar marker.

The plugin reports a sesh_last workspace metadata token with the default value last on the workspace that last would switch to. Add $sesh_last to Herdr's Space rows in ~/.config/herdr/config.toml to show it:

[ui.sidebar.spaces]
rows = [
  ["state_icon", "workspace", { token = "$sesh_last", fg = "#f9e2af", bold = true }],
  ["branch", "git_status"],
]

The marker moves with workspace history, including switches made outside the picker.

To change its text, add this to the herdr-sesh config.toml:

[history]
last_workspace_label = "previous"

The default is "last". An empty string hides the marker. Text may include Unicode, up to 80 characters, but must not contain control characters or start or end with whitespace; Herdr would otherwise alter the stored value. Changes apply on the next workspace focus or close event without restarting the plugin.

Linked worktrees¶

Linked worktrees appear beneath their open parent in every sort mode, with a purple type label and ├─/└─ branches. The default label is ↳ herdr ([↳ herdr] without icons). Paths appear when space permits; narrow layouts keep the type label. Grouping is automatic, independent of show_icons and replace_worktree_icon. Without a single resolvable open parent, a row stays ungrouped.

In agent mode, the family's highest-priority status ranks the whole family. The parent remains first; children follow in agent-priority order.