pi-autoname

✨ What it does

🚀 Install

pi install npm:pi-autoname

Works out of the box. No configuration needed — uses your current session's model by default.

Animated terminal title

Working:  π - ⠋ - Database retries
          π - ⠙ - Database retries
          π - ⠹ - Database retries
Idle:     π - Database retries

The marker cycles through ten Braille frames every 120 ms. It starts during agent preparation and stays active through reasoning, streaming, tool calls, retries, and queued follow-ups until agent_settled. Background naming and /autoname model calls are also tracked, independently of the main agent. Escape clears main-agent activity at settlement; background naming may continue until completion or its own cancellation. Cancellation of naming releases its marker immediately; shutdown, session replacement, and reload clear timers and reject stale updates.

The displayed title is the session name, or the working-directory basename until one is available. The animation only updates the terminal title through ctx.ui.setTitle(); it never renames the session, writes animation frames into history, or makes additional model requests. Manual /name changes update the displayed title immediately. Control characters are removed before sending a title to the terminal.

This is TUI-only: print, JSON, and RPC modes never emit spinner title updates. Set "titleSpinner": false and run /reload to leave terminal titles entirely to Pi or another extension. The spinner remains available when "enabled": false disables AI naming. Avoid running a second title-owning extension alongside it. The terminal must accept application-provided titles; a terminal-side fixed tab-title override can hide the animation.

⚙️ Configuration

Config file is auto-generated on first use at ~/.pi/agent/pi-autoname.json:

{
  "enabled": true,
  "titleSpinner": true,
  "model": "",
  "fallbackModels": [],
  "language": "auto",
  "cooldownMinutes": 10,
  "debug": false,
  "respectManualName": false,
  "includeCustomMessages": false
}

Example: Model fallback chain

{
  "enabled": true,
  "model": "minimax-cn/MiniMax-M2.7",
  "fallbackModels": [
    "xiaomi-token-plan-cn/mimo-v2-omni"
  ],
  "cooldownMinutes": 10
}

This tries models in order: MiniMax-M2.7 → mimo-v2-omni → session model.

For example, "model": "xai/grok-4.6:low" selects the model with Pi’s unified reasoning: "low" option. Supported suffixes are minimal, low, medium, high, xhigh, and max; unknown suffixes remain part of the model ID. Authentication, provider routing, cancellation, and the shared 30-second budget still belong to the same host runtime path.

Example: Name worker sessions from injected assignments

When a pi extension is used to coordinate agents, relevant context information may be injected into the chat history as a custom_message (e.g. via pi.sendMessage(..., { customType: "my-pi-orchestrator" })) rather than as a typed user message. By default, custom messages are ignored by pi-autoname. By whitelisting the relevant message types, we can ensure that the inferred name takes the relevant context into account:

{
  "includeCustomMessages": ["my-pi-orchestrator"]
}

Matching entries with text are treated as user turns: they keep their chronological position in the recent-context window, count toward it, can serve as the first user turn, and take part in language detection. Entries without text do not count toward the recent window or the initial-history check. The entry's display flag is ignored, because hidden messages still reach the model.

🏗️ How it works

Automatic naming

first textual request/response pair (message_end)
        ↓
AI generates an initial name in the background
        ↓
agent continues working, including tool calls
        ↓
agent_settled → reconsider the name using recent task context

The initial pass does not wait for tools to finish. Tool-only, thinking-only, failed, and cancelled responses do not trigger it. One refinement at settlement bypasses the usual cooldown and keeps the existing name when it still fits; subsequent updates use the normal cooldown. A first task can therefore use two naming passes. The settled pass cancels any still-running initial request, and late results cannot overwrite its name.

A pending refinement survives reload once an initial name has been saved. /name or /autoname cancels that refinement; manual-name protection and the normal grace period still apply. If no early name could be attempted, naming at settlement remains available. Older unmarked sessions continue to use recent context rather than an obsolete opening exchange.

Periodic re-naming

agent_settled event (all retry/follow-up work complete)
        ↓
cooldown passed? (10 min default)
        ↓
AI checks recent context against the current name
        ↓
topic changed? → silently update
name still fits? → keep it

Model fallback chain

primary model (from config)
        ↓ failed within the shared 30-second budget?
fallback models (from config)
        ↓ failed?
session model (automatic)
        ↓ failed?
smart text extraction (no AI)

Manual naming

/autoname

Regenerates the session name from recent conversation context. Useful when you want to force an immediate rename.

Built-in /name is largely redundant

Pi's native command still works:

/name My custom title

With the default respectManualName: false, pi-autoname gives /name a full cooldownMinutes grace period, then may resume automatic naming if the topic changes. It observes the name change immediately through Pi's session metadata event.

• For a one-shot rename that pi-autoname may later take over again: use /name.
• To force a re-name from the current conversation right now: use /autoname.
• To keep a /name indefinitely: set respectManualName: true. Running /autoname remains an explicit override.

Stable periodic names

Every naming pass identifies the newest relevant task and outcome first. The old name is only a wording reference: it is kept when it still accurately describes that task, avoiding meaningless rewording, and replaced when the task or conclusion has changed. Later findings can come from an assistant summary or a tool result; earlier cancelled or superseded tasks do not control the name.

Recent naming context includes up to six user/assistant text messages, with the latest user goal retained during long tool work, plus up to two latest text tool results after that goal. Custom messages still follow includeCustomMessages. Tool evidence does not determine the naming language and is never used as a local fallback title. Each text is redacted before excerpting; long texts preserve both their beginning and their conclusion within a 700-character budget. The first-response snapshot for a fresh session remains the initial request/response pair.

The 10-minute default cooldown is unchanged: later automatic checks happen at settlement once the cooldown has elapsed, not after a fixed message count. The one-time first settlement check still bypasses it.

🔐 Privacy note

pi-autoname sends a short, recent conversation excerpt and up to two recent text tool-result excerpts to the selected naming model. Tool results can contain file contents, command output, or retrieved information, so that text now participates in naming even when the assistant does not repeat it. Non-text tool content is excluded; tool instructions are treated as untrusted quoted data. With includeCustomMessages enabled, that excerpt also contains the matching extension-injected messages, including messages with display: false. Before sending, it redacts common secret patterns such as API keys, bearer tokens, AWS access keys, private keys, *_TOKEN / *_SECRET / *_PASSWORD environment assignments, and quoted JSON credential fields (including escaped string values). Redaction is pattern-based and cannot guarantee detection of every sensitive value or encoding. If the AI call fails and the user text contained a detected secret, the local fallback name is skipped to avoid turning secrets into session names. Debug logs contain status events and selected diagnostic metadata only; session names, conversation text, file paths, and raw provider/configuration errors are not logged.

🌍 Language support

Set "language": "zh-CN" (or another BCP 47 locale) to explicitly choose the language of AI names. Invalid values fall back to "auto". This setting is a model instruction; local fallback extraction cannot translate the user’s text.

With the default "language": "auto", names use the dominant natural language in user messages: the first user message for initial naming, and recent user messages for periodic or manual naming. Assistant responses, paths, URLs, and code snippets do not determine the language. A user message that contains any Han / Kana / Hangul characters is treated as a CJK-language message, so English noise co-injected into the same turn (system warnings, error logs, tool output) cannot outweigh the user's CJK intent; only purely-Latin user messages contribute to the English score. When no natural-language user text is available, pi-autoname optionally uses the active pi-di18n /lang locale; pi-di18n is never required.

🔗 Related

• pi-compaction-i18n — localized compaction summaries

Development

The repository has no development dependency. With Node.js 22.19.0 or later (Node.js 22.22.3 is the current integration baseline), run the built-in TypeScript test runner directly:

npm test

Pi provides the two declared peer dependencies (@earendil-works/pi-ai and @earendil-works/pi-coding-agent, both ^1.4.0) at extension runtime. The current integration baseline is Pi 1.4.0 (Node.js 22.22.3). Naming calls use ctx.modelRegistry.streamSimple().result() so Pi resolves provider authentication, including providers that do not require an API key.

An additional offline check uses the installed Pi loader, runner, session manager, and model runtime with an in-memory test provider:

PI_HOST_ROOT="$(npm root -g)/@earendil-works/pi-coding-agent" node tests/pi-host-smoke.mjs

This checks automatic/manual naming, reload state, redaction, failure fallback, TUI animation, final settlement, shutdown cleanup, and RPC silence without using personal credentials or external models. On Linux/macOS, an additional Python 3 PTY test exercises early naming during a gated tool, settlement refinement, real terminal-title output, /name, /reload, and Escape cancellation:

PI_HOST_ROOT="$(npm root -g)/@earendil-works/pi-coding-agent" python3 tests/pi-tui-smoke.py

An additional real AgentSession check verifies that the first title appears while a fixture tool is still running, animation stays active during early naming and refinement, and the final title becomes idle after settlement:

PI_HOST_ROOT="$(npm root -g)/@earendil-works/pi-coding-agent" node tests/pi-early-naming-smoke.mjs

Set PI_HOST_ROOT to the actual installed package directory if Pi is managed outside global npm. These checks use offline providers, not live-model or graphical-terminal acceptance tests. See compatibility evidence and limits.

AI replies use the first nonempty text line, or the last nonempty thinking line when no text was returned, and share the same 30-character limit as local fallback labels. The quality gate checks length and basic sentence patterns; it cannot guarantee that a model’s chosen line is semantically useful.

Contributors

Thanks to @git-geeky for the name-quality fixes in PR #2, @LoveSnowEx for the lazy-session diagnostic fix in PR #3, and @chuxubank for thinking-suffix support in PR #7. These contributions are adapted to Pi’s current host runtime.

Thanks to Luca Mondada (@lmondada) for contributing opt-in custom-message context through PR #8. His includeCustomMessages setting lets extension-injected assignments inform session names, with support for selecting specific customType values.

Thanks to @jack-o-mania for the terminal-title animation in PR #10 and early session naming with settlement refinement in PR #11.

License

MIT