Tab presets
A preset is one tab’s layout saved under a name: where its panes sit, how big they are, what they are called and what runs in them. Opening a preset makes a new tab in the workspace you choose. Every pane starts a shell in the workspace’s folder, and Herdsman types the pane’s command into it, so an agent or a test watcher is running as soon as the tab is up, and the shell stays when it exits.
Build the tab you like with splits, stacks and labels, save it, and open it in any repository.
Save a tab
Section titled “Save a tab”Right-click a tab and choose Save tab as preset…. The prompt suggests the tab’s name. A name that is
already taken asks again, and Enter then replaces that preset. Names use lowercase letters, digits, - and
_, and start with a letter or digit.
From the CLI:
herdsman preset save dev --current # the tab this pane is inherdsman preset save dev w1:t2 # a tab by IDherdsman preset save dev --overwrite # the active tab, replacing a preset named devA preset records:
- the layout: splits and their ratios, and stacks with the member that shows;
- each pane’s label, if you gave it one;
- what to start in each pane: a detected agent’s command, such as
claude, or the command the pane was launched with. A plain shell gets no command; - the tab’s name, if you renamed it.
Folders are not recorded. Every pane opens in the workspace’s folder, so the same preset works in any
repository; give a pane a cwd in the file to start it somewhere else.
Open a preset
Section titled “Open a preset”prefix+t opens the presets list, and so does New tab from preset… in a tab’s right-click menu. Pick a
preset and press Enter: it opens as a new tab in the current workspace, or, from the tab menu, in that tab’s
workspace.
| Key | Action |
|---|---|
/ |
Filter the list |
Up, Down, j, k, Ctrl+n, Ctrl+p |
Move |
| Enter | Open the preset as a new tab |
e |
Edit the preset’s file |
r |
Rename |
d |
Delete, after a confirmation: y deletes, any other key keeps it |
| Esc | Close the list |
A click selects a row, and a second click or the open button opens it. The key is keys.presets in the
configuration.
From the CLI:
herdsman preset list # names, tab labels and pane countsherdsman preset load dev --current # in the workspace of this paneherdsman preset load dev --workspace w2 --no-focusStart a workspace from a preset
Section titled “Start a workspace from a preset”A new workspace can start from a preset instead of a plain shell: the preset becomes its first tab. When you
have presets, creating a workspace, New worktree and Open worktree… show a preset choice, with
None for a plain shell. The default from your config is selected, so Enter keeps it. A preset with a
required parameter that has no default is left out of the choice; give its value with the CLI’s
--param instead.
Set the defaults in the configuration, for every workspace, for every worktree, and per repository:
[presets]workspace = "dev" # new workspacesworktree = "worktree" # new or newly opened worktrees, in any repository
[presets.projects.herdsman] # a repository, by the name the sidebar shows for itworkspace = "herdsman" # new workspaces in its main checkoutworktree = "herdsman-worktree" # its worktreesA repository’s own setting wins over the general one. A worktree takes only worktree settings, never the
workspace one, so worktrees stay plain unless you name a preset for them. A worktree that is already open
keeps the layout it has.
From the CLI, --preset does the same for one command; without it, the CLI creates a plain workspace as
before:
herdsman workspace create --cwd ~/project --preset devherdsman worktree create --branch fix-login --preset worktreeherdsman worktree open --branch review --preset worktreeGive a preset’s parameters with --param name=value. A missing or broken preset, or a missing
value, fails before anything is created, and so does --env, since the preset’s panes replace the shell it
would reach. The answer describes the workspace and its tab as they are once the preset is open, and carries
the preset’s panes as preset_layout in place of the shell’s root_pane. If the preset still cannot be
applied, the workspace stays open with its plain shell: the create answer goes to stdout, the error to
stderr, and the command exits with status 1.
Edit a preset
Section titled “Edit a preset”A preset is a TOML file you can change by hand. Press e in the list, or run herdsman preset edit <name>.
The list opens it in a popup pane, the CLI in your terminal, each with $VISUAL, else $EDITOR, else vi
(Notepad on Windows). Herdsman reads the file again afterwards: the CLI prints any mistake with its line
when the editor closes, and the list shows a broken preset with its error the next time it opens, ready for
another e.
The file
Section titled “The file”Presets live in ~/.config/herdsman/presets/<name>.toml on the machine whose server runs the tab. Each node
of the layout is a table: [root] is the whole tab, and a split’s halves are its first and second.
label = "dev" # the new tab's name
[root]split = "right" # side by side; "down" stacks them top and bottomratio = 0.6 # the first half's share; 0.5 if left out
[root.first]label = "agent"command = "claude" # typed into the pane's shell once it starts
[root.second]split = "down"
[root.second.first]label = "tests"command = "just test"env = { RUST_LOG = "info" }
[root.second.second]active = 1 # the stack shows its second member
[[root.second.second.stack]]label = "docs"cwd = "docs" # relative to the workspace's folder
[[root.second.second.stack]]label = "shell"A node with split is a split, a node with stack is a stack, and any other node is a pane. A pane takes
label, cwd, command and env; a stack’s panes, in [[...stack]] tables, take the same. cwd can also
be absolute or start with ~. A folder that does not exist falls back to the workspace’s, and the server’s
log says so. A preset holds at most 24 panes and 16 levels of splits, as for layout.apply.
Parameters
Section titled “Parameters”A preset can take values when it opens, so one preset serves every pull request, ticket or branch. Declare
them in a [params] table:
[params]pr = { required = true, description = "pull request number" }base = { default = "dev" }
[root]split = "right"
[root.first]command = "claude"
[root.second]command = "gh pr diff $PR | diffnav"Every pane gets each value as an environment variable named in upper case, pr as PR, and its command
reads it as $PR. The shell expands the variable, so a value is never pasted into the command line: a
branch named x;rm -rf ~ stays a plain string. A parameter with a default takes it when no value is given;
a required one cannot be left out. Names are a lowercase letter, then lowercase letters, digits and _,
and may not stand for a variable the shell or Herdsman uses, such as path or home.
Give the values when you open the preset:
herdsman preset load pr --param pr=42 --param base=testOpening a preset with a value it does not declare, or without a required one, fails before any tab opens.
In the presets list, Enter on a preset with required parameters asks for each value first. Saving a tab over
an existing preset keeps its [params].
Presets on other machines
Section titled “Presets on other machines”Each server keeps its own presets, in its own machine’s config folder. A tab on a saved SSH machine is saved
there and opened from there, and herdsman --machine <name> preset ... works too, except edit, which opens
a file on the machine you run it on.
The JSON methods behind these commands are listed under Tab presets in the socket API.
Thanks to the herdr-grid plugin for the nudge toward presets.