herdr-plugin-renamer

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

herdr-plugin-renamer

★ 13 Open GitHub ↗

LLM-powered session naming for herdr: Claude Code / Codex / Grok / Pi / opencode, Chinese or English tab labels, free opencode zen engine by default

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# herdr-plugin-renamer

A [herdr](https://herdr.dev) plugin that gives every agent session a meaningful
name, generated by an LLM from the agent's **first prompt**. Tabs stop being a
wall of `zsh` / `claude` / `codex` and start telling you what each session is
actually doing.

Supports **Claude Code, Codex, Grok, Pi, and opencode** sessions, English or
Chinese labels, and a pluggable chain of naming engines. The default path tries
Pi's configured model first, then multiple free OpenCode Zen models.

Based on [wyattjoh/herdr-plugin-renamer](https://github.com/wyattjoh/herdr-plugin-renamer),
extended with multi-agent support, tab/agent rename targets, CJK labels,
additional engines, and session-scoped renaming.

## Quick install

```sh
herdr plugin install wenhanweime/herdr-plugin-renamer
```

Then install the herdr integration for each agent you use (this is how herdr
learns the agent's native session id):

```sh
herdr integration install claude
herdr integration install codex
herdr integration install pi
herdr integration install opencode
```

Grok needs no integration: its session is recovered from
`~/.grok/active_sessions.json` automatically.

Requirements: herdr 0.7.4+ on macOS or Linux, a Rust toolchain (the install
builds from source), and the `pi` and `opencode` CLIs on PATH for the default
naming chain. macOS additionally builds an optional Apple FoundationModels
helper.

## What it does

When an agent in a pane starts working on its first prompt, the plugin:

1. Resolves the agent's native session and reads the first genuine user prompt
   from the agent's own transcript (context wrappers and slash-command noise
   are filtered out).
2. Asks a naming engine for a short task name (and an ASCII branch slug).
3. Renames targets when configured. With the default `tab` target (non-worktree
   panes), the Chinese/English **title goes on the workspace** (herdr 0.7.4's
   only bright Agent-sidebar token) and the **tab gets the folder basename**
   (dim second row). Recommended sidebar layout:

```toml
   [ui.sidebar.agents]
   rows = [
     ["state_icon", "workspace"],  # title, white/bold
     ["agent", "tab"],             # agent · folder, dim
   ]
   ```

A prompt like "给登录页面加上手机号验证码登录" becomes workspace
   `手机验证码登录` in `zh` mode, or `phone-otp-login` in English mode.
   Note: multi-tab siblings share one workspace label (last writer wins).
   `$task` metadata is still published, but paints dim in herdr 0.7.4, so it
   is a poor choice for the top title row until per-token styles land.

4. Publishes the name as `task` metadata, available as `$task` in custom
   Agent and Space sidebar rows.

5. In an auto-generated linked worktree (branch starting with `worktree/`), it
   also renames the git branch to the ASCII slug — locally, never pushed — and
   then the workspace (skipping the title-on-workspace step so the slug wins).

Renaming is **session-scoped**: a new agent session in a long-lived pane gets
a fresh name; repeat events for the same session are no-ops. Every path fails
open — naming can never block herdr.

## Configuration

Config knobs are single-value files in
`$(herdr plugin config-dir herdr-plugin-renamer)/`, each with a matching env
var that takes precedence (env vars must be visible to the herdr server).

| Knob (file / env)                                | Default                           | Purpose |
| ------------------------------------------------ | --------------------------------- | ------- |
| `engine` / `HERDR_NAMING_ENGINE`                 | `pi,opencode`                     | Naming agents in fallback order; `claude`, `codex`, and `foundation` remain available when explicitly selected |
| `pi-models` / `HERDR_NAMING_PI_MODELS`           | Pi's configured default model      | Comma/newline-separated `provider/model` fallback list; `default` uses Pi's own selection |
| `opencode-models` / `HERDR_NAMING_OPENCODE_MODELS` | three free OpenCode models       | Comma/newline-separated free-model fallback list |
| `opencode-model` / `HERDR_NAMING_OPENCODE_MODEL` | unset                              | Legacy single-model override, used only when the plural setting is absent; `default` uses OpenCode's own selection |
| `style` / `HERDR_NAMING_STYLE`                   | `en`                              | `zh` = Chinese labels + ASCII branch slug (one engine call returns both) |
| `targets` / `HERDR_NAMING_TARGETS`               | `tab`                             | Comma-separated subset of `pane,tab,agent` to rename |
| `branch-prefix` / `HERDR_NAMING_BRANCH_PREFIX`   | none                              | Prefix for renamed worktree branches (`you/fix-cache`) |
| `HERDR_NAMING_OPENCODE_BIN` / `HERDR_NAMING_CLAUDE_BIN` / `HERDR_NAMING_CODEX_BIN` / `HERDR_NAMING_FOUNDATION_BIN` | auto | Engine binary overrides (standard install paths are probed, since the herdr server often runs with a minimal PATH) |
| `HERDR_NAMING_CLAUDE_MODEL`                      | unset                             | Optional `--model` for the claude engine |
| `HERDR_NAMING_GROK_DIR`                          | `~/.grok`                         | Grok home for session/transcript lookup |

Example — Chinese tab names (labels in Chinese, branches stay ASCII):

```sh
echo zh > "$(herdr plugin config-dir herdr-plugin-renamer)/style"
```

## Naming engines

The engine chain is tried in order; the first success wins, and a
deterministic local fallback guarantees a name even when every engine fails
(CJK prompts keep a readable excerpt as the label).

- **pi** (default): ephemeral, tool-free `pi --print` calls. By default it uses
  Pi's configured model; when `pi-models` is set, models are tried in order
  until one returns a valid title and branch slug.
- **opencode** (default fallback): headless `opencode run`; several free Zen
  models are tried in `opencode-models` order.
- **claude**: headless `claude -p`, uses your existing Claude Code auth/relay.
- **codex**: headless `codex exec` (`gpt-5.5`, needs direct OpenAI access).
- **foundation** (macOS): on-device Apple FoundationModels via a bundled Swift
  helper — no network, needs macOS 26+ on Apple Silicon with Apple
  Intelligence enabled.

Default chain on every platform: `pi (configured default or model list) →
opencode (multiple free models) → deterministic local fallback`. Claude,
Codex, and Foundation run only when explicitly included in `engine`.

## 中文说明（简）

给 herdr 里的每个 agent 会话自动起名：读取会话的第一条用户消息，用大模型
总结成短标签（默认先用 Pi 当前模型，再尝试 OpenCode Zen 免费模型）。

```sh
herdr plugin install wenhanweime/herdr-plugin-renamer
herdr integration install claude   # 按需：codex / pi / opencode
CFG=$(herdr plugin config-dir herdr-plugin-renamer)
echo zh       > "$CFG/style"    # 中文标签（worktree 分支名仍为英文 slug）
echo 'pi,opencode' > "$CFG/engine"
```

支持 Claude Code / Codex / Grok / Pi / opencode。Grok 无需集成，自动通过
`active_sessions.json` 反查会话。同一 pane 里每开一个新会话都会重新命名。

在 `targets` 含 `tab` 时（默认）：中文标题写到 **workspace**（侧栏唯一亮色
token），tab 写目录名；另会发布 `$task` 元数据。建议侧栏：

```toml
[ui.sidebar.agents]
rows = [["state_icon", "workspace"], ["agent", "tab"]]
```

`pi-models` 和 `opencode-models` 支持逗号或换行分隔；先在 Pi 内逐模型
fallback，再在 OpenCode 内逐个尝试免费模型。

## Local development

```sh
cargo test                                            # unit tests
cargo build --release                                 # plugin binary
swift build -c release --package-path naming-helper   # macOS on-device helper
herdr plugin link "$PWD"                              # use the local build
```

`herdr plugin link` does not run build steps, so build first (or use
`just build && just link`). See [CONTRIBUTING.md](CONTRIBUTING.md) for the
complete development and test workflow.

## Credits & license

Forked from [wyattjoh/herdr-plugin-renamer](https://github.com/wyattjoh/herdr-plugin-renamer);
the hot/cold event architecture, worktree renaming, and the FoundationModels
helper are his work. [MIT](LICENSE).

herdr-plugin-renamer

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README