@normful/pi-auto-name

[!TIP] Documentation in: 简体中文 · 繁體中文 · 日本語 · 한국어 · Português · Español · Deutsch · Français · Bahasa Indonesia · Tiếng Việt · Türkçe · Polski · Українська · فارسی · العربية · हिन्दी · Italiano · Nederlands · ไทย

Automatically names your Pi session and terminal multiplexer surfaces from the conversation.

Supports renaming a herdr pane or herdr tab containing Pi:

Also supports renaming a tmux window containing Pi:

And supports renaming a zellij pane or zellij tab containing Pi:

Various languages are supported too, such as Japanese:

Installation

pi install npm:@normful/pi-auto-name

Usage

The extension is fully automatic; there is nothing to run.

Configure it once, and that's it. Set it and forget it.

How It Works

After the first user input (or the first agent_settled event — see config below), it renames the Pi session and renames the containing:

• tmux window
• herdr pane and herdr tab
• zellij pane and zellij tab

Additionally, you can also configure it to continually rename as the conversation evolves, by configuring reRenameEveryNTurns.

Configuration

Save config to either:

• Globally: ~/.config/pi-auto-name/config.json (respects XDG_CONFIG_HOME)
• Per-project override: .pi/pi-auto-name.json

Full default configuration:

{
  "enabled": true,
  "initialRenameTrigger": "first-input",
  "language": "en",
  "namingContextDepth": "recent-user-messages",
  "namingModel": "",
  "namingStyle": "natural",
  "replaceExistingName": "always",
  "reRenameEveryNTurns": 0,
  "respectExternalRenames": true,
  "sessionNameMaxLength": 200,
  "skipSessionNameDedup": false,
  "surfaces": {
    "renameHerdrPane": true,
    "renameHerdrTab": true,
    "renamePiSession": true,
    "renameTmuxWindow": true,
    "renameZellijPane": true,
    "renameZellijTab": true
  },
  "windowNameMaxLength": 30
}

Every configuration key is optional.

Configuration Reference

Key	Type	Default	Meaning
enabled	boolean	true	false disables this extension entirely.
initialRenameTrigger	string	"first-input"	When the first rename fires:"first-input" — after you send first prompt"first-agent-settled" — after the first LLM run finishes (after the first agent_settled event).
language	string	"en"	One of: "en", "es", "de", "fr", "it", "nl", "pt", "pt-BR", "pt-PT", "id", "vi", "tr", "pl", "uk", "fa", "ar", "hi", "zh", "zh-CN", "zh-Hans", "zh-Hant", "zh-TW", "zh-HK", "ja", "ko", "th"
namingContextDepth	string	"recent-user-messages"	How much of the conversation to send to LLM in each renaming prompt:"first-user-message" — only the first user message"recent-user-messages" — first user message plus the last 3 user messages"full-conversation" — the whole conversation (users, assistants, tool calls & results), capped to ~60k chars keeping both the opening (core intent) and the latest tail
namingModel	string	""	provider/modelId override for the naming LLM call. Example: "openrouter/nvidia/nemotron-3-nano-30b-a3b:free". Leave empty to use your configured Pi default model and provider.
namingStyle	string	"natural"	The naming style used for both names:"natural" — free-form sentence"slug" — lowercase kebab-case."topic-project" — <topic>｜<project>, project derived from current working directory
replaceExistingName	string	"always"	When to overwrite an existing Pi session name, tmux window name, herdr pane/tab name, zellij pane/tab name:"always" — always overwrite"never" — never overwrite
reRenameEveryNTurns	integer	0	Re-rename every N turns (every N agent_settled events). 0 never re-renames.
respectExternalRenames	boolean	true	When true, disables this extension's renaming after an external rename is detected (e.g. after you manually run /name)
sessionNameMaxLength	integer	200	Max character limit for the Pi session name.
skipSessionNameDedup	boolean	false	true skips sending existing Pi session names into the renaming prompt. false (default) sends up to 15 existing session names as names to avoid duplicating.
surfaces.renamePiSession	boolean	true	false disables renaming of Pi session
surfaces.renameHerdrPane	boolean	true	false disables renaming of the herdr pane Pi is running in
surfaces.renameHerdrTab	boolean	true	false disables renaming of the herdr tab this process runs in.
surfaces.renameTmuxWindow	boolean	true	false disables renaming of the tmux window this process runs in.
surfaces.renameZellijPane	boolean	true	false disables renaming of the zellij pane this process runs in.
surfaces.renameZellijTab	boolean	true	false disables renaming of the zellij tab this process runs in.
windowNameMaxLength	integer	30	Max chars for every terminal/frame window name (herdr pane/tab, tmux window, zellij pane/tab). One of the two length knobs.

Debugging

Set PI_AUTO_NAME_DEBUG=1 and the extension will both append structured pi-auto-name:debug entries to the session transcript and render them in the TUI. (The debug entries are not sent to the LLM.)

Inspiration

This extension is inspired by several other similar extensions:

• https://github.com/ssdiwu/pi-autoname
• https://github.com/byteowlz/pi-agent-extensions/tree/main/pi-auto-rename
• https://github.com/mkioutcc/pi-title-renamer
• https://github.com/default-anton/pi-tmux-window-name