pi-qol

Quality-of-life extensions for pi.

A small collection of opt-in extensions that smooth out everyday pi usage. Today it ships auto_session_name — automatic, opencode-style session titling, model_select — an interactive model picker, and custom_footer — a compact configurable interactive footer.

Installation

Install the package from npm:

pi install npm:@0xkahi/pi-qol

Then register it in your pi configuration so pi loads ./src/index.ts as an extension (see the pi.extensions field in package.json).

Features

auto_session_name

Automatically generates a short, human-readable title for a brand-new session from its first user message, using a cheap model call that runs in the background and never blocks your turn.

• Non-blocking — titles are generated asynchronously while the agent responds.
• Fires once, early — only on the very first real user turn of a session.
• Smart guards — skips sessions that already have a name, forked/child sessions, and empty prompts.
• Model-flexible — use a configured cheap model, or fall back to the active session model automatically.
• Safe output — strips <think> blocks, unwraps quotes, and truncates titles to 100 characters.

model_select

Adds /select-model, an interactive model picker with fuzzy search, optional favourites, provider filtering, and inline or overlay layouts,

• quick access to listed favourite models
• filtering specified providers from model search

allow keybindings with pi-vim-keys with eventId of pi.vimKeys.event:pi-qol.model_select

custom_footer

Replaces pi's built-in interactive footer with the same three-line layout, but shows the current directory as an icon plus basename, supports hex color overrides, can hide token/cache clusters, and adds an OAuth subscription-usage progress bar for supported providers (Anthropic and OpenAI Codex).

• Directory line — directory icon + basename, with optional git branch and session name.
• Stats line — cumulative input/output tokens, cache read/write/hit cluster, session cost (or (sub) when on a subscription), context-window usage, and the right-aligned model name (with provider prefix when multiple providers are available).
• Subscription usage — a colored progress bar plus percentage and reset time for the active OAuth provider. Usage is fetched lazily and cached, refreshing at most once every 60 seconds per provider; auth/network failures simply hide the segment.

Known difference from pi's built-in footer: the (auto) compaction suffix is omitted because extensions do not expose reliable live state for it.

Configuration

pi-qol reads a JSON config file named config.json from two locations and merges them (project overrides global):

| Scope | Path | | ------- | ---------------------------------------------------------- | | Global | <agent-dir>/extensions/pi-qol/config.json | | Project | <cwd>/.pi/extensions/pi-qol/config.json (trusted projects only) |

Project config is only loaded when the project is trusted.

Example

{
  "$schema": "https://raw.githubusercontent.com/0xKahi/pi-qol/main/assets/config.schema.json",
  "auto_session_name": {
    "enabled": true,
    "model": {
      "provider": "opencode",
      "modelId": "gpt-5-nano",
      "reasoning": "low"
    }
  },
  "model_select": {
    "enabled": true,
    "layout": "overlay",
    "provider_filter": ["anthropic", "openai"],
    "favourite": [{ "provider": "anthropic", "modelId": "claude-sonnet-4-5" }]
  },
  "custom_footer": {
    "enabled": true,
    "colors": {
      "directory": "#A78BFA",
      "modelName": "#60A5FA"
    },
    "display": {
      "tokens": true,
      "cache": true
    }
  }
}

Options

auto_session_name

| Key | Type | Default | Description | | --------- | --------- | ------- | ------------------------------------------------------------------ | | enabled | boolean | false | Turn the auto session naming feature on. | | model | object | — | Optional model used to generate titles. Falls back to the session model if omitted. |

model

| Key | Type | Description | | ----------- | -------- | --------------------------------------------------------------------- | | provider | string | Model provider id (e.g. anthropic, openai). | | modelId | string | Model identifier as registered in pi's model registry. | | reasoning | enum | One of off, minimal, low, medium, high, xhigh. |

When model is set but cannot be found or authenticated, pi-qol automatically falls back to the active session model and surfaces a warning notification.

model_select

| Key | Type | Default | Description | | ----------------- | --------- | -------- | --------------------------------------------------------- | | enabled | boolean | false | Turn the model picker on. | | layout | enum | inline | Picker layout: inline or overlay. | | provider_filter | string[]| [] | Restrict searchable models to these providers. | | favourite | object[]| [] | Favourite models shown in a separate tab (provider, modelId). |

custom_footer

| Key | Type | Default | Description | | --------------------------- | --------- | --------- | ------------------------------------------------ | | enabled | boolean | false | Replace pi's built-in interactive footer. | | display.tokens | boolean | true | Show cumulative input/output token counts. | | display.cache | boolean | true | Show the custom cache read/write/hit cluster. | | colors.directory | hex | — | Color the directory icon and basename. | | colors.modelName | hex | — | Color the right-aligned model name. | | colors.anthropicUsage | hex | #D97706 | Color the Claude subscription usage segment (bar + percentage). | | colors.codexUsage | hex | #10B981 | Color the Codex subscription usage segment (bar + percentage). | | icons.directory | string | nerd font | Glyph shown before the directory basename. | | icons.cache | string | nerd font | Glyph for the cache cluster. | | icons.cacheRead | string | nerd font | Glyph for cache-read tokens. | | icons.cacheWrite | string | nerd font | Glyph for cache-write tokens. | | icons.refresh | string | nerd font | Glyph shown before the subscription reset time. |

Project config shallow-merges each top-level section over global config. If project config sets model_select.favourite, it replaces the global favourites array.

How it works

On before_agent_start, the auto_session_name extension checks a series of guards before doing any work. It only proceeds when all of the following hold:

1. The feature is enabled in config.
2. The session does not already have a name.
3. The session is not a fork/child session.
4. It is the user's first turn.
5. The user prompt is non-empty.

If those pass, it resolves a model, generates a title via a dedicated title-generation prompt, cleans the result, and persists it with pi.setSessionName(). The work runs in a cancellable background task that is aborted on session shutdown.

Development

This project uses Bun and Biome.

bun install        # install dependencies
bun run check      # biome fix + type-check
bun test           # run tests
bun run buildSchema # regenerate assets/config.schema.json from the zod schemas

Project structure

src/
  index.ts                       # extension entry — lifecycle wiring only
  config-loader.ts               # loads + merges global/project config
  constants.ts                   # EXTENSION_ID
  schemas/                       # zod config schemas (full + partial)
  utils/                         # path + model-resolution helpers
  extensions/
    auto-session-name/           # the auto_session_name feature
    model-select/                # the model_select feature
    custom-footer/               # the custom_footer feature
scripts/                         # JSON schema generation
assets/config.schema.json        # generated config schema

License

See repository for license details.

Author

0xKahi