herdr-rename-hook
Skill3 starsChanged yesterdayMITView on GitHub
Install the hook that renames the Herdr agent, pane and tab to match a Claude Code or Codex session renamed with /rename.
In this repository31 other files it gives its agents.
- affix-domainsSkill
- apple-designSkill
- apwcli-pairSkill
- ask-always-on-agentSkill
- asus-esc8000-firmware-upgradeSkill
- asus-esc8000-gpu-bios-tuningSkill
- build-stealth-rustdeskSkill
- chrome-cdp-setupSkill
- cua-macos-lume-sandboxSkill
- deploy-kimi-k26-on-rtx-pro-6000Skill
- deploy-kimi-k3-on-rtx-pro-6000Skill
- deploy-stealth-rustdeskSkill
- ghostty-terminfoSkill
- imsg-permissionsSkill
- llm-inference-benchmarkSkill
- lxd-docker-firewall-conflictSkill
- mac-mini-as-headless-serverSkill
- macos-app-multi-instancesSkill
- macos-smb-serverSkill
- mac-smb-automountSkill
- openclaw-diagnoseSkill
- paseo-profilesSkill
- private-fork-syncSkill
- refresh-claude-accountSkill
- ssh-claude-authSkill
- sync-claude-accountsSkill
- to-featuresSkill
- trusted-publishSkill
- ubuntu-lxd-gpu-serverSkill
- ubuntu-nvidia-gpu-enablementSkill
- ubuntu-zfs-mirror-installSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 26
Run the installer: sh ~/.claude/skills/herdr-rename-hook/scripts/install.sh (copies the hook.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Herdr rename hook
One installed script, ~/.claude/hooks/herdr-rename-agent.sh, serves both Claude Code and Codex. Whatever notices the rename, the mirroring onto the calling pane is the same three commands: herdr agent rename (the title slugified to Herdr's agent-name rules), then herdr pane rename and — only when the pane is the first pane of its tab — herdr tab rename (the title as typed, whitespace collapsed; the tab id and the pane order are read live from herdr pane layout). The bundled scripts/herdr-rename-agent.sh is the source of truth — its header carries the mechanism, the slug and collision rules; edit there and re-run install.sh.
Claude Code has no hook event for /rename, but /rename writes the session's custom-title.json sidecar. A SessionStart hook registers that file as a FileChanged watch path (hookSpecificOutput.watchPaths); the FileChanged hook does the renaming.
Codex has no FileChanged event at all and no watchable sidecar — /rename only appends {"id","thread_name","updated_at"} to ~/.codex/session_index.jsonl (append-only, last line for an id wins). So its SessionStart hook spawns a detached watcher that polls that file for its own session id. Two Codex facts shape it:
SessionStartfires on the session's first turn, not at TUI launch, so the watcher starts a turn late and syncs whatever name the session already has.- Codex auto-titles a new thread itself on that first turn (one or two appends within seconds, never again), and those are indistinguishable from a typed
/rename. So a change seen within 60 s of the watcher starting fills in blanks only; after that window a change overwrites, exactly like Claude Code's/rename. The watcher exits when the pane stops hosting that session, when a newer watcher claims the pane (claim file~/.cache/herdr-rename/<pane>.watch), or after 24 h.
Behaviour worth telling the user:
- A tab carries the name of its first pane. A single-pane tab, the usual layout, simply follows its session; in a split tab only the first pane's renames reach the tab, and every later pane relabels itself and leaves the tab title alone. "First" is layout order (
pane layout→.result.layout.panes[0]):tab getexposes no root-pane id,pane listreturns the same geometric traversal, and pane ids are not monotonic with creation order (p1Y,p1Z,p10,p21were created in that order on herdr 0.9.0-preview).pane splitopens onlyrightanddown, so a new pane cannot reach the first slot by splitting — onlypane swaporpane movecan, and after a deliberate reorder the leftmost pane is the one to follow. - Filling in only what is blank — an unnamed agent gets the slug, an unlabelled pane and its tab get the title, anything already set stays — is what happens on Claude
SessionStartwith an existing title (resume, or an old session in a fresh pane) and on Codex's first-turn auto-title. - Clearing the title (
/renamewith no name) changes nothing in Herdr. - A Claude
/renamein the first seconds of a session can be dropped:SessionStartreturns the watch path, butcustom-title.jsonmay be written before Claude Code has armed theFileChangedwatch, and that write is then never reported. Seen once, 2026-09-16, renaming a session prompted immediately afteragent start; the log shows thesessionline with nochangedline after it. Renaming again works, so the fix is to rename again rather than to go looking for a broken hook. - Codex needs
[features] hooks = truein~/.codex/config.toml(the installer reports it if missing), and asks you to trust a new or changed hook the next time it starts — pick "Trust all and continue". Editing the hook's command string re-triggers that prompt; editing the script it points at does not.
Install
- Run the installer: sh ~/.claude/skills/herdr-rename-hook/scripts/install.sh
(copies the hook; merges one SessionStart entry and one FileChanged group into ~/.claude/settings.json and one SessionStart group into ~/.codex/hooks.json — Herdr's own managed entries are left alone; self-checks inside a Herdr pane; done when both
self-check: OKlines andinstalledprint; idempotent — re-run it after editing the hook. Codex absent printscodex: not installed, skipped.)- Another Mac: the skill lives in git (~/github.com/soulmachine/skills), so on that host: cd ~/github.com/soulmachine/skills && git pull && agentstow adopt ~/github.com/soulmachine/skills/herdr-rename-hook && agentstow sync && sh ~/.claude/skills/herdr-rename-hook/scripts/install.sh && sh ~/.claude/skills/herdr-rename-hook/scripts/install.sh --check (adopt is a no-op once the skill is already linked).
- Tell the user: running Claude sessions open /hooks once or restart; Codex asks to trust the hook at its next start; every rename is logged at ~/Library/Logs/herdr-rename-agent.log.
Check or remove: install.sh --check (exit 0 = installed), install.sh --uninstall
Prove it end to end
Only when asked, or after editing the hook. The proof relabels a tab, so use a throwaway tab of your own, never the user's: herdr tab create --workspace "$HERDR_WORKSPACE_ID" --cwd "$PWD" --label hooktest --no-focus, read .result.root_pane.pane_id and .result.tab.tab_id, then herdr agent start hooktest --kind claude --pane <pane> --timeout 120000, herdr agent prompt <pane> "/rename e2e check", and poll herdr agent get <pane> until .result.agent.name is e2e-check; then herdr pane get <pane> must show .result.pane.label and herdr tab get <tab> must show .result.tab.label both equal to e2e check. Address the agent by pane id. Finish by sending /exit, herdr tab close <tab>, and deleting only that session's transcript and folder under ~/.claude/projects/.
For Codex, same shape with --kind codex and four differences: a fresh pane stops on a directory-trust prompt and (after any hook change) a hook-trust prompt — clear them with herdr pane send-keys <pane> enter and … down + … enter, reading the pane with herdr pane read <pane> to see which is up; herdr agent prompt types but does not submit for Codex, so always follow it with herdr pane send-keys <pane> enter; send one throwaway prompt first, because that first turn is what starts the watcher (the log line is codex watch: session=…); and only rename more than 60 s after that line, or the settle window will treat it as Codex's own auto-title and fill blanks instead of overwriting. Then /rename e2e codex and assert e2e-codex / e2e codex as above. Finish with /exit (send-keys enter), herdr tab close <tab>, and remove the [projects."<throwaway dir>"] trust_level stanza the run added to ~/.codex/config.toml.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

