herdr-automatic-rename

No more having to manually name your new tabs or deal with plain numbered tabs:

‎ 1 ‎‎‎‎ ‎ ‎ 2 ‎ ‎‎ ‎ 3 ‎‎‎ ‎ ‎ +

This plugin automatically names them either after their foreground process (inspired by tmux's automatic-rename):

‎ [1] zsh ‎‎‎ ‎ ‎ [2] nvim ‎ ‎ ‎‎ [3] ssh ‎‎‎ ‎ ‎ +

Or after the agent session context:

‎ [1] Debug transient issue ‎ ‎ ‎‎‎‎ [2] Improve test suite ‎‎‎ ‎ ‎ +

The naming mechanism is highly configurable. See the Configuration section below for more info.

Quick start

Requirements

• herdr >= 0.7.1
• jq
• bash
• Linux or macOS

Install or update

curl -fsSL https://raw.githubusercontent.com/qu8n/herdr-automatic-rename/main/install.sh | bash

This script installs the latest version of the plugin and adds our shell hook, which makes the renaming mechanism happen immediately when a command starts. It picks the hook for your login shell out of zsh, bash, and fish, and writes it to that shell's startup file.

herdr plugin install qu8n/herdr-automatic-rename --yes

# ~/.zshrc
for _f in ${HOME}/.config/herdr/plugins/github/herdr-automatic-rename-*/shell/hook.zsh(N); do
  source $_f; break
done

# ~/.bashrc
for _f in "$HOME"/.config/herdr/plugins/github/herdr-automatic-rename-*/shell/hook.bash; do
  [ -r "$_f" ] && { source "$_f"; break; }
done

# ~/.config/fish/config.fish
for _f in $HOME/.config/herdr/plugins/github/herdr-automatic-rename-*/shell/hook.fish
    test -r "$_f"; and source "$_f"; and break
end

Recommended herdr configs

1. Turn off herdr's new-tab name prompt.

# ~/.config/herdr/config.toml
[ui]
prompt_new_tab_name = false

When you create a new tab, herdr prompts you to give it a name. Custom tab names are respected by this plugin. For the best UX, disable this feature to let the plugin do the naming for you by default.

2. Install herdr integrations for your coding agents.

See herdr's integrations docs for installation details. This lets herdr detect an agent natively instead of by reading the screen, which makes for agent tab naming more effective.

Configuration (optional)

To customize, create your config file at ~/.config/herdr-automatic-rename/config.sh (or point HERDR_AUTOMATIC_RENAME_CONFIG elsewhere). See config.example.sh for the full configuration details. Every setting has a default, so you only need to set what you'd like to change.

Actions

• reset: When you manually name a tab, the plugin respects that name and doesn't touch it. This action lets the plugin take over renaming that tab.

• doctor: This action prints why the plugin named the current tab the way it did for troubleshooting purposes.

To invoke an action, either run it from the CLI:

herdr plugin action invoke herdr-automatic-rename.reset

Or bind it in config.toml as a plugin_action, like this:

[[keys.command]]
key = "prefix+a" # a for "automatic"
type = "plugin_action"
command = "herdr-automatic-rename.reset"
description = "hand this tab's name back to automatic naming"

Caveats

• Prefix numbering stops at 9 since herdr only allows keybindings up until that number.
• An untitled Claude Code tab gets its name from the session transcript on disk. Set AGENT_TRANSCRIPT=0 in config.sh to stop that.
• Some Linux containers and sandboxes hide the foreground process from herdr, so naming stops (numbering still works). On herdr >= 0.8.0, set HERDR_PROCESS_DETECTION=child-groups in herdr's environment.
• Below herdr 0.7.4, a new name only shows at the next redraw, such as a focus change.

Uninstall

bash "$(herdr plugin list --json \
  | jq -r '.result.plugins[]|select(.plugin_id=="herdr-automatic-rename").source.managed_path')/automatic-rename.sh" --clear
herdr plugin uninstall herdr-automatic-rename

Then delete ~/.local/state/herdr-automatic-rename/.

Contributing

See CONTRIBUTING.md and docs/ARCHITECTURE.md.

License

MIT.