pi-session-namer

An automatic session naming extension for Pi.

This is a fork of joshua-zyy/pi-session-namer, published to npm as @someok/pi-session-namer. It carries fixes that are not merged upstream.

It names and periodically updates Pi sessions based on the current conversation, using the following format:

MMDD｜Type｜Topic｜Progress

Examples:

0310｜Fix｜Handle OAuth callback errors｜testing
0310｜修复｜处理 OAuth 回调错误｜待审查

The optional progress segment shows where the task currently stands, so you can recall not only what a session is about but also how far it has gone.

中文文档 / Chinese documentation

Features

• Automatically names a session after the first agent run settles.
• Re-evaluates the current task after compaction.
• Periodically checks for a substantial task change without calling the model every turn.
• Keeps the session creation date stable when the topic changes.
• Uses English for extension commands, status messages, warnings, and errors.
• Generates the type, topic, and progress in the conversation's primary language (or a language you configure).
• Shows an optional progress segment (max 16 characters) that is kept up to date as the task advances.
• Lets you customize the name format, type list, and naming language.
• Uses the operating system timezone by default, with IANA timezone overrides.
• Uses the current primary agent model by default, with an optional dedicated naming model.
• Inherits the primary agent's thinking level by default, with an optional fixed level.
• Treats a user-set /name as a manual name and locks automatic updates.
• Persists naming state and a short name history in the session.

Installation

Install from the local repository while developing:

pi -e ./src/index.ts

Install as a Pi package from npm:

pi install npm:@someok/pi-session-namer

Install as a Pi package from Git:

pi install git:github.com/someok/pi-session-namer

Restart Pi or run /reload after installation or source changes.

Do not install this package and the upstream pi-session-namer at the same time. Both use the same configuration file (~/.pi/agent/session-namer.json) and the same session entry type, so they would overwrite each other's state.

Commands

Automatic updates are skipped while a session is locked.

Configuration

On first load, the extension creates this global configuration file if it does not already exist:

~/.pi/agent/session-namer.json

It never overwrites an existing file. The default configuration is:

{
  "model": "inherit",
  "thinkingLevel": "inherit",
  "timeZone": "auto",
  "checkEveryTurns": 4,
  "nameFormat": "{date}｜{type}｜{topic}｜{progress}",
  "types": ["Feature", "Design", "Fix", "Optimization", "Release", "Exploration", "Documentation", "Research"],
  "nameLanguage": "auto"
}

A complete example is available in session-namer.example.json.

Configuration options

Configuration is loaded when the extension starts. Run /reload after editing the file.

Thinking levels

Supported configuration values are:

off, minimal, low, medium, high, xhigh, max, inherit

inherit reads the primary agent's current level when naming is triggered. The extension uses Pi's model metadata and known provider formats where available; unsupported levels are reduced to the nearest supported level, and unsupported provider-specific parameters are omitted rather than fabricated.

Naming behavior

The naming model may return only one of:

SKIP
Type｜Topic

• SKIP leaves an unnamed session unnamed, or leaves the current name unchanged. It is honored only during automatic checks; a manual refresh always produces a name.
• Type｜Topic is combined with the program-generated session date.

If a manual refresh cannot produce a name, the notice states why: no conversation content, a provider error (with the provider's own message), an empty model response, or a model that declined to pick a task.

The semantic type categories default to Feature, Design, Fix, Optimization, Release, Exploration, Documentation, and Research. The model expresses the selected category in the naming language; you can customize the list via the types config.

The naming model always describes the task with segments; the extension itself decides whether anything changed by comparing the segments with the previous ones:

• No change → nothing happens (no rename, no history entry).
• Only the progress changed → the name is updated silently.
• The type or topic changed → the name is updated (first naming and manual refresh show a notification).

When the name format contains {progress}, the model also outputs a short progress status (at most 16 characters) anchored to the latest evidence in the conversation. The optional progress segment shows where the task currently stands, so you can recall not only what a session is about but also how far it has gone.

The prompt asks the model to keep the same name for ordinary progress and only rename when the main task changes substantially.

A plain refresh may reuse the existing type and topic; adding force (or any other text) re-evaluates them from scratch and can carry your own requirement, for example /session-name-refresh force write the type in Chinese. The requirement is injected with the highest priority, but it cannot override the output format or the type whitelist, and it never bypasses a lock.

Naming context is limited to current session text, compaction summaries, and tool names. Tool arguments and tool results are not sent. The extension does not perform additional sensitive-data redaction; choose a provider according to your privacy requirements.

Development

Install development dependencies and run the checks:

npm install
npm test
npx tsc --noEmit

Unit tests do not call a real provider or require an API key.

License

MIT. See LICENSE.