@0xkahi/pi-qol 0.0.2 → 0.0.3

package/README.md

@@ -3,8 +3,9 @@
 > 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 — and
-**`model_select`** — an interactive model picker.
+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
 
@@ -44,6 +45,26 @@ provider filtering, and inline or overlay layouts,
 
 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
 
@@ -76,6 +97,17 @@ them (project overrides global):
     "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
+    }
   }
 }
 ```
@@ -111,6 +143,23 @@ falls back to the active session model and surfaces a warning notification.
 | `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.
 
@@ -152,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

@@ -109,11 +109,140 @@
         "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",
-    "model_select"
+    "model_select",
+    "custom_footer"
   ],
   "additionalProperties": false
 }

package/package.json

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

package/src/config-loader.ts

@@ -24,6 +24,10 @@ export class ConfigLoader {
     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

@@ -5,6 +5,7 @@ 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>;
@@ -16,3 +17,5 @@ export const piVimKeyEventId = (type: SubExtentionIds, extra: string[] = []) =>
   });
   return id;
 };
+
+export const COLOR_HEX_REGEX = /^#[0-9a-fA-F]{6}$/;

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),
+  };
+}

package/src/extensions/custom-footer/subscription-usage-manager.ts

@@ -0,0 +1,91 @@
+import { AnthropicOauthUsageStrategy } from '../../libs/subscription-usage/strategy/anthropic-oauth-usage.strategy';
+import { OpenAiCodexUsageStrategy } from '../../libs/subscription-usage/strategy/openai-codex-usage.strategy';
+import {
+  type FetchUsageResponse,
+  type RateWindow,
+  SubscriptionUsageApi,
+  type SubscriptionUsageStrategy,
+} from '../../libs/subscription-usage/subscription-usage-api.util';
+import { SUBSCRIPTION_USAGE_TTL_MS } from './constants';
+import type { SupportedProvider } from './types';
+
+export type SubscriptionUsageApiLike = Pick<SubscriptionUsageApi, 'fetchUsage' | 'formatResetDescription'>;
+
+export function resolveSupportedProvider(provider: string | undefined): SupportedProvider | undefined {
+  switch (provider?.toLowerCase()) {
+    case 'anthropic':
+      return 'anthropic';
+    case 'openai-codex':
+    case 'codex':
+    case 'openai':
+    case 'chatgpt':
+      return 'openai-codex';
+    default:
+      return undefined;
+  }
+}
+
+export function pickSubscriptionUsageWindow(windows: readonly RateWindow[]): RateWindow | undefined {
+  let earliestWithReset: RateWindow | undefined;
+
+  for (const window of windows) {
+    if (!window.resetAt) continue;
+    if (!earliestWithReset?.resetAt || window.resetAt.getTime() <= earliestWithReset.resetAt.getTime()) {
+      earliestWithReset = window;
+    }
+  }
+
+  return earliestWithReset ?? windows[0];
+}
+
+export class SubscriptionUsageManager {
+  private cache = new Map<SupportedProvider, FetchUsageResponse>();
+  private inFlight = new Set<SupportedProvider>();
+  private lastFetchAt = new Map<SupportedProvider, number>();
+
+  constructor(
+    private api: SubscriptionUsageApiLike = new SubscriptionUsageApi(),
+    private onUpdate?: () => void,
+    private ttlMs = SUBSCRIPTION_USAGE_TTL_MS,
+  ) {}
+
+  get(provider: SupportedProvider): FetchUsageResponse | undefined {
+    return this.cache.get(provider);
+  }
+
+  ensureFresh(provider: SupportedProvider): FetchUsageResponse | undefined {
+    const last = this.lastFetchAt.get(provider) ?? 0;
+    if (!this.inFlight.has(provider) && Date.now() - last > this.ttlMs) {
+      this.refresh(provider);
+    }
+
+    return this.cache.get(provider);
+  }
+
+  formatResetDescription(date: Date): string {
+    return this.api.formatResetDescription(date);
+  }
+
+  private refresh(provider: SupportedProvider): void {
+    this.inFlight.add(provider);
+    this.lastFetchAt.set(provider, Date.now());
+
+    void this.api
+      .fetchUsage(this.strategyFor(provider))
+      .then(response => {
+        if (!response) return;
+        this.cache.set(provider, response);
+        this.onUpdate?.();
+      })
+      .catch(() => {
+        // Best-effort status: auth/network failures simply hide the segment.
+      })
+      .finally(() => {
+        this.inFlight.delete(provider);
+      });
+  }
+
+  private strategyFor(provider: SupportedProvider): SubscriptionUsageStrategy {
+    return provider === 'anthropic' ? new AnthropicOauthUsageStrategy() : new OpenAiCodexUsageStrategy();
+  }
+}

package/src/extensions/custom-footer/token-stats.ts

@@ -0,0 +1,144 @@
+import type { ContextUsage, SessionEntry } from '@earendil-works/pi-coding-agent';
+import { crayon } from '../../utils/crayon.util';
+import { clampPercent, renderProgressBar } from './progress-bar';
+import type { CustomFooterColors, CustomFooterDisplay, CustomFooterIcons, FooterTheme, SupportedProvider, UsageTotals } from './types';
+
+export type SubscriptionUsageSegmentInput = {
+  provider: SupportedProvider;
+  responseLabel: string;
+  windowLabel: string;
+  usedPercent: number;
+  resetDescription?: string;
+};
+
+export type BuildStatsLeftOptions = {
+  totals: UsageTotals;
+  display: CustomFooterDisplay;
+  icons: Pick<CustomFooterIcons, 'cache' | 'cacheRead' | 'cacheWrite'>;
+  contextUsage: ContextUsage | undefined;
+  contextWindow: number;
+  usingSubscription: boolean;
+  subscriptionUsageSegment?: string;
+  theme: FooterTheme;
+};
+
+export function formatTokens(count: number): string {
+  if (count < 1000) return count.toString();
+  if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+  if (count < 1000000) return `${Math.round(count / 1000)}k`;
+  if (count < 10000000) return `${(count / 1000000).toFixed(1)}M`;
+  return `${Math.round(count / 1000000)}M`;
+}
+
+export function calculateUsageTotals(entries: readonly SessionEntry[]): UsageTotals {
+  const totals: UsageTotals = {
+    totalInput: 0,
+    totalOutput: 0,
+    totalCacheRead: 0,
+    totalCacheWrite: 0,
+    totalCost: 0,
+  };
+
+  for (const entry of entries) {
+    if (entry.type !== 'message' || entry.message.role !== 'assistant') continue;
+
+    const usage = entry.message.usage;
+    totals.totalInput += usage.input;
+    totals.totalOutput += usage.output;
+    totals.totalCacheRead += usage.cacheRead;
+    totals.totalCacheWrite += usage.cacheWrite;
+    totals.totalCost += usage.cost.total;
+
+    const latestPromptTokens = usage.input + usage.cacheRead + usage.cacheWrite;
+    totals.latestCacheHitRate = latestPromptTokens > 0 ? (usage.cacheRead / latestPromptTokens) * 100 : undefined;
+  }
+
+  return totals;
+}
+
+export function buildSubscriptionUsageSegment({
+  colors,
+  icons,
+  theme,
+  usage,
+}: {
+  colors: Pick<CustomFooterColors, 'anthropicUsage' | 'codexUsage'>;
+  icons: Pick<CustomFooterIcons, 'refresh'>;
+  theme: FooterTheme;
+  usage: SubscriptionUsageSegmentInput;
+}): string {
+  const providerColor = usage.provider === 'anthropic' ? colors.anthropicUsage : colors.codexUsage;
+  const pct = clampPercent(usage.usedPercent);
+  const roundedPercent = Math.round(pct).toString();
+  const bar = renderProgressBar(pct);
+
+  const resetParts = usage.resetDescription ? [icons.refresh, usage.resetDescription].filter(Boolean).join(' ') : '';
+
+  return [
+    crayon.colorize(usage.responseLabel, { fg: providerColor }),
+    crayon.colorize(usage.windowLabel, { fg: providerColor }),
+    `${crayon.colorize(bar.filled, { fg: providerColor })}${theme.fg('dim', bar.empty)}`,
+    crayon.colorize(`${roundedPercent}%`, { fg: providerColor }),
+    resetParts ? theme.fg('dim', resetParts) : undefined,
+  ]
+    .filter((part): part is string => Boolean(part))
+    .join(' ');
+}
+
+export function buildStatsLeft({
+  contextUsage,
+  contextWindow,
+  display,
+  icons,
+  subscriptionUsageSegment,
+  theme,
+  totals,
+  usingSubscription,
+}: BuildStatsLeftOptions): string {
+  const parts: string[] = [];
+
+  if (display.tokens) {
+    if (totals.totalInput) parts.push(theme.fg('dim', `↑${formatTokens(totals.totalInput)}`));
+    if (totals.totalOutput) parts.push(theme.fg('dim', `↓${formatTokens(totals.totalOutput)}`));
+  }
+
+  if (display.cache && (totals.totalCacheRead > 0 || totals.totalCacheWrite > 0)) {
+    const hitRate = totals.latestCacheHitRate !== undefined ? ` ${totals.latestCacheHitRate.toFixed(1)}%` : '';
+    parts.push(
+      theme.fg(
+        'dim',
+        `${icons.cache}[${icons.cacheRead}${formatTokens(totals.totalCacheRead)} ${icons.cacheWrite}${formatTokens(totals.totalCacheWrite)}${hitRate}]`,
+      ),
+    );
+  }
+
+  if (totals.totalCost || usingSubscription) {
+    parts.push(theme.fg('dim', `$${totals.totalCost.toFixed(3)}${usingSubscription ? ' (sub)' : ''}`));
+  }
+
+  parts.push(buildContextUsageSegment({ contextUsage, contextWindow, theme }));
+
+  if (subscriptionUsageSegment) {
+    parts.push(theme.fg('dim', '•'), subscriptionUsageSegment);
+  }
+
+  return parts.join(' ');
+}
+
+function buildContextUsageSegment({
+  contextUsage,
+  contextWindow,
+  theme,
+}: {
+  contextUsage: ContextUsage | undefined;
+  contextWindow: number;
+  theme: FooterTheme;
+}): string {
+  const contextPercentValue = contextUsage?.percent ?? 0;
+  const contextPercent = contextUsage?.percent !== null ? contextPercentValue.toFixed(1) : '?';
+  const contextPercentDisplay = contextPercent === '?' ? `?/${formatTokens(contextWindow)}` : `${contextPercent}%/${formatTokens(contextWindow)}`;
+
+  if (contextPercentValue > 90) return theme.fg('error', contextPercentDisplay);
+  if (contextPercentValue > 70) return theme.fg('warning', contextPercentDisplay);
+  return theme.fg('dim', contextPercentDisplay);
+}

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

@@ -0,0 +1,40 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { TUI } from '@earendil-works/pi-tui';
+import type { ConfigLoader } from '../../config-loader';
+import type { Config } from '../../schemas/config.schema';
+
+export type SupportedProvider = 'anthropic' | 'openai-codex';
+
+export type CustomFooterConfig = Config['custom_footer'];
+export type CustomFooterColors = CustomFooterConfig['colors'];
+export type CustomFooterDisplay = CustomFooterConfig['display'];
+export type CustomFooterIcons = CustomFooterConfig['icons'];
+
+export type FooterTheme = {
+  fg(color: 'dim' | 'error' | 'warning', text: string): string;
+};
+
+export type FooterDataProvider = {
+  getGitBranch(): string | null;
+  getExtensionStatuses(): ReadonlyMap<string, string>;
+  getAvailableProviderCount(): number;
+  onBranchChange(cb: () => void): () => void;
+};
+
+export type CustomFooterComponentDeps = {
+  tui: TUI;
+  theme: FooterTheme;
+  footerData: FooterDataProvider;
+  ctx: ExtensionContext;
+  config: ConfigLoader;
+  getThinkingLevel: () => string;
+};
+
+export type UsageTotals = {
+  totalInput: number;
+  totalOutput: number;
+  totalCacheRead: number;
+  totalCacheWrite: number;
+  totalCost: number;
+  latestCacheHitRate?: number;
+};

package/src/index.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { ConfigLoader } from './config-loader';
 import { registerAutoSessionName } from './extensions/auto-session-name';
+import { registerCustomFooter } from './extensions/custom-footer';
 import { registerModelSelect } from './extensions/model-select';
 
 export default function (pi: ExtensionAPI) {
@@ -13,4 +14,5 @@ export default function (pi: ExtensionAPI) {
 
   registerAutoSessionName(pi, { config });
   registerModelSelect(pi, { config });
+  registerCustomFooter(pi, { config });
 }

package/src/libs/subscription-usage/strategy/anthropic-oauth-usage.strategy.ts

@@ -0,0 +1,41 @@
+import { RawDataParser } from '../../../utils/raw-data-parser.util';
+import type { ProviderAuth, RateWindow, SubscriptionUsageStrategy } from '../subscription-usage-api.util';
+
+export class AnthropicOauthUsageStrategy implements SubscriptionUsageStrategy {
+  readonly provider = 'anthropic';
+  readonly label = 'Claude';
+
+  async fetchUsage(auth: ProviderAuth) {
+    const response = await fetch(this.request(auth));
+    const data = RawDataParser.asRecord(await response.json());
+    if (!data) return;
+
+    const windows: RateWindow[] = [];
+    for (const [key, label] of [
+      ['five_hour', '5h'],
+      ['seven_day', 'Week'],
+    ] as const) {
+      const source = RawDataParser.asRecord(data[key]);
+      const usedPercent = RawDataParser.numberValue(source?.utilization);
+      if (usedPercent === undefined) continue;
+      const resetAt = RawDataParser.stringValue(source?.resets_at);
+      const resetDate = resetAt ? new Date(resetAt) : undefined;
+      windows.push({
+        label,
+        usedPercent,
+        resetAt: resetDate && Number.isFinite(resetDate.getTime()) ? resetDate : undefined,
+      });
+    }
+    return windows;
+  }
+
+  private request(opts: ProviderAuth) {
+    return new Request('https://api.anthropic.com/api/oauth/usage', {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${opts.token}`,
+        'anthropic-beta': 'oauth-2025-04-20',
+      },
+    });
+  }
+}

package/src/libs/subscription-usage/strategy/openai-codex-usage.strategy.ts

@@ -0,0 +1,75 @@
+import { RawDataParser } from '../../../utils/raw-data-parser.util';
+import type { ProviderAuth, RateWindow, SubscriptionUsageStrategy } from '../subscription-usage-api.util';
+
+const PRIMARY_WINDOW_FALLBACK_SECONDS = 10800;
+const SECONDARY_WINDOW_FALLBACK_SECONDS = 86400;
+
+export class OpenAiCodexUsageStrategy implements SubscriptionUsageStrategy {
+  readonly provider = 'openai-codex';
+  readonly label = 'Codex';
+
+  async fetchUsage(auth: ProviderAuth) {
+    const response = await fetch(this.request(auth));
+    if (!response.ok) return;
+
+    const data = RawDataParser.asRecord(await response.json());
+    if (!data) return;
+
+    const windows: RateWindow[] = [];
+    this.pushRateLimitWindows(windows, RawDataParser.asRecord(data.rate_limit));
+
+    const additionalRateLimits = Array.isArray(data.additional_rate_limits) ? data.additional_rate_limits : [];
+    for (const item of additionalRateLimits) {
+      const entry = RawDataParser.asRecord(item);
+      if (!entry) continue;
+
+      const prefix = RawDataParser.stringValue(entry.limit_name) ?? RawDataParser.stringValue(entry.metered_feature) ?? 'Additional';
+      this.pushRateLimitWindows(windows, RawDataParser.asRecord(entry.rate_limit), prefix);
+    }
+
+    return windows.length > 0 ? windows : undefined;
+  }
+
+  private pushRateLimitWindows(windows: RateWindow[], rateLimit: Record<string, unknown> | undefined, prefix?: string): void {
+    this.pushRateWindow(windows, RawDataParser.asRecord(rateLimit?.primary_window), PRIMARY_WINDOW_FALLBACK_SECONDS, prefix);
+    this.pushRateWindow(windows, RawDataParser.asRecord(rateLimit?.secondary_window), SECONDARY_WINDOW_FALLBACK_SECONDS, prefix);
+  }
+
+  private pushRateWindow(windows: RateWindow[], window: Record<string, unknown> | undefined, fallbackWindowSeconds: number, prefix?: string): void {
+    if (!window) return;
+
+    const resetDate = this.getResetDate(window);
+    windows.push({
+      label: this.getWindowLabel(RawDataParser.numberValue(window.limit_window_seconds), fallbackWindowSeconds, prefix),
+      usedPercent: RawDataParser.numberValue(window.used_percent) ?? 0,
+      resetAt: resetDate,
+    });
+  }
+
+  private getResetDate(window: Record<string, unknown>): Date | undefined {
+    const resetSeconds = RawDataParser.numberValue(window.reset_at);
+    if (!resetSeconds) return;
+
+    const resetDate = new Date(resetSeconds * 1000);
+    return Number.isFinite(resetDate.getTime()) ? resetDate : undefined;
+  }
+
+  private getWindowLabel(windowSeconds: number | undefined, fallbackWindowSeconds: number, prefix?: string): string {
+    const seconds = windowSeconds && windowSeconds > 0 ? windowSeconds : fallbackWindowSeconds;
+    const hours = Math.round(seconds / 3600);
+
+    const label = hours >= 144 ? 'Week' : hours >= 24 ? 'Day' : `${hours}h`;
+    return prefix ? `${prefix} ${label}` : label;
+  }
+
+  private request(opts: ProviderAuth) {
+    return new Request('https://chatgpt.com/backend-api/wham/usage', {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${opts.token}`,
+        ...(opts?.accountId ? { 'ChatGPT-Account-Id': opts.accountId } : {}),
+        Accept: 'application/json',
+      },
+    });
+  }
+}

package/src/libs/subscription-usage/subscription-usage-api.util.ts

@@ -0,0 +1,78 @@
+import { readFileSync } from 'node:fs';
+import { PathUtil } from '../../utils/path.util';
+import { RawDataParser } from '../../utils/raw-data-parser.util';
+
+export type ProviderAuth = {
+  token: string;
+  accountId?: string;
+};
+
+export type SubscriptionProvider = 'anthropic' | 'openai-codex';
+type SubscriptionAuthconfig = Partial<Record<SubscriptionProvider, Record<string, unknown>>>;
+
+export type RateWindow = {
+  label: string;
+  usedPercent: number;
+  resetAt?: Date;
+};
+
+export type FetchUsageResponse = {
+  label: string;
+  rateWindow: RateWindow[];
+};
+
+export interface SubscriptionUsageStrategy {
+  readonly provider: SubscriptionProvider;
+  readonly label: string;
+  fetchUsage(auth: ProviderAuth): Promise<RateWindow[] | undefined>;
+}
+
+export class SubscriptionUsageApi {
+  async fetchUsage(strategy: SubscriptionUsageStrategy): Promise<FetchUsageResponse | undefined> {
+    const auth = this.getOauthProviderAuth(strategy.provider);
+    if (!auth) return;
+    const rateWindow = await strategy.fetchUsage(auth);
+    if (!rateWindow) return;
+    return {
+      label: strategy.label,
+      rateWindow,
+    };
+  }
+
+  formatResetDescription(date: Date): string {
+    const diffMs = date.getTime() - Date.now();
+    if (diffMs <= 0) return 'now';
+
+    const minutes = Math.floor(diffMs / 60000);
+    if (minutes < 60) return `${minutes}m`;
+
+    const hours = Math.floor(minutes / 60);
+    const remainingMinutes = minutes % 60;
+    if (hours < 24) return remainingMinutes > 0 ? `${hours}h${remainingMinutes}m` : `${hours}h`;
+
+    const days = Math.floor(hours / 24);
+    const remainingHours = hours % 24;
+    return remainingHours > 0 ? `${days}d${remainingHours}h` : `${days}d`;
+  }
+
+  private getOauthProviderAuth(provider: SubscriptionProvider): ProviderAuth | undefined {
+    const auth = this.loadAuthConfig();
+    if (!auth) return;
+
+    const providerAuth = auth[provider];
+    const access = RawDataParser.stringValue(providerAuth?.access);
+    if (!access) return;
+
+    return {
+      token: access,
+      accountId: RawDataParser.stringValue(providerAuth?.accountId),
+    };
+  }
+
+  private loadAuthConfig(): SubscriptionAuthconfig | undefined {
+    const authJson = PathUtil.findPiAuthConfig();
+    if (!authJson.exists) return undefined;
+
+    return RawDataParser.asRecord(JSON.parse(readFileSync(authJson.path, 'utf-8'))) as SubscriptionAuthconfig | undefined;
+  }
+}

package/src/schemas/config.schema.ts

@@ -1,5 +1,6 @@
 import z from 'zod';
 import { AutoSessionNameConfigSchema, PartialAutoSessionNameConfigSchema } from './auto-session-name.config.schema';
+import { CustomFooterConfigSchema, DEFAULT_CUSTOM_FOOTER_CONFIG, PartialCustomFooterConfigSchema } from './custom-footer-config.schema';
 import { ModelSelectConfigSchema, PartialModelSelectConfigSchema } from './model-select.config.schema';
 
 export const ConfigSchema = z.object({
@@ -13,6 +14,7 @@ export const ConfigSchema = z.object({
     provider_filter: [],
     layout: 'inline',
   }),
+  custom_footer: CustomFooterConfigSchema.default(DEFAULT_CUSTOM_FOOTER_CONFIG),
 });
 export type Config = z.infer<typeof ConfigSchema>;
 
@@ -20,5 +22,6 @@ export const PartialConfigSchema = z.object({
   $schema: z.string().optional(),
   auto_session_name: PartialAutoSessionNameConfigSchema.optional(),
   model_select: PartialModelSelectConfigSchema.optional(),
+  custom_footer: PartialCustomFooterConfigSchema.optional(),
 });
 export type PartialConfig = z.infer<typeof PartialConfigSchema>;

package/src/schemas/custom-footer-config.schema.ts

@@ -0,0 +1,64 @@
+import z from 'zod';
+import { ColorHexSchema } from './shared-config.schema';
+
+const CustomFooterColorsSchema = z.object({
+  directory: ColorHexSchema.optional(),
+  modelName: ColorHexSchema.optional(),
+  anthropicUsage: ColorHexSchema.optional().default('#D97706'),
+  codexUsage: ColorHexSchema.optional().default('#10B981'),
+});
+
+const CustomFooterIconsSchema = z.object({
+  directory: z.string().optional().default(' '),
+  refresh: z.string().optional().default(''),
+  cache: z.string().optional().default(' '),
+  cacheRead: z.string().optional().default(' '),
+  cacheWrite: z.string().optional().default(' '),
+});
+
+const CustomFooterDisplaySchema = z.object({
+  tokens: z.boolean().optional().default(true),
+  cache: z.boolean().optional().default(true),
+});
+
+const DEFAULT_CUSTOM_FOOTER_COLORS = CustomFooterColorsSchema.parse({});
+const DEFAULT_CUSTOM_FOOTER_ICONS = CustomFooterIconsSchema.parse({});
+const DEFAULT_CUSTOM_FOOTER_DISPLAY = CustomFooterDisplaySchema.parse({});
+
+export const CustomFooterConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  colors: CustomFooterColorsSchema.default(DEFAULT_CUSTOM_FOOTER_COLORS),
+  icons: CustomFooterIconsSchema.default(DEFAULT_CUSTOM_FOOTER_ICONS),
+  display: CustomFooterDisplaySchema.default(DEFAULT_CUSTOM_FOOTER_DISPLAY),
+});
+export type CustomFooterConfig = z.infer<typeof CustomFooterConfigSchema>;
+
+export const DEFAULT_CUSTOM_FOOTER_CONFIG = CustomFooterConfigSchema.parse({ enabled: false });
+
+export const PartialCustomFooterConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  colors: z
+    .object({
+      directory: ColorHexSchema.optional(),
+      modelName: ColorHexSchema.optional(),
+      anthropicUsage: ColorHexSchema.optional(),
+      codexUsage: ColorHexSchema.optional(),
+    })
+    .optional(),
+  icons: z
+    .object({
+      directory: z.string().optional(),
+      refresh: z.string().optional(),
+      cache: z.string().optional(),
+      cacheRead: z.string().optional(),
+      cacheWrite: z.string().optional(),
+    })
+    .optional(),
+  display: z
+    .object({
+      tokens: z.boolean().optional(),
+      cache: z.boolean().optional(),
+    })
+    .optional(),
+});
+export type PartialCustomFooterConfig = z.infer<typeof PartialCustomFooterConfigSchema>;

package/src/schemas/shared-config.schema.ts

@@ -1,4 +1,5 @@
 import z from 'zod';
+import { COLOR_HEX_REGEX } from '../constants';
 
 export const ReasoningLevelSchema = z.enum(['off', 'minimal', 'low', 'medium', 'high', 'xhigh']);
 export type ReasoningLevel = z.infer<typeof ReasoningLevelSchema>;
@@ -9,3 +10,5 @@ export const ModelConfigSchema = z.object({
   reasoning: ReasoningLevelSchema,
 });
 export type ModelConfig = z.infer<typeof ModelConfigSchema>;
+
+export const ColorHexSchema = z.string().regex(COLOR_HEX_REGEX, { message: 'Invalid color format. Must be a 7-character hex code (e.g., #RRGGBB).' });

package/src/utils/crayon.util.ts

@@ -0,0 +1,58 @@
+import { COLOR_HEX_REGEX } from '../constants';
+
+type ColorizeOptions = {
+  bg?: string;
+  fg?: string;
+};
+
+function hexToRgb(hex: string): { r: number; g: number; b: number } {
+  return {
+    r: Number.parseInt(hex.slice(1, 3), 16),
+    g: Number.parseInt(hex.slice(3, 5), 16),
+    b: Number.parseInt(hex.slice(5, 7), 16),
+  };
+}
+
+function fgAnsi(hex: string): string {
+  const { r, g, b } = hexToRgb(hex);
+  return `\x1b[38;2;${r};${g};${b}m`;
+}
+
+function bgAnsi(hex: string): string {
+  const { r, g, b } = hexToRgb(hex);
+  return `\x1b[48;2;${r};${g};${b}m`;
+}
+
+function colorize(text: string, { bg, fg }: ColorizeOptions = {}): string {
+  const hasFg = fg !== undefined && COLOR_HEX_REGEX.test(fg);
+  const hasBg = bg !== undefined && COLOR_HEX_REGEX.test(bg);
+
+  if (!hasFg && !hasBg) {
+    return text;
+  }
+
+  const prefix = `${hasBg ? bgAnsi(bg) : ''}${hasFg ? fgAnsi(fg) : ''}`;
+  const suffix = `${hasFg ? '\x1b[39m' : ''}${hasBg ? '\x1b[49m' : ''}`;
+
+  return `${prefix}${text}${suffix}`;
+}
+
+const ANSI_ESCAPE_REGEX = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, 'g');
+
+function stripAnsi(text: string): string {
+  return text.replace(ANSI_ESCAPE_REGEX, '');
+}
+
+export const crayon = {
+  colorize(text: string, opts: ColorizeOptions = {}): string {
+    return colorize(text, opts);
+  },
+
+  reverseVideo(text: string): string {
+    return `\x1b[7m${text}\x1b[27m`;
+  },
+
+  stripAnsi(text: string): string {
+    return stripAnsi(text);
+  },
+};

package/src/utils/model-resolver.util.ts

@@ -7,6 +7,7 @@ export type ResolvedModel = {
   apiKey?: string;
   headers?: Record<string, string>;
   reasoning?: ModelConfig['reasoning'];
+  isOauth?: boolean;
 };
 
 export type ResolveModelResult = {
@@ -50,6 +51,7 @@ export class ModelResolver {
             apiKey: auth.apiKey,
             headers: auth.headers,
             reasoning: candidate.reasoning,
+            isOauth: this.ctx.modelRegistry.isUsingOAuth(model),
           },
         };
       }

package/src/utils/path.util.ts

@@ -31,6 +31,10 @@ export class PathUtil {
     }
   }
 
+  static findPiAuthConfig(): FileSearchResult {
+    return PathUtil.findFile(path.join(getAgentDir(), 'auth.json'));
+  }
+
   private static getExtensionConfig(paths: string[]): string {
     return path.join(...paths, 'extensions', EXTENSION_ID, 'config.json');
   }

package/src/utils/raw-data-parser.util.ts

@@ -0,0 +1,14 @@
+export class RawDataParser {
+  static asRecord(value: unknown): Record<string, unknown> | undefined {
+    return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+  }
+
+  static stringValue(value: unknown): string | undefined {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+  }
+
+  static numberValue(value: unknown): number | undefined {
+    const number = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(number) ? number : undefined;
+  }
+}