A Herdr plugin that reads your session twice a second and keeps every tab's title in step with the work in it. Rename a tab yourself and it leaves that tab alone from then on.

Demo

https://github.com/user-attachments/assets/606fde6a-dfd3-4010-b4f3-80c79d74ea63

Quick start

[!NOTE] Requires Herdr 0.8.2+ and Go 1.24+ on macOS, Linux or Windows. Herdr compiles the plugin from source on your machine when it installs it.

herdr plugin install kryptamine/herdr-auto-title

[!IMPORTANT] Installing does not start the plugin. Plugins are started by the Herdr server, and only when it restores a session, so run this once:

herdr server stop   # closes the session; `herdr` brings it back

Reopening your terminal will not do: that attaches a new client and leaves the server, and your plugin, exactly as they were.

Herdr clones the repository, builds the binary and registers it. Until the server has restarted, nothing is renamed. herdr plugin list shows the plugin, herdr plugin disable turns it off. Every server start brings a fresh instance, and the one the previous server started leaves on its own.

Better names for agent tabs

An agent usually says what it is working on through its terminal title, and that is where Auto Title reads it. Claude Code has one blind spot: a session you opened with a slash command and never typed a prompt into is never given a title, so its tab stays claude. One command closes it:

herdr integration install claude

That is Herdr's own hook, not this plugin's: it tells Herdr which session each pane holds, and Auto Title reads the topic from the session itself.

Herdr ships the same hook for seventeen agents (herdr integration status) and Auto Title accepts a session from any of them, but every agent keeps its transcript in its own format, so only Claude Code is read so far. Any other agent's tab is named from its terminal title, exactly as before, and HERDR_AUTO_TITLE_TRANSCRIPT=false stops Auto Title reading transcripts at all.

If your terminal already shows which agent holds a pane, the name in the tab is saying it twice: HERDR_AUTO_TITLE_AGENT_NAME=false leaves it out, and dashboard › claude › Implement OAuth scopes becomes dashboard › Implement OAuth scopes. It goes everywhere, including the tabs where the name was all there was — a pane whose agent has reported nothing then reads as its directory, dashboard, in place of claude.

What your tabs will be called

~/work/dashboard                       →  1 · dashboard
~/work/dashboard on feature/MC-13200   →  2 · dashboard › MC-13200
nvim editing auth.provider.ts          →  3 · nvim › auth.provider.ts
an agent working on OAuth scopes       →  4 · dashboard › claude › Implement OAuth scopes
ssh into prod-01                       →  5 · ssh › prod-01
$HOME                                  →  6 · Shell

Titles read <position> · <context> › <activity>, capped at 50 columns of the tab bar. The activity is the first of these that has something to say: what an agent reports it is working on, then the terminal title, then a lone program in the pane. The context is the directory you are in, or the machine you reached over ssh, and the branch you have checked out qualifies it.

These rules explain most surprises:

• The number in front is the tab's position in the workspace, which is the key that switches to it. It leads the title because the tab bar cuts the tail of one too wide for it. HERDR_AUTO_TITLE_POSITION=false leaves it out.
• A branch shows when it distinguishes. Your repository's default branch says nothing, so it is left out; anything else is shown, shortened to what identifies it (bugfix-asa-cpanel-uapi-mc-13675 → MC-13675).
• A tab you renamed is yours and Auto Title never touches it again. Clear its name and it is handed back, on the next poll; renaming it to something else keeps it yours under the new name.
• Paths, shell prompts, bare program names and your workspace name are left out, because they only repeat what the screen already shows.
• A tab with several panes takes its name from one of them: the focused pane, a pane running a busy agent, or the pane that changed last.
• On Windows, an editor or an ssh session does not name its tab. Herdr reports only the shell or an agent as what a pane there is running, so nvim › auth.provider.ts and ssh › prod-01 are titles other platforms get; the directory, the branch and every agent title work the same.

Configuration

Everything is optional; the defaults are what the section above describes. Settings live in a file Auto Title reads once, at startup:

Nothing creates it for you; config.env.example lists every setting commented out. A change reaches the plugin only when it restarts, with the same herdr server stop the install needs.

[!NOTE] The config directory herdr plugin list prints is Herdr's own. Auto Title does not read it — a plugin you start by hand would never see it. Use the path above.

Documentation

• Architecture — how it works and why: the poll loop, how a tab becomes a name, where configuration comes from, and the measured facts about the Herdr socket API.
• Development — working on it.

Contributors