pi-session-name

Auto-name pi sessions with a short LLM-generated title so --resume lists are easy to scan — instead of the raw first message.

Features

• First-mode (default) — names the session once on first agent response, then leaves it alone
• Auto-mode — re-evaluates each turn; the title tracks the current topic
• Never overwrites manual names — detects /name, --name, the resume picker's rename, or any other extension calling setSessionName, and locks itself for the rest of the session
• /rename [name] — rename the current session on demand. With an argument it sets that name; without, it generates one from the conversation
• Language-aware — titles use the same language as your first message
• Distinctive titles — leads with the concrete entity/error/identifier, so similar sessions don't blur together (~15-40 chars)
• Conflict-aware — reads recent sibling session titles from local session storage and injects them into the prompt, so a new title never duplicates or rewords one already in the list
• Graceful failure — model unavailable or no API key? Stays silent, never blocks the session

Prerequisites

• pi >= 0.80.0 (uses agent_settled / session_info_changed events)

Installation

As a pi package (recommended)

# Global (user) install
pi install @fyeeme/pi-session-name

# Project-local (.pi/settings.json)
pi install -l @fyeeme/pi-session-name

# Try once without saving
pi -e @fyeeme/pi-session-name

Manual (development)

# Clone the repo
git clone https://github.com/fyeeme/pi-packages.git
cd pi-packages/packages/extensions/pi-session-name

# Symlink to pi extensions
ln -s "$(pwd)" ~/.pi/agent/extensions/pi-session-name

Usage

No configuration needed for the default first mode. Just install and use pi — your first session will auto-name itself.

Tip: in first mode the session is named after the first turn, so if the root cause or key point usually emerges only in later turns, set "mode": "auto" — the title then re-evaluates each turn and tracks the conversation's conclusion.

If you want to change behavior, see Configuration.

Commands

Command	Description
/rename <name>	Rename session to <name> and lock out auto-naming
/rename	Generate a descriptive name from the current conversation

Note: /rename is a manual action — once used, auto-naming is locked for the rest of the session. This is consistent with pi's built-in /name command.

Configuration

Create .pi/session-name.json in your project root:

{
	"mode": "auto",
	"maxLength": 200,
	"model": { "provider": "openai", "id": "gpt-4o-mini" }
}

Options

Option	Default	Env override	Description
mode	"first"	PI_SESSION_NAME_MODE	"first" — name once; "auto" — re-evaluate each turn
maxLength	200	PI_SESSION_NAME_MAX_LENGTH	Character cap for generated titles
enabled	true	PI_SESSION_NAME_ENABLED=false	Master switch to disable auto-naming
model	current session model	PI_SESSION_NAME_MODEL_PROVIDER + PI_SESSION_NAME_MODEL_ID	Override the model used to generate titles

By default the extension uses the model you're already chatting with (ctx.model), so no extra API key is needed.

Environment variables only

If you prefer environment variables over a config file:

export PI_SESSION_NAME_MODE=auto
export PI_SESSION_NAME_MAX_LENGTH=150
export PI_SESSION_NAME_ENABLED=true
export PI_SESSION_NAME_MODEL_PROVIDER=openai
export PI_SESSION_NAME_MODEL_ID=gpt-4o-mini

How it works

1. On agent_settled (after the first turn completes), the extension builds a condensed text of the conversation
2. It asks the LLM (same model as the session, unless overridden) to generate a descriptive title
3. The title is set via pi.setSessionName(), which updates the resume picker immediately
4. In first mode, it stops there. In auto mode, each subsequent turn re-evaluates: the LLM returns either KEEP or a new title
5. If a manual rename is detected (session_info_changed with a name the extension didn't set), auto-naming locks permanently

Smoke test

# 1. Fresh session with auto-naming
pi -e @fyeeme/pi-session-name
# Ask a question, wait for reply → resume picker shows a generated title

# 2. Manual rename protection
/name foo
# Chat a few turns → name stays "foo" (locked)

# 3. Auto mode: topic tracking
# Set mode to "auto", shift topic across turns → name updates; same topic → stays

# 4. /rename command
/rename foo    # → name is "foo", locked
/rename        # → generates a fresh name from the conversation

# 5. Graceful degradation (unset model's API key)
# → No errors, session runs normally

API (for extension developers)

This extension exposes utilities that other extensions can import:

import {
	buildConversationText,
	cleanTitle,
	buildFirstPrompt,
	buildAutoPrompt,
	loadConfig,
	generateTitle,
	parseSessionTitle,
	collectRecentSessionTitles,
} from "@fyeeme/pi-session-name";

See index.ts for complete type signatures.

Changelog

See CHANGELOG.md.

License

MIT