Configuration¶

herdr-sesh uses TOML configuration with version = 1 and rejects unknown keys. Older Sesh files still load with a deprecation warning; see Legacy migration.

The Herdr TUI plugin and Herdr app mods share this format and its lookup order. The herdr plugin commands below apply to the TUI plugin. For app mod setup and host-specific limits, see Herdr app.

Configure a workspace once, then select it in the picker to open its named tabs and split panes, each with its own working directory, environment, and command. Layouts run when a workspace is created; reconnecting preserves your running terminals.

Create your configuration¶

For a fresh Herdr TUI plugin installation, ask Herdr for its managed directory:

herdr plugin config-dir fullerzz.sesh

Create config.toml in the printed directory. If you already have a config, check the lookup order and migration instructions before creating a higher-priority file.

Herdr keeps runtime state in a separate HERDR_PLUGIN_STATE_DIR directory.

For the app mods, use ~/.config/herdr-sesh/config.toml or set HERDR_SESH_CONFIG to an explicit path. The app does not provide the TUI plugin's managed directories. App history uses a separate state directory.

Add a workspace with a tab¶

Put this complete example in config.toml, replacing the path with an existing Git checkout:

version = 1

[[tab]]
name = "git"
startup = "git status"

[[workspace]]
name = "my-project"
path = "/absolute/path/to/my-project"
tabs = ["git"]

If a native config already exists, add just the [[tab]] and [[workspace]] entries, using unique names; keep its single version = 1 line. Migrate a legacy config before adding native entries.

Open the picker from Herdr TUI:

herdr plugin action invoke fullerzz.sesh.open-picker

In the Herdr app, open the sesh mod instead.

Search for my-project and press Enter. A newly created workspace receives the named git tab and runs git status there. Selecting an existing workspace focuses it; it does not recreate its tabs or rerun startup commands. For a new workspace, Herdr initially shows a separate shell tab; select git to see the command. See Initial tab behavior for when a configured tab can reuse that first tab.

For optional shell validation, follow the CLI setup and run "$sesh_bin" config validate. For splits, continue with the pane layout walkthrough.

Settings editor¶

In either integration, press F2 in the native picker (Ctrl+, if preview cycling uses F2). Herdr TUI also provides this plugin action:

herdr plugin action invoke fullerzz.sesh.open-settings

Edit Picker, Lists (source order and blacklist), Naming, Keys, and Workspace Defaults here. Workspace, tab, pane, and rule definitions remain file-only. For standalone use, see config edit.

Press Ctrl+S to review changes, then Y to save. In text/list editors, Ctrl+S first applies the edit to the draft. Saving runs no startup or preview commands. Returning to the picker applies saved settings, refreshes sessions, resumes previews, and preserves search/selection when possible. The editor uses the picker's colors; theme changes apply after saving.

Save errors keep your draft. On a conflict, R opens a reload confirmation; Y discards the draft and loads the current file. There is no force overwrite or automatic merge.

The form supports 80×24 and compact 60×18 terminals; smaller sizes show resize instructions and safe exit controls. See Settings controls.

Files, defaults, and conflicts¶

Legacy conversion¶

Opening a legacy file offers a separate migration review. Confirming preserves the source and creates a native file, then switches the editor and returning picker to it. Existing destinations are never overwritten.

Configuration file lookup¶

Lookup order:

1. --config PATH
2. HERDR_SESH_CONFIG (an error if the file does not exist)
3. ${HERDR_PLUGIN_CONFIG_DIR}/config.toml
4. ${HERDR_PLUGIN_CONFIG_DIR}/sesh.toml as a legacy fallback
5. ~/.config/herdr-sesh/config.toml
6. ~/.config/herdr-sesh/sesh.toml as a legacy fallback
7. ~/.config/sesh/sesh.toml as a legacy fallback

Explicit paths may use either schema: a top-level version selects native decoding; otherwise they are legacy. See config commands for path, init, validate, and missing-file exceptions.

Settings¶

Picker shortcuts, appearance, sorting, and history are documented in Picker.

[list]¶

[naming]¶

[history]¶

[workspace_defaults]¶

[[workspace]]¶

Startup commands are selected in this order: the explicit workspace command, the first matching rule command, then workspace_defaults.startup. Preview commands use the same explicit workspace, rule, then default order.

Layouts¶

For named tabs, pane splits, startup behavior, and recovery, see Layouts.

[[rule]]¶

Rule startup, preview, and disable settings apply to every matching workspace when the corresponding explicit workspace field is unset. Rule tabs apply only to discovered or direct-path workspaces. The first matching rule wins.

For example, append this rule to a native config containing the git tab above:

[[rule]]
path_glob = "~/projects/**"
tabs = ["git"]

Discovered projects under ~/projects then receive that tab when created. Omitted rule commands fall back to workspace defaults; disable_startup defaults to false and tabs to [].

Legacy migration¶

Legacy files remain supported for at least one released version. To convert, use the settings editor, or follow the CLI setup and run "$sesh_bin" config migrate. Add --config PATH (or positional PATH) to select a particular file.

Migration flattens imports into native config.toml, preserves the source, and prints the new path. Check the result before optionally deleting the legacy file. First update HERDR_SESH_CONFIG or explicit arguments that select the old path. A legacy file already named config.toml must be renamed before migration; in-place conversion is not supported, even with --force.

Legacy tmux_command, tmuxp, and tmuxinator fields have no Herdr equivalent; native decoding rejects them like any other unknown key. Describe tab splits with native pane layouts instead.