pi-auto-rename

AI session naming for pi: derives a short core-goal title from the session's original intent and applies it via pi.setSessionName().

# before: session-2026-08-21-2218
# after:  auto-rename 扩展拆分

Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Commands
• How It Works
• Development
• Troubleshooting
• License

Features

• Core-goal titles, not activity labels: the title names what the session is accomplishing, derived only from the ORIGINAL INTENT (earliest substantive user prompts). Later pastes, spec dumps, and quoted material can never crowd the core out.
• Anchor + delayed lock: once a core is derived from substantive intent it is locked; periodic refreshes reuse it verbatim with no model call. Junk cores self-heal on the next refresh.
• Quality gates: greeting/ack openers are skipped, procedural labels ("Issue list triage") and non-goal cores ("方案确认") are rejected and backed off to the next cycle. A forced /autorename degrades instead of rejecting: the meta filter is skipped and non-goal cores are accepted with a warning, so a quality-gate hit never blocks a title.
• Manual-rename protection: an out-of-band name change pauses the session so the extension never fights the user.
• Secret redaction: 6 patterns (private keys, AWS keys, API keys, bearer tokens, KEY=value assignments) before anything is sent to the model.
• LLM via pi's model registry (deepseek/deepseek-v4-flash by default) — API keys stay in pi's keychain, never read from dotfiles.
• agent-board sync: mirrors the name into the agent-board view's meta.json (absorbed from agent-board-name-sync).
• Zero dependencies beyond pi itself: pure title logic lives in lib/ and is unit-tested without a test framework.

Requirements

• pi ≥ 0.84 recommended. The extension uses pi.setSessionName(), pi.appendEntry(), pi.getSessionName(), and the agent_settled, session_start, session_shutdown, and session_info_changed events; on older builds these degrade to best-effort no-ops rather than crashing.

Installation

From npm (recommended)

pi install npm:@zhuxixi/pi-auto-rename

Then run /reload in pi (no restart needed).

To update later:

pi update --extensions

To remove:

pi remove npm:@zhuxixi/pi-auto-rename

From source

Clone the repository into a subdirectory of pi's global extensions dir:

git clone https://github.com/zhuxixi/pi-auto-rename.git ~/.pi/agent/extensions/pi-auto-rename

Configuration

The config file is created automatically on first load at ~/.pi/agent/auto-rename.json:

Key	Default	Meaning
enabled	true	Master switch
model	"deepseek/deepseek-v4-flash"	provider/modelId in pi's model registry
firstAfterMin	5	Core-lock delay: the title appears at the first settle and stays re-derivable until the session is this old
repeatEveryMin	3	Re-rename cadence after the first rename
maxCoreWidth	24	Core-goal cap in display columns (CJK counts 2)
debug	false	Verbose logging to stderr
lang	"auto"	Forced title language: "zh" / "en" / "auto" (default — follows the session's original intent). Invalid values fall back to "auto". Applies to newly generated and /autorename-forced titles only

Edit the file and run /reload to apply.

Commands

Command	Effect
/autorename	Force a rename now (bypasses cooldown, pause, and core lock; re-derives with latest context)
/autorename-pause	Pause auto-rename for this session
/autorename-resume	Resume auto-rename for this session
/autorename-status	Show current state (title, core, locked, paused)

How It Works

1. On the first agent_settled that has user content, the extension names the session immediately (no wall-clock wait); after that it re-checks every repeatEveryMin. The core locks once the session is firstAfterMin old, so early titles stay correctable. A session that ends first gets one final attempt on session_shutdown, and a never-named session is named when it is reopened.
2. It scans the transcript for the first substantive user prompts (greetings/acks skipped) — the session's ORIGINAL INTENT.
3. Secrets are redacted, then the excerpt is sent to the configured model with a strict title-generation prompt; the configured lang forces the title language ("auto" follows the original intent).
4. The output passes quality gates (not a sentence, not a response, not a procedural label), is capped to maxCoreWidth display columns, and applied via pi.setSessionName(). On /autorename the ambiguous meta filter is skipped and non-goal cores fall back to a warning instead of an empty rejection.
5. State (lastRunEpoch, lastSetTitle, lastCore, coreLocked, paused) lives in the session file as auto-rename-state custom entries, so it survives reloads.

Issue evidence (issue #7): the extension also scans tool calls and their results for a GitHub issue "under work" — gh issue view output parsed for title/number pairs, plus claim/branch/research-path signals scored per issue. A unique mutate claim on the top-scoring issue wins outright (one write operation rules out ambiguity); otherwise the top must lead the runner-up by 2x. When evidence wins, it is injected into the title prompt as a high-weight block that requires the core to condense the issue's subject, and a new evidence key overrides the core lock for exactly one re-derive — so existing stage-label titles (issue认领处理-style) self-heal. Sessions with no issue evidence are untouched and derive titles exactly as before.

Development

./test/run-all.sh   # bundles test/*.test.ts with esbuild and runs them

After editing, run /reload inside pi to hot-reload the extension.

Troubleshooting

• Titles stop updating: check /autorename-status — the session may be paused (manual rename detected) or the core may be locked (that's by design: periodic refreshes reuse the locked core without a model call). /autorename forces a re-derive — it bypasses the lock and includes the latest user messages, so a drifted title can be regenerated.
• /autorename reports "quality gate flagged core …": the model produced a non-goal label (e.g. "方案确认"), but force mode still set a title from it. Use /name to set your own, or run /autorename again; the next background refresh re-derives the core anyway.
• No rename happens at all: check enabled in ~/.pi/agent/auto-rename.json, and that the configured model is available in pi's model registry (pi models).
• Debug logging: set debug: true in the config and reload; messages are printed to stderr with the [auto-rename] prefix.

License

MIT