agentleFS
soulmachinesoulmachine/skills/herdr-rename-hook/SKILL.md

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.

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
  1. Very specific:

    Run the installer: sh ~/.claude/skills/herdr-rename-hook/scripts/install.sh (copies the hook.

    line 26

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  • SessionStart fires 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 get exposes no root-pane id, pane list returns the same geometric traversal, and pane ids are not monotonic with creation order (p1Y, p1Z, p10, p21 were created in that order on herdr 0.9.0-preview). pane split opens only right and down, so a new pane cannot reach the first slot by splitting — only pane swap or pane move can, 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 SessionStart with an existing title (resume, or an old session in a fresh pane) and on Codex's first-turn auto-title.
  • Clearing the title (/rename with no name) changes nothing in Herdr.
  • A Claude /rename in the first seconds of a session can be dropped: SessionStart returns the watch path, but custom-title.json may be written before Claude Code has armed the FileChanged watch, and that write is then never reported. Seen once, 2026-09-16, renaming a session prompted immediately after agent start; the log shows the session line with no changed line 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 = true in ~/.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

  1. 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: OK lines and installed print; idempotent — re-run it after editing the hook. Codex absent prints codex: 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).
  2. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.