// plugin · v0.3.0 · herdr ≥ 0.9.5 · macOS & Linux

auto-tab-name

Tabs that name themselves. Every Herdr tab takes the name of the folder its pane is in, keeps it in sync as you and your agents move around, and leaves alone the tabs you name yourself.

herdr plugin install MrBogomips/herdr-tools/auto-tab-name

Before: tabs named 1, 2, 3. After: each one says where its pane works, worktree branch included.

// 01

Pick what a name shows

Herdr shows a tab nobody named as its position number. auto-tab-name renames those tabs after their pane's folder, and only writes when a name changes. For ~/tools/initech/sort, inside the repository initech on branch main:

`format`	Name	Outside a repository
`basename` (default)	`sort`	same
`repo`	`initech/sort`	like `basename`
`last_n`	`initech/sort`, the last `depth` folders	same
`home_path`	`~/tools/initech/sort`	same
`repo_branch`	`initech@main`, or the short hash when detached	like `basename`

A linked worktree shows the name of its main repository. The repository is found by reading .git: no git process runs.

// 02

It follows your agents into worktrees

By default the name comes from the folder of the program in the foreground, not the shell's. When an agent started in ~/tools/initech goes to work in the worktree .worktrees/login, its tab says so:

`format`	`"cwd"` (the shell)	`"foreground_cwd"` (default)
`basename`	`initech`	`login`
`repo_branch`	`initech@main`	`initech@feature/login`

Herdr has no event for a folder change, so the name follows at the agent's next change of state: when it gets ready, and at the latest when the turn that moved it ends.

// 03

Your names stay yours

A new tab shows its position number, so it follows its folder from the start.
Rename a tab by hand and it stops following: your name stays.
follow makes it follow again, and so does renaming it back to its position number.
A Herdr restart changes nothing: tabs already named like their folder count as followed.

// 04

Key bindings

Bind the actions you want in ~/.config/herdr/config.toml, then run herdr server reload-config:

[[keys.command]]
key = "prefix+alt+c"
type = "plugin_action"
command = "mrbogomips.auto-tab-name.configure"

[[keys.command]]
key = "prefix+alt+t"
type = "plugin_action"
command = "mrbogomips.auto-tab-name.toggle"

[[keys.command]]
key = "prefix+alt+f"
type = "plugin_action"
command = "mrbogomips.auto-tab-name.follow"

On macOS an alt key reaches Herdr only when the terminal sends Option as Alt: in iTerm2 set Profiles › Keys › Left Option key to "Esc+", in Ghostty set macos-option-as-alt = left, and keep the right Option for the characters your layout types with it (~, @, # on an Italian keyboard). Terminal's "Use Option as Meta key" takes both Option keys, so there, or if you would rather not change the terminal, bind prefix+<letter> keys instead.

Action	What it does
`configure`	Opens the configuration popup
`toggle`	Turns `auto_sync` on or off
`sync`	Names every followed tab now
`follow` / `unfollow`	Makes the current tab follow its folder, or keeps its name as it is
`refresh`	The quiet run, for the shell integration

// 05

Instant names with shell integration

Without it, a name catches up at the next focus or tab change. To rename as soon as you cd, add the lines for your shell; bash and fish versions are in the README.

# ~/.zshrc
if [[ $HERDR_ENV == 1 && -n $HERDR_BIN_PATH ]]; then
  autoload -Uz add-zsh-hook
  _auto_tab_name_chpwd() { "$HERDR_BIN_PATH" plugin action invoke mrbogomips.auto-tab-name.refresh >/dev/null 2>&1 &! }
  add-zsh-hook chpwd _auto_tab_name_chpwd
fi

It runs only inside Herdr, in the background, so the prompt never waits.

// 06

Configuration

The configure popup edits config.json for you; the file is read on every run.

Key	Default	Meaning
`auto_sync`	`true`	Rename tabs from the hooks
`format`	`"basename"`	What the name shows, see formats
`depth`	`2`	Folders shown by `last_n`
`max_length`	`24`	Longest name, cut with `…`; `0` for no limit
`source`	`"foreground_cwd"`	Folder of the foreground program, or `"cwd"` for the shell's
`home_tilde`	`true`	Write the home folder as `~`

// 07

Good to know

No Herdr event fires on cd: without the shell integration a name catches up at the next focus or tab change.
A tab with several panes uses the pane you focused last in it.
With repo or repo_branch, a git repository in your home folder (dotfiles, say) names every folder under home that is in no other repository.

Install → Full README on GitHub ↗