# session-rename

Automatic short session names for Pi.

## Install / load

Loaded through the root pi-ext package.
See [root README](../../README.md).

## Commands / tools / settings

- Command:
  `/session-rename [name]`
  - no args:
    force a model pass to generate/refine the session name
  - with args:
    set the exact session name and lock it as user/manual
- Tools:
  none
- Settings:
  `session-rename.idleDelayMs`, see [Settings](#settings)
- Hooks:
  `session_start`, `turn_end`, `turn_start`, `input`, `agent_start`,
  `session_shutdown`

## Behavior

- Generates 1–3 word session names from current branch activity.
- Runs 700 ms after session load and `session-rename.idleDelayMs` (default 10 s) after turn end.
- Cancels pending work when input, turn, or agent activity starts.
- Requires meaningful branch activity:
  user text plus assistant text or tool calls.
- Uses current model through Pi model registry; skips when no model or API key
  exists.
- Preserves manual names.
  Automatic renames stop after user-set or cleared names.
- Refines only extension-generated names.
- Cooldown grows with user turns:
  1 turn early, then 2, then 5.
- Records `session-rename` custom entries for auto-title revisions and user
  locks.
- Builds naming context from current name, initial user goals, recent summaries,
  recent messages, and tool calls.
- Normalizes generated names:
  lowercase words, no punctuation, max 3 words.
- Rejects generic one-word names, tiny edit-distance changes, and previous auto
  names.
- Shows temporary UI status while naming.
  Manual command generation notifies on rename.

## Settings

`session-rename.idleDelayMs` sets the idle delay in milliseconds between turn end and the naming pass.
Env var: `PI_SESSION_RENAME_IDLE_DELAY_MS`.
Default: `10000`.
Valid range: integer from `0` to `2147483647`.
Precedence: env, trusted project `.pi/settings.json`, user `~/.pi/agent/settings.json`, default.
Project settings apply only when the project is trusted.
Settings files need a JSON number; numeric strings are accepted only from the env var.
Resolved once per session at `session_start`.
An invalid value shows one warning naming the source and uses the default `10000`; it never falls through to a lower-priority source.

```json
{ "session-rename": { "idleDelayMs": 5000 } }
```

## Debug

Opt in through [debug configuration](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `name.generate.start`, `name.generate.finish`, `name.generate.error`.