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