Auto-Rename Extension for pi

Automatically generates descriptive session names based on the first user query, making it easier to find and resume sessions later.

Features

• Automatic naming: Generates a session name as soon as the first prompt is sent
• Configurable model: Use any model accessible via pi (Anthropic, OpenAI, Google, etc.)
• Model selection strategy: Choose whether auto mode prefers current model or cheapest model
• Fallback model: Specify an alternative model if the primary fails
• Deterministic fallback: Generate names without LLM if all models fail
• Custom prompts: Customize the prompt used for name generation
• Static or dynamic prefixes: Use a fixed string or a shell command for the prefix
• Readable-id suffix: Append a deterministic [adjective-noun-noun] id
• Prefix-only mode: Skip LLM entirely and use just the prefix (e.g., workspace name)
• Manual override: Rename sessions manually via /auto-rename <name>
• Regenerate names: Force regeneration with /auto-rename regen
• Connectivity test: Test model availability with /auto-rename test

Installation

Copy or symlink the auto-rename directory to your pi extensions folder:

# Global installation
cp -r auto-rename ~/.pi/agent/extensions/

# Or project-local
cp -r auto-rename .pi/extensions/

Then reload pi or restart it.

Configuration

Create auto-rename.json in one of these locations (searched in order):

1. ./auto-rename.json (current working directory)
2. ./.pi/auto-rename.json (project-local)
3. ~/.pi/agent/auto-rename.json (global)

Default Configuration

{
  "$schema": "./auto-rename.schema.json",
  "model": null,
  "fallbackModel": null,
  "fallbackDeterministic": "readable-id",
  "modelSelection": "current",
  "prompt": "Generate a short, descriptive title...",
  "prefix": "",
  "prefixCommand": null,
  "prefixOnly": false,
  "readableIdSuffix": false,
  "readableIdEnv": "PI_SESSION_READABLE_ID",
  "enabled": true,
  "debug": false
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | model | object/null | null | Primary model to use ({ provider, id }). If null, auto selection is used. | | fallbackModel | object/null | null | Fallback model if primary fails. If null, skip explicit fallback. | | fallbackDeterministic | string | "readable-id" | Fallback if all LLMs fail: "readable-id" (adjective-noun-noun from session ID), "truncate" (first 50 chars), "words" (first 6 words), "none" | | modelSelection | string | "current" | Auto strategy when model/fallbackModel are null: "current" (current model then cheapest) or "cheapest" (cheapest then current). | | prompt | string | (see above) | Prompt template. Use {{query}} as placeholder | | prefix | string | "" | Static prefix before generated names | | prefixCommand | string/null | null | Shell command to generate dynamic prefix (5s timeout) | | prefixOnly | boolean | false | Skip LLM, use only prefix as full name | | readableIdSuffix | boolean | false | Append [readable-id] to generated names | | readableIdEnv | string/null | "PI_SESSION_READABLE_ID" | Environment variable that can provide a readable-id suffix override | | maxQueryLength | integer | 2000 | Max characters of user query sent to LLM prompt. Longer queries have their middle cut out, preserving beginning and end. | | maxNameLength | integer | 80 | Max characters for the generated name (before prefix/suffix). LLM responses exceeding this are truncated. | | enabled | boolean | true | Enable/disable auto-rename | | debug | boolean | false | Show debug notifications | | wordlistPath | string/null | null | Override path to word_lists.toml (relative to session cwd) | | wordlist | object | null | Inline wordlist override ({ adjectives: [], nouns: [] }) |

Example Configurations

Using OpenAI with Google fallback:

{
  "model": { "provider": "openai", "id": "gpt-4o-mini" },
  "fallbackModel": { "provider": "google", "id": "gemini-2.0-flash" }
}

Local Ollama with cloud fallback:

{
  "model": { "provider": "ollama", "id": "llama3.2" },
  "fallbackModel": { "provider": "anthropic", "id": "claude-3-5-haiku-20241022" },
  "fallbackDeterministic": "words"
}

No LLM fallback, deterministic only on failure:

{
  "model": { "provider": "anthropic", "id": "claude-3-5-haiku-20241022" },
  "fallbackModel": null,
  "fallbackDeterministic": "readable-id"
}

Dynamic prefix from git repo name:

{
  "prefixCommand": "basename $(git rev-parse --show-toplevel 2>/dev/null || pwd)"
}

Result: my-project: Fix Authentication Bug

Workspace prefix + readable-id suffix:

{
  "prefixCommand": "basename $(git rev-parse --show-toplevel 2>/dev/null || pwd)",
  "readableIdSuffix": true
}

Result: my-project: Fix Authentication Bug [brisk-sunflower-river]

Readable-id override from frontend:

{
  "readableIdSuffix": true,
  "readableIdEnv": "PI_SESSION_READABLE_ID"
}

Result: my-project: Fix Authentication Bug [frontend-temp-id]

Workspace name only (no LLM):

{
  "prefixCommand": "basename $(git rev-parse --show-toplevel 2>/dev/null || pwd)",
  "prefixOnly": true
}

Custom wordlist path for readable IDs:

{
  "fallbackDeterministic": "readable-id",
  "wordlistPath": "./word_lists.toml"
}

Result: my-project

Git branch as prefix:

{
  "prefixCommand": "git branch --show-current 2>/dev/null || echo 'main'"
}

Result: feature/auth: Add OAuth Support

Custom prompt for code-focused sessions:

{
  "prompt": "Generate a 3-5 word title for a coding session. Focus on the programming language, framework, or task. Based on:\n\n{{query}}\n\nReply with ONLY the title.",
  "prefix": "code: "
}

Commands

| Command | Description | |---------|-------------| | /auto-rename | Show current session name | | /auto-rename <name> | Manually set session name | | /auto-rename regen | Force regenerate name from first query | | /auto-rename config | Show current configuration | | /auto-rename init | Create default config in current directory | | /auto-rename test | Test model connectivity |

How It Works

1. On session_start, the extension checks if the session already has a name
2. After the first before_agent_start event (first prompt send), it:
   • Resolves the prefix (runs prefixCommand if set, otherwise uses static prefix)
   • If prefixOnly is true: uses just the prefix as the session name
   • Otherwise: extracts the first user message and tries to generate a name:
     1. Try primary model
     2. If primary fails, try fallback model
     3. If both fail, use deterministic fallback (readable-id, truncate, words, or none)
   • Combines prefix + generated name and sets via pi.setSessionName()
3. The name appears in the session selector (/resume) instead of the first message

Input and Output Guards

The extension protects against excessively long inputs and outputs:

• Query truncation (maxQueryLength, default 2000): When the user's first message is very long (e.g., pasting a large code block or document), the middle section is cut out and replaced with a [...truncated...] marker. The beginning (60%) and end (40%) of the query are preserved at word boundaries, keeping both the initial context and the trailing question/details. This prevents excessive token usage and keeps costs low.

• Name length enforcement (maxNameLength, default 80): If the LLM returns a name longer than maxNameLength characters, it is truncated at a word boundary with an ellipsis. This ensures session names stay readable in the session selector UI.

Both limits can be tuned in the config. Enable debug: true to see notifications when truncation occurs.

Error Handling

The extension provides detailed error messages for common issues:

• Provider not found: Shows available providers
• Model not found: Indicates the model ID is invalid
• No API key: Reminds you to set the environment variable
• Authentication failed (401/403): API key is invalid or expired
• Rate limited (429): Too many requests, uses fallback
• Timeout: Network issues, uses fallback

Enable debug: true to see all error details.

Fallback Chain

Configured model → Configured fallback → Auto strategy → Deterministic function → (no name)
      ↓                  ↓                 ↓                    ↓
   Success?           Success?     current/cheapest         "truncate" / "words"
      ↓                  ↓                 ↓                    ↓
    Done!              Done!             Done!             Done! (or skip if "none")

Auto strategy is controlled by modelSelection:

• "current": current model, then cheapest
• "cheapest": cheapest, then current

Session File Format

The extension writes to the standard pi session format using pi.setSessionName(), which appends a session_info entry to the JSONL session file:

{"type":"session_info","id":"...","parentId":"...","timestamp":"...","name":"Your Generated Name"}

This is the canonical field for session names in pi-agent session files.

Requirements

• pi-coding-agent (pi)
• An API key for at least one configured model provider (or use prefixOnly)
• Node.js 18+

Tips

• Use a fast, cheap model (like claude-3-5-haiku or gpt-4o-mini) for quick naming
• Set up a fallback model from a different provider for reliability
• Use fallbackDeterministic: "readable-id" for canonical session IDs
• Keep the prefix short to avoid truncation in the session selector
• Enable debug: true temporarily to troubleshoot issues
• Use /auto-rename test to verify model connectivity before relying on it
• The extension skips renaming if the session already has a name

Files

• index.ts - Extension source code
• auto-rename.schema.json - JSON Schema (Draft-07) for configuration validation
• auto-rename.example.json - Example configuration file
• README.md - This documentation

License

MIT