@0xkahi/pi-qol 0.0.1 → 0.0.3

package/README.md

@@ -3,8 +3,20 @@
 > Quality-of-life extensions for [pi](https://github.com/earendil-works/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 — with
-more QoL features planned.
+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:
+
+```bash
+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
 
@@ -23,16 +35,36 @@ never blocks your turn.
 - **Safe output** — strips `<think>` blocks, unwraps quotes, and truncates titles
   to 100 characters.
 
-## Installation
+### `model_select`
 
-Install the package from npm:
+Adds `/select-model`, an interactive model picker with fuzzy search, optional favourites,
+provider filtering, and inline or overlay layouts,
 
-```bash
-pi install npm:@0xkahi/pi-qol
-```
+- **quick access** to listed favourite models
+- **filtering** specified providers from model search 
 
-Then register it in your pi configuration so pi loads `./src/index.ts` as an
-extension (see the `pi.extensions` field in `package.json`).
+allow keybindings with [pi-vim-keys](https://github.com/0xKahi/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
 
@@ -44,6 +76,7 @@ them (project overrides global):
 | 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
@@ -54,9 +87,26 @@ them (project overrides global):
   "auto_session_name": {
     "enabled": true,
     "model": {
-      "provider": "anthropic",
-      "modelId": "claude-3-5-haiku-latest",
-      "reasoning": "minimal"
+      "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
     }
   }
 }
@@ -84,6 +134,35 @@ them (project overrides global):
 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
@@ -122,6 +201,8 @@ src/
   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
 ```

package/assets/config.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/0xKahi/pi-qol/main/assets/config.schema.json",
-  "title": "Pi Btw Extension Configuration",
+  "title": "Pi Quality of Life Extensions Configuration",
   "description": "Configuration schema for pi-qol extension",
   "type": "object",
   "properties": {
@@ -51,10 +51,198 @@
         "enabled"
       ],
       "additionalProperties": false
+    },
+    "model_select": {
+      "default": {
+        "enabled": false,
+        "favourite": [],
+        "provider_filter": [],
+        "layout": "inline"
+      },
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": false,
+          "type": "boolean"
+        },
+        "favourite": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "provider": {
+                "type": "string"
+              },
+              "modelId": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "provider",
+              "modelId"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "provider_filter": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "layout": {
+          "default": "inline",
+          "type": "string",
+          "enum": [
+            "inline",
+            "overlay"
+          ]
+        }
+      },
+      "required": [
+        "enabled",
+        "favourite",
+        "provider_filter",
+        "layout"
+      ],
+      "additionalProperties": false
+    },
+    "custom_footer": {
+      "default": {
+        "enabled": false,
+        "colors": {
+          "anthropicUsage": "#D97706",
+          "codexUsage": "#10B981"
+        },
+        "icons": {
+          "directory": " ",
+          "refresh": "",
+          "cache": " ",
+          "cacheRead": " ",
+          "cacheWrite": " "
+        },
+        "display": {
+          "tokens": true,
+          "cache": true
+        }
+      },
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": false,
+          "type": "boolean"
+        },
+        "colors": {
+          "default": {
+            "anthropicUsage": "#D97706",
+            "codexUsage": "#10B981"
+          },
+          "type": "object",
+          "properties": {
+            "directory": {
+              "type": "string",
+              "pattern": "^#[0-9a-fA-F]{6}$"
+            },
+            "modelName": {
+              "type": "string",
+              "pattern": "^#[0-9a-fA-F]{6}$"
+            },
+            "anthropicUsage": {
+              "default": "#D97706",
+              "type": "string",
+              "pattern": "^#[0-9a-fA-F]{6}$"
+            },
+            "codexUsage": {
+              "default": "#10B981",
+              "type": "string",
+              "pattern": "^#[0-9a-fA-F]{6}$"
+            }
+          },
+          "required": [
+            "anthropicUsage",
+            "codexUsage"
+          ],
+          "additionalProperties": false
+        },
+        "icons": {
+          "default": {
+            "directory": " ",
+            "refresh": "",
+            "cache": " ",
+            "cacheRead": " ",
+            "cacheWrite": " "
+          },
+          "type": "object",
+          "properties": {
+            "directory": {
+              "default": " ",
+              "type": "string"
+            },
+            "refresh": {
+              "default": "",
+              "type": "string"
+            },
+            "cache": {
+              "default": " ",
+              "type": "string"
+            },
+            "cacheRead": {
+              "default": " ",
+              "type": "string"
+            },
+            "cacheWrite": {
+              "default": " ",
+              "type": "string"
+            }
+          },
+          "required": [
+            "directory",
+            "refresh",
+            "cache",
+            "cacheRead",
+            "cacheWrite"
+          ],
+          "additionalProperties": false
+        },
+        "display": {
+          "default": {
+            "tokens": true,
+            "cache": true
+          },
+          "type": "object",
+          "properties": {
+            "tokens": {
+              "default": true,
+              "type": "boolean"
+            },
+            "cache": {
+              "default": true,
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "tokens",
+            "cache"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "enabled",
+        "colors",
+        "icons",
+        "display"
+      ],
+      "additionalProperties": false
     }
   },
   "required": [
-    "auto_session_name"
+    "auto_session_name",
+    "model_select",
+    "custom_footer"
   ],
   "additionalProperties": false
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xkahi/pi-qol",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "quality of life pi extensions",
   "type": "module",
   "keywords": [

package/src/config-loader.ts

@@ -11,10 +11,6 @@ export class ConfigLoader {
     return ConfigSchema.parse({});
   }
 
-  getConfig(): Config {
-    return this.config;
-  }
-
   isEnabled(key: keyof Config): boolean {
     const section = this.config[key];
     return typeof section === 'object' && section !== null && 'enabled' in section ? Boolean((section as { enabled?: boolean }).enabled) : false;
@@ -24,6 +20,14 @@ export class ConfigLoader {
     return this.config.auto_session_name;
   }
 
+  getModelSelect(): Config['model_select'] {
+    return this.config.model_select;
+  }
+
+  getCustomFooter(): Config['custom_footer'] {
+    return this.config.custom_footer;
+  }
+
   initializeConfig(ctx: ExtensionContext): { success: boolean; error?: string } {
     let merged: Config = this.defaultConfig;
 

package/src/constants.ts

@@ -1 +1,21 @@
+import type { ObjectValues } from './types';
+
 export const EXTENSION_ID = 'pi-qol';
+
+const SUB_EXTENSION_IDS = {
+  auto_session_name: 'auto_session_name',
+  model_select: 'model_select',
+  custom_footer: 'custom_footer',
+} as const;
+
+export type SubExtentionIds = ObjectValues<typeof SUB_EXTENSION_IDS>;
+
+export const piVimKeyEventId = (type: SubExtentionIds, extra: string[] = []) => {
+  let id = `pi.vimKeys.event:${EXTENSION_ID}.${type}`;
+  extra.forEach(val => {
+    id = `${id}.${val}`;
+  });
+  return id;
+};
+
+export const COLOR_HEX_REGEX = /^#[0-9a-fA-F]{6}$/;

package/src/extensions/auto-session-name/index.ts

@@ -66,7 +66,7 @@ export function registerAutoSessionName(pi: ExtensionAPI, deps: { config: Config
         return;
       }
 
-      ctx.ui.notify(`(pi-qol) auto_session_name: ${result.text}  `, 'info');
+      ctx.ui.notify(`(pi-qol) session renamed  : ${result.text}  `, 'info');
     })().catch(err => {
       ctx.ui.notify(`(pi-qol) auto_session_name: ${JSON.stringify(err)}`, 'error');
     });

package/src/extensions/custom-footer/constants.ts

@@ -0,0 +1,4 @@
+export const FILLED_BAR_ICON = '█';
+export const EMPTY_BAR_ICON = '░';
+export const SUBSCRIPTION_BAR_WIDTH = 10;
+export const SUBSCRIPTION_USAGE_TTL_MS = 60_000;

package/src/extensions/custom-footer/footer-component.ts

@@ -0,0 +1,179 @@
+import { basename } from 'node:path';
+import type { Component } from '@earendil-works/pi-tui';
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { crayon } from '../../utils/crayon.util';
+import { pickSubscriptionUsageWindow, resolveSupportedProvider, SubscriptionUsageManager } from './subscription-usage-manager';
+import { buildStatsLeft, buildSubscriptionUsageSegment, calculateUsageTotals } from './token-stats';
+import type { CustomFooterComponentDeps, CustomFooterConfig } from './types';
+
+const MIN_STATS_MODEL_PADDING = 2;
+
+function sanitizeStatusText(text: string): string {
+  return text
+    .replace(/[\r\n\t]/g, ' ')
+    .replace(/ +/g, ' ')
+    .trim();
+}
+
+export class CustomFooterComponent implements Component {
+  private readonly usageManager: SubscriptionUsageManager;
+  private readonly unsubscribeBranch: () => void;
+  private restoredDefaultFooter = false;
+  private disposed = false;
+
+  constructor(private readonly deps: CustomFooterComponentDeps) {
+    this.usageManager = new SubscriptionUsageManager(undefined, () => {
+      if (!this.disposed) deps.tui.requestRender();
+    });
+    this.unsubscribeBranch = deps.footerData.onBranchChange(() => deps.tui.requestRender());
+  }
+
+  invalidate(): void {
+    // All footer data is read live on each render.
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    this.unsubscribeBranch();
+  }
+
+  render(width: number): string[] {
+    if (width <= 0) return [];
+
+    if (!this.deps.config.isEnabled('custom_footer')) {
+      if (!this.restoredDefaultFooter) {
+        this.restoredDefaultFooter = true;
+        this.deps.ctx.ui.setFooter(undefined);
+        this.deps.tui.requestRender();
+      }
+      return [];
+    }
+
+    this.restoredDefaultFooter = false;
+
+    const config = this.deps.config.getCustomFooter();
+    const lines = [this.renderPathLine(width, config), this.renderStatsLine(width, config)];
+
+    const extensionStatuses = this.deps.footerData.getExtensionStatuses();
+    if (extensionStatuses.size > 0) {
+      const statusLine = Array.from(extensionStatuses.entries())
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([, text]) => sanitizeStatusText(text))
+        .join(' ');
+      lines.push(truncateToWidth(statusLine, width, this.deps.theme.fg('dim', '...')));
+    }
+
+    return lines;
+  }
+
+  private renderPathLine(width: number, config: CustomFooterConfig): string {
+    const cwd = this.deps.ctx.sessionManager.getCwd();
+    const directoryText = `${config.icons.directory}${basename(cwd) || cwd}`;
+    const branch = this.deps.footerData.getGitBranch();
+    const sessionName = this.deps.ctx.sessionManager.getSessionName();
+
+    let line: string;
+    if (config.colors.directory) {
+      line = crayon.colorize(directoryText, { fg: config.colors.directory });
+      if (branch) line += this.deps.theme.fg('dim', ` (${branch})`);
+      if (sessionName) line += this.deps.theme.fg('dim', ` • ${sessionName}`);
+    } else {
+      let rawLine = directoryText;
+      if (branch) rawLine += ` (${branch})`;
+      if (sessionName) rawLine += ` • ${sessionName}`;
+      line = this.deps.theme.fg('dim', rawLine);
+    }
+
+    return truncateToWidth(line, width, this.deps.theme.fg('dim', '...'));
+  }
+
+  private renderStatsLine(width: number, config: CustomFooterConfig): string {
+    const model = this.deps.ctx.model;
+    const usingSubscription = model ? this.deps.ctx.modelRegistry.isUsingOAuth(model) : false;
+    const contextUsage = this.deps.ctx.getContextUsage();
+    const contextWindow = contextUsage?.contextWindow ?? model?.contextWindow ?? 0;
+    const subscriptionUsageSegment = this.renderSubscriptionUsageSegment(config, usingSubscription);
+
+    let statsLeft = buildStatsLeft({
+      totals: calculateUsageTotals(this.deps.ctx.sessionManager.getEntries()),
+      display: config.display,
+      icons: config.icons,
+      contextUsage,
+      contextWindow,
+      usingSubscription,
+      subscriptionUsageSegment,
+      theme: this.deps.theme,
+    });
+
+    let statsLeftWidth = visibleWidth(statsLeft);
+    if (statsLeftWidth > width) {
+      statsLeft = truncateToWidth(statsLeft, width, this.deps.theme.fg('dim', '...'));
+      statsLeftWidth = visibleWidth(statsLeft);
+    }
+
+    const rightWithoutProvider = this.buildModelNameSegment(config);
+    let rightSide = rightWithoutProvider;
+
+    if (this.deps.footerData.getAvailableProviderCount() > 1 && model) {
+      const candidate = `${this.deps.theme.fg('dim', `(${model.provider}) `)}${rightWithoutProvider}`;
+      if (statsLeftWidth + MIN_STATS_MODEL_PADDING + visibleWidth(candidate) <= width) {
+        rightSide = candidate;
+      }
+    }
+
+    const rightSideWidth = visibleWidth(rightSide);
+    const totalNeeded = statsLeftWidth + MIN_STATS_MODEL_PADDING + rightSideWidth;
+
+    if (totalNeeded <= width) {
+      return `${statsLeft}${' '.repeat(width - statsLeftWidth - rightSideWidth)}${rightSide}`;
+    }
+
+    const availableForRight = width - statsLeftWidth - MIN_STATS_MODEL_PADDING;
+    if (availableForRight <= 0) return statsLeft;
+
+    const truncatedRight = truncateToWidth(rightSide, availableForRight, '');
+    const truncatedRightWidth = visibleWidth(truncatedRight);
+    return `${statsLeft}${' '.repeat(Math.max(0, width - statsLeftWidth - truncatedRightWidth))}${truncatedRight}`;
+  }
+
+  private buildModelNameSegment(config: CustomFooterConfig): string {
+    const model = this.deps.ctx.model;
+    const modelName = model?.id ?? 'no-model';
+    const modelNameSegment = config.colors.modelName
+      ? crayon.colorize(modelName, { fg: config.colors.modelName })
+      : this.deps.theme.fg('dim', modelName);
+
+    if (!model?.reasoning) return modelNameSegment;
+
+    const thinkingLevel = this.deps.getThinkingLevel() || 'off';
+    const thinkingLabel = thinkingLevel === 'off' ? 'thinking off' : thinkingLevel;
+    return `${modelNameSegment}${this.deps.theme.fg('dim', ` • ${thinkingLabel}`)}`;
+  }
+
+  private renderSubscriptionUsageSegment(config: CustomFooterConfig, usingSubscription: boolean): string | undefined {
+    const model = this.deps.ctx.model;
+    if (!model || !usingSubscription) return undefined;
+
+    const provider = resolveSupportedProvider(model.provider);
+    if (!provider) return undefined;
+
+    const response = this.usageManager.ensureFresh(provider);
+    if (!response) return undefined;
+
+    const window = pickSubscriptionUsageWindow(response.rateWindow);
+    if (!window) return undefined;
+
+    return buildSubscriptionUsageSegment({
+      colors: config.colors,
+      icons: config.icons,
+      theme: this.deps.theme,
+      usage: {
+        provider,
+        responseLabel: response.label,
+        windowLabel: window.label,
+        usedPercent: window.usedPercent,
+        resetDescription: window.resetAt ? this.usageManager.formatResetDescription(window.resetAt) : undefined,
+      },
+    });
+  }
+}

package/src/extensions/custom-footer/index.ts

@@ -0,0 +1,18 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { ConfigLoader } from '../../config-loader';
+import { CustomFooterComponent } from './footer-component';
+
+export function registerCustomFooter(pi: ExtensionAPI, deps: { config: ConfigLoader }): void {
+  let installed = false;
+
+  pi.on('session_start', (_event, ctx) => {
+    if (!deps.config.isEnabled('custom_footer')) return;
+    if (installed) return;
+
+    ctx.ui.setFooter(
+      (tui, theme, footerData) =>
+        new CustomFooterComponent({ tui, theme, footerData, ctx, config: deps.config, getThinkingLevel: () => pi.getThinkingLevel() }),
+    );
+    installed = true;
+  });
+}

package/src/extensions/custom-footer/progress-bar.ts

@@ -0,0 +1,16 @@
+import { EMPTY_BAR_ICON, FILLED_BAR_ICON, SUBSCRIPTION_BAR_WIDTH } from './constants';
+
+export function clampPercent(usedPercent: number): number {
+  return Number.isFinite(usedPercent) ? Math.max(0, Math.min(100, usedPercent)) : 0;
+}
+
+export function renderProgressBar(usedPercent: number, width = SUBSCRIPTION_BAR_WIDTH): { filled: string; empty: string } {
+  const barWidth = Math.max(0, Math.floor(width));
+  const pct = clampPercent(usedPercent);
+  const filledCount = Math.round((pct / 100) * barWidth);
+
+  return {
+    filled: FILLED_BAR_ICON.repeat(filledCount),
+    empty: EMPTY_BAR_ICON.repeat(barWidth - filledCount),
+  };
+}