herdr-plugin-renamer: Instructions file for Claude Code

CLAUDE.md

herdr plugin (Rust) that names a herdr pane from the coding agent's first prompt. When the pane is in an auto-generated linked worktree, it also renames the worktree branch and workspace. The naming engine is swappable: on-device Apple FoundationModels by default (a small Swift helper), with a headless Codex call as the automatic fallback.

Architecture

Single binary, two phases (src/main.rs):

• Hot phase (default, every pane.agent_status_changed event): pure env-var reads, no I/O. context::evaluate bails unless the new status is working and this pane does not already have a done marker. On a pass, writes a pane-scoped claim marker and forks the cold phase detached (setsid).
• Cold phase (HERDR_NAMING_PHASE=cold): herdr::poll_agent_session → transcript::read_first_prompt → main::generate_slug (walks the engine::engine_chain; fallback slug::fallback_from_prompt) → herdr::pane_rename. The generated slug is also reported as the task metadata token on the pane and workspace for custom Agent and Space sidebar rows. If the pane is in a linked worktree whose current branch starts with worktree/, git::rename_current_branch renames it to <prefix>/<slug> and only then herdr::workspace_rename renames the workspace to <slug>.

Naming outputs: pane <slug>; branch <prefix>/<slug> (bare <slug> when no prefix is configured; main::compose_branch joins them); workspace <slug> after a successful worktree branch rename. The prefix comes from main::resolve_branch_prefix: HERDR_NAMING_BRANCH_PREFIX env, then a branch-prefix file in HERDR_PLUGIN_CONFIG_DIR, else none.

Foundation-generated slugs should be compact noun-topic labels, not literal sentence summaries. Prefer labels such as current-file over change-selected-file-to-current. The helper must ground labels in the actual prompt and avoid introducing absent concepts from examples or instructions. The default Foundation path is two-pass: generate several candidates, sanitize and dedupe them, then ask FoundationModels to select exactly one candidate from the cleaned list. Codex remains a fallback only when Foundation fails.