@openlines/opl-pi-sht 0.1.14

package/extensions/opl-ctxtrim/index.ts

@@ -0,0 +1,151 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// opl-ctxtrim trims the verbose descriptions that the third-party context-mode
+// MCP bridge attaches to its ctx_* tools. It edits only the serialized provider
+// payload in the documented `before_provider_request` hook, so the installed
+// context-mode package (and its tool execution) is never modified. Tool names,
+// schema structure, required fields, enums, defaults, bounds, and strict flags
+// are preserved; only human-readable `description` prose is shortened.
+
+// Concise top-level descriptions for the eleven ctx_* tools shipped by
+// context-mode v1.0.169. Any ctx_* tool NOT listed here is left unchanged so a
+// future context-mode release cannot have its semantics silently rewritten.
+export const CTX_DESCRIPTIONS: Record<string, string> = {
+  ctx_execute:
+    "Run code in a sandbox; only what you print (console.log/print/echo) enters context. Use to derive answers from large data (filter, parse, aggregate, transform) without loading raw bytes. Pass background:true to keep a server/daemon alive past the timeout; pass intent to auto-index large output for ctx_search.",
+  ctx_execute_file:
+    "Run code over one file loaded as FILE_CONTENT in a sandbox; only printed output enters context. Use to analyze a large file (line counts, pattern matches, structure, aggregates) without reading raw bytes. Use the Read tool instead when you intend to edit the file.",
+  ctx_index:
+    "Store text/markdown, a file, or a directory into the searchable FTS5 knowledge base for later ctx_search. Prefer `path` over `content` so bytes never pass through context. Not for logs, test output, or single-use data.",
+  ctx_search:
+    "Search the indexed knowledge base and captured session memory (BM25 + trigram, typo-corrected, ranked). Batch every question into one `queries` array; scope with `source`; use sort:\"timeline\" for chronological recall and contentType to filter code vs prose. Content must be indexed first.",
+  ctx_fetch_and_index:
+    "Fetch URL(s) (HTML->markdown, JSON, or text), index them, and return a small preview; raw page bytes never enter context. Use `requests` with concurrency 2-8 for batches; `force`/`ttl` control the 24h cache. Retrieve content with ctx_search.",
+  ctx_batch_execute:
+    "Run multiple shell commands in one call, auto-index their output, and return the sections matching `queries` in the same round trip. Use concurrency 2-8 for I/O-bound commands; keep concurrency 1 for CPU-bound or stateful commands. Put all questions in `queries`.",
+  ctx_stats:
+    "Show this session's context-consumption statistics: bytes returned, per-tool breakdown, estimated tokens, and savings ratio. Read-only.",
+  ctx_doctor:
+    "Diagnose the context-mode install; returns [OK]/[WARN]/[FAIL] checks for runtimes, storage, server, FTS5/SQLite, and hooks.",
+  ctx_upgrade:
+    "Return the shell command that upgrades context-mode. Run it with your shell tool, show the result as a checklist, and tell the user to restart the session.",
+  ctx_purge:
+    "DESTRUCTIVE and irreversible. Requires confirm:true and exactly one scope: `sessionId` wipes a single session; scope:\"project\" wipes the whole project (FTS5 + every session + stats). Never combine `sessionId` with scope:\"project\".",
+  ctx_insight:
+    "Open the context-mode Insight dashboard in the browser. Not a query engine; use ctx_search for indexed content.",
+};
+
+// Shorten a nested JSON Schema parameter description to its first sentence or
+// line. Only `description` text is touched, never validation keywords.
+export function shortenParamDescription(text: string): string {
+  const firstLine = text.split("\n", 1)[0].trim();
+  const sentenceEnd = firstLine.search(/\.\s|\.$/);
+  const clipped = sentenceEnd >= 0 ? firstLine.slice(0, sentenceEnd + 1) : firstLine;
+  return clipped.length > 160 ? `${clipped.slice(0, 157).trimEnd()}...` : clipped;
+}
+
+// Recursively shorten every `description` string inside a parameters schema.
+function shortenSchemaDescriptions(node: unknown): void {
+  if (Array.isArray(node)) {
+    for (const item of node) shortenSchemaDescriptions(item);
+    return;
+  }
+  if (!node || typeof node !== "object") return;
+  const record = node as Record<string, unknown>;
+  for (const [key, value] of Object.entries(record)) {
+    if (key === "description" && typeof value === "string") {
+      record[key] = shortenParamDescription(value);
+    } else if (value && typeof value === "object") {
+      shortenSchemaDescriptions(value);
+    }
+  }
+}
+
+// A tool entry across the three supported provider shapes exposes a name, a
+// holder object carrying `description`, and (optionally) a parameters schema.
+interface ToolView {
+  name: string;
+  descriptionHolder: Record<string, unknown>;
+  parameters?: unknown;
+}
+
+// Resolve a single serialized tool object to a common view, or null when the
+// shape is unrecognized (fail open: leave it untouched).
+function viewTool(tool: unknown): ToolView | null {
+  if (!tool || typeof tool !== "object") return null;
+  const record = tool as Record<string, unknown>;
+
+  // OpenAI Chat Completions / Mistral: { type:"function", function:{ name, description, parameters } }
+  if (record.function && typeof record.function === "object") {
+    const fn = record.function as Record<string, unknown>;
+    if (typeof fn.name === "string") {
+      return { name: fn.name, descriptionHolder: fn, parameters: fn.parameters };
+    }
+  }
+
+  // Bedrock Converse: { toolSpec:{ name, description, inputSchema:{ json } } }
+  if (record.toolSpec && typeof record.toolSpec === "object") {
+    const spec = record.toolSpec as Record<string, unknown>;
+    if (typeof spec.name === "string") {
+      const inputSchema = spec.inputSchema as Record<string, unknown> | undefined;
+      return { name: spec.name, descriptionHolder: spec, parameters: inputSchema?.json };
+    }
+  }
+
+  // OpenAI Responses / Anthropic / Google: { name, description, parameters|input_schema }
+  if (typeof record.name === "string") {
+    return {
+      name: record.name,
+      descriptionHolder: record,
+      parameters: record.parameters ?? record.input_schema,
+    };
+  }
+
+  return null;
+}
+
+// Trim a single tool view in place when it is a known ctx_* tool.
+function trimToolView(view: ToolView): boolean {
+  const concise = CTX_DESCRIPTIONS[view.name];
+  if (!concise) return false;
+  if (typeof view.descriptionHolder.description === "string") {
+    view.descriptionHolder.description = concise;
+  }
+  if (view.parameters && typeof view.parameters === "object") {
+    shortenSchemaDescriptions(view.parameters);
+  }
+  return true;
+}
+
+// Locate the tool arrays inside a provider payload across supported shapes.
+function toolArrays(payload: Record<string, unknown>): unknown[][] {
+  const arrays: unknown[][] = [];
+  if (Array.isArray(payload.tools)) arrays.push(payload.tools);
+  const toolConfig = payload.toolConfig as Record<string, unknown> | undefined;
+  if (toolConfig && Array.isArray(toolConfig.tools)) arrays.push(toolConfig.tools);
+  return arrays;
+}
+
+// Return a trimmed copy of a provider payload, or the original when nothing
+// matched. Never mutates the input.
+export function trimPayload<T>(payload: T): T {
+  if (!payload || typeof payload !== "object") return payload;
+  const clone = structuredClone(payload) as Record<string, unknown>;
+  const arrays = toolArrays(clone);
+  if (arrays.length === 0) return payload;
+  let changed = false;
+  for (const tools of arrays) {
+    for (const tool of tools) {
+      const view = viewTool(tool);
+      if (view && trimToolView(view)) changed = true;
+    }
+  }
+  return changed ? (clone as T) : payload;
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("before_provider_request", (event) => {
+    const trimmed = trimPayload(event.payload);
+    if (trimmed !== event.payload) return trimmed;
+  });
+}

package/extensions/opl-footer/README.md

@@ -0,0 +1,193 @@
+# opl-footer
+
+A customizable three-row footer for the Pi coding agent. It shows model, path, Git, context, thinking, mode, token, cost, session, and performance information in configurable left/right segments.
+
+## Commands, flags, and shortcuts
+
+No commands, flags, or shortcuts. Nerd Font detection can be overridden with `FOOTER_NERD_FONTS=1` or `FOOTER_NERD_FONTS=0`.
+
+## Extension features
+
+### Layout
+
+The default footer has three content rows separated by horizontal dividers:
+
+```
+Row 1 left:  π | <model name> (<provider>) | <folder> <path> <branch> <dirty>
+Row 1 right: <context bar> <pct%> / <max tokens>
+
+Row 2 left:  Thinking: <LEVEL> | <active mode>
+Row 2 right: T: <total> (<cached> cached) ↑ <in> ↓ <out> | $<cost>
+
+Row 3 left:  <turns> turns · <steps> steps · <model requests> mreq · <tool calls> mtool
+Row 3 right: LLM <time> (<last-turn TAT>) · Tool <time> | TTFT <time> · <tokens>/s | Cache <percent>%
+```
+
+The third row is populated after the first completed turn. Its session and performance values are reconstructed from the current session branch where possible; timing values are process-local.
+
+## Features
+
+- **Three-row layout**: independent left and right segment lists for model/context, mode/usage, and session/performance data
+- **Context bar**: configurable gradient bar with percentage and context-window size
+- **Git integration**: branch plus staged, unstaged, and untracked counts, with invalidation after relevant file and Git commands
+- **Token and cost tracking**: total, cache, input/output, and accumulated cost segments
+- **Session statistics**: turns, tool steps, model requests, and model tool calls
+- **Performance statistics**: cumulative LLM/tool duration, most recent user-prompt-to-completion turnaround time, average time to first token, output rate, and cache-hit percentage
+- **Thinking and mode indicators**: thinking-level colors plus caveman, plan, chat, or unified mode segments when available
+- **Nerd Font support**: automatic detection with plain-icon fallbacks
+- **Live updates**: branch changes and session events request footer re-rendering
+
+## Configuration
+
+Create `~/.pi/agent/configs/opl-footer.json` or copy the tracked example from [`configs/opl-footer.json.sample`](../../configs/opl-footer.json.sample). Configure all six row-side arrays (`row1LeftSegments` through `row3RightSegments`) to change the layout. Colors, icons, path/Git display, and the context bar are also configurable. Unknown or invalid JSON uses the extension defaults.
+
+The config is cached for five seconds. Changes normally appear automatically; use `/reload` or restart Pi if needed.
+
+```json
+{
+  "row1LeftSegments": ["pi", "separator", "model", "separator", "path", "git"],
+  "row1RightSegments": ["context_pct"],
+  "row2LeftSegments": ["thinking", "separator", "mode_switcher"],
+  "row2RightSegments": ["token_total", "separator", "cost"],
+  "row3LeftSegments": ["session_stats"],
+  "row3RightSegments": ["perf_stats"]
+}
+```
+
+See the tracked [`configs/opl-footer.json.sample`](../../configs/opl-footer.json.sample) for a complete example. Segment IDs, color fields, context-bar options, thinking-level colors, and icon overrides are documented below. Colors accept Pi theme tokens or hex strings.
+
+## Architecture
+
+`index.ts` installs the footer and lifecycle tracking. `segments/` renders configurable values; `theme.ts`, `types.ts`, and `config.ts` provide styling and JSON configuration; session and performance statistics are collected in process memory and reconstructed from session history where possible.
+
+## Available Segments
+
+| Segment | Description | Notes |
+|---------|-------------|-------|
+| `pi` | π symbol in accent blue | — |
+| `model` | Model name in pink + `(provider)` in dim | No icon; provider omitted if unavailable |
+| `path` | Current working directory | `segmentOptions.path.mode`: `"full"` (default) · `"abbreviated"` · `"basename"` |
+| `git` | Git branch and dirty indicators | `showBranch`, `showStaged`, `showUnstaged`, `showUntracked` (all bool) |
+| `context_pct` | Gradient bar + `X.X%` + max tokens | Bar fully configurable via `segmentOptions.contextBar` (see below). % and max tokens use `contextLabel` colour. Max tokens formatted with K/M suffix (e.g. `128k`, `2M`). Set `DEBUG_PCT` in `context.ts` to a number (0–100) to pin the bar at a fixed value for visual testing. |
+| `cost` | `$<amount>` | `$` dim, amount in `cost` colour (`muted` by default). Shows dim `(no pricing)` when the session total is zero on a non-local model (provider has no pricing configured), and `(local model)` for local models |
+| `thinking` | `Thinking: <LEVEL>` | Dim label, CAPS level with per-level colour; always visible |
+| `mode_switcher` | Unified active mode label | Reads state published by `opl-modes`; `appearance.modeColor` controls the mode value, with hardcoded `muted` fallback |
+| `caveman` | `Caveman mode: <MODE>` | Hidden when caveman extension not loaded |
+| `plan_mode` | `Plan mode: <MODE>` | Hidden when plan-mode extension not loaded |
+| `chat_mode` | `Chat mode: <MODE>` | Hidden when chat-mode extension not loaded |
+| `token_total` | `T: <total> (<cached> cached) ↑ <in> ↓ <out>` | Labels dim, numbers in `tokens` colour (`muted` by default) |
+| `token_in` | Input tokens | Available for custom layouts |
+| `token_out` | Output tokens | Available for custom layouts |
+| `cache_read` | Cache read tokens (hidden if zero) | — |
+| `cache_write` | Cache write tokens (hidden if zero) | — |
+| `context_total` | Total context window size | — |
+| `separator` | `\|` divider | Coloured via `separator` in `colors` |
+| `text:...` | Literal text, e.g. `text:⚡` | — |
+
+## Context Bar
+
+The `context_pct` segment's bar is fully configurable via `segmentOptions.contextBar`:
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `barWidth` | number | `18` | Number of characters wide |
+| `filledChar` | string | `"▋"` | Character used for the filled portion |
+| `unfilledChar` | string | `"▋"` | Character used for the unfilled portion |
+| `unfilledColor` | color | `"#4e4c49"` | Color of the unfilled portion — hex or pi theme token |
+| `gradientStart` | color | `"#f29373"` | Gradient color at the left/empty end — hex or pi theme token |
+| `gradientMid` | color | `"#d67858"` | Gradient midpoint color — hex or pi theme token |
+| `gradientEnd` | color | `"#ae4f2f"` | Gradient color at the right/full end — hex or pi theme token |
+| `gradientMidPoint` | number | `0.55` | Where `gradientMid` sits along the bar (0–1). Below this fraction the gradient runs start→mid; above it mid→end |
+
+All color fields accept either a hex string (e.g. `"#ff6347"`) or a pi theme token (e.g. `"accent"`, `"warning"`, `"dim"`).
+
+```json
+{
+  "segmentOptions": {
+    "contextBar": {
+      "barWidth": 20,
+      "unfilledColor": "dim",
+      "gradientStart": "#56b6c2",
+      "gradientMid": "#61afef",
+      "gradientEnd": "#c678dd",
+      "gradientMidPoint": 0.4
+    }
+  }
+}
+```
+
+## Thinking Levels
+
+The `thinking` segment shows per-level colours:
+
+| Level | Display | Default colour |
+|-------|---------|---------------|
+| `off` | `OFF` | dim |
+| `minimal` | `MINIMAL` | muted |
+| `low` | `LOW` | warning |
+| `medium` | `MEDIUM` | success |
+| `high` | `HIGH` | `#afb9fe` |
+| `xhigh` | `EXTRA HIGH` | rainbow gradient |
+| `max` | `MAX` | rainbow gradient |
+
+Override any level colour via the corresponding key in `colors`. Setting `thinkingXhigh` or `thinkingMax` replaces the rainbow gradient with a solid colour:
+
+```json
+{
+  "colors": {
+    "thinkingXhigh": "#9575cd",
+    "thinkingMax": "#ce93d8"
+  }
+}
+```
+
+
+## Git Status Indicators
+
+The `git` segment shows:
+- Branch name coloured green (clean) or amber (dirty)
+- `*N` — unstaged changes
+- `+N` — staged changes
+- `?N` — untracked files
+
+## Session and Performance Statistics
+
+The `session_stats` segment shows turns, tool steps, and (when available) model requests and model tool calls for the current branch; turns and steps are reconstructed from session history so they survive quit/resume.
+
+The `perf_stats` segment shows cumulative session LLM and tool time, average time to first token, output tokens/sec, and cache-hit percentage. The `LLM` figure is followed by the most recent user-prompt-to-completion turnaround time in parentheses, e.g. `LLM 18m 22s (2m 13s)`. This turnaround reflects only fully-settled turns (the `agent_settled` signal, after any retries or compaction), so it stays blank until the first turn completes. All `perf_stats` timing values are ephemeral — they reset each session and are not reconstructed from branch history.
+
+## Icons
+
+Nerd Font icons are auto-detected from your terminal. Ghostty, WezTerm, Kitty, iTerm2, Alacritty, Foot, Rio, and Contour are recognised automatically — everything else falls back to plain Unicode symbols. If detection gets it wrong (e.g. when running inside tmux), override it:
+
+```bash
+export FOOTER_NERD_FONTS=1  # force Nerd Fonts on
+export FOOTER_NERD_FONTS=0  # force plain icons
+```
+
+### Installing a Nerd Font (macOS)
+
+```bash
+brew install --cask font-jetbrains-mono-nerd-font
+```
+
+Other fonts available via `brew search nerd-font`.
+
+### Configuring iTerm2
+
+1. Open **Settings → Profiles → Text**
+2. Set **Font** to `JetBrainsMonoNL Nerd Font Propo`, size `10` (recommended)
+3. Enable **Use a different font for non-ASCII text** and set the same font there — required for icons to render correctly
+
+### Custom Icons
+
+To swap out any icon, add an `icons` key to your `~/.pi/agent/configs/opl-footer.json`. Browse available Nerd Font glyphs at [nerdfonts.com/cheat-sheet](https://www.nerdfonts.com/cheat-sheet):
+
+```json
+{
+  "icons": {
+    "branch": "",
+    "separator": "|"
+  }
+}
+```

package/extensions/opl-footer/config.ts

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { FooterUserConfig, StatusLineSegmentId, ColorScheme, StatusLineSegmentOptions } from "./types.js";
+import { getDefaultColors } from "./theme.js";
+import type { IconSet } from "./icons.js";
+
+// Default segment configuration — two rows
+const DEFAULT_ROW1_LEFT: StatusLineSegmentId[] = ["pi", "separator", "model", "separator", "path", "git"];
+const DEFAULT_ROW1_RIGHT: StatusLineSegmentId[] = ["context_pct"];
+const DEFAULT_ROW2_LEFT: StatusLineSegmentId[] = ["thinking", "separator", "caveman", "separator", "mode_switcher"];
+const DEFAULT_ROW2_RIGHT: StatusLineSegmentId[] = ["token_total", "separator", "cost"];
+const DEFAULT_ROW3_LEFT: StatusLineSegmentId[] = ["session_stats"];
+const DEFAULT_ROW3_RIGHT: StatusLineSegmentId[] = ["perf_stats"];
+
+const DEFAULT_SEGMENT_OPTIONS: StatusLineSegmentOptions = {
+  path: { mode: "full" },
+  git: {
+    showBranch: true,
+    showStaged: true,
+    showUnstaged: true,
+    showUntracked: true,
+  },
+};
+
+// Cache for user config
+let userConfigCache: FooterUserConfig | null = null;
+let userConfigCacheTime = 0;
+const CACHE_TTL = 5000; // 5 seconds
+
+function getConfigPath(): string {
+  const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+  return join(homeDir, ".pi", "agent", "configs", "opl-footer.json");
+}
+
+export function loadUserConfig(): FooterUserConfig | null {
+  const now = Date.now();
+  if (userConfigCache && now - userConfigCacheTime < CACHE_TTL) {
+    return userConfigCache;
+  }
+
+  const configPath = getConfigPath();
+  try {
+    if (existsSync(configPath)) {
+      const content = readFileSync(configPath, "utf-8");
+      const parsed = JSON.parse(content);
+      userConfigCache = parsed as FooterUserConfig;
+      userConfigCacheTime = now;
+      return userConfigCache;
+    }
+  } catch {
+    // Ignore errors, return null
+  }
+
+  userConfigCache = null;
+  userConfigCacheTime = now;
+  return null;
+}
+
+export function clearUserConfigCache(): void {
+  userConfigCache = null;
+  userConfigCacheTime = 0;
+}
+
+export function getEffectiveConfig(): {
+  row1LeftSegments: StatusLineSegmentId[];
+  row1RightSegments: StatusLineSegmentId[];
+  row2LeftSegments: StatusLineSegmentId[];
+  row2RightSegments: StatusLineSegmentId[];
+  row3LeftSegments: StatusLineSegmentId[];
+  row3RightSegments: StatusLineSegmentId[];
+  colors: ColorScheme;
+  segmentOptions: StatusLineSegmentOptions;
+  icons: Partial<IconSet>;
+} {
+  const userConfig = loadUserConfig();
+
+  return {
+    row1LeftSegments: userConfig?.row1LeftSegments ?? DEFAULT_ROW1_LEFT,
+    row1RightSegments: userConfig?.row1RightSegments ?? DEFAULT_ROW1_RIGHT,
+    row2LeftSegments: userConfig?.row2LeftSegments ?? DEFAULT_ROW2_LEFT,
+    row2RightSegments: userConfig?.row2RightSegments ?? DEFAULT_ROW2_RIGHT,
+    row3LeftSegments: userConfig?.row3LeftSegments ?? DEFAULT_ROW3_LEFT,
+    row3RightSegments: userConfig?.row3RightSegments ?? DEFAULT_ROW3_RIGHT,
+    colors: userConfig?.colors ?? getDefaultColors(),
+    segmentOptions: {
+      ...DEFAULT_SEGMENT_OPTIONS,
+      ...userConfig?.segmentOptions,
+    },
+    icons: userConfig?.icons ?? {},
+  };
+}

package/extensions/opl-footer/git-status.ts

@@ -0,0 +1,170 @@
+import { spawn } from "node:child_process";
+import type { GitStatus } from "./types.js";
+
+interface CachedGitStatus {
+  staged: number;
+  unstaged: number;
+  untracked: number;
+  timestamp: number;
+}
+
+interface CachedBranch {
+  branch: string | null;
+  timestamp: number;
+}
+
+const CACHE_TTL_MS = 1000;
+const BRANCH_TTL_MS = 500;
+let cachedStatus: CachedGitStatus | null = null;
+let cachedBranch: CachedBranch | null = null;
+let pendingFetch: Promise<void> | null = null;
+let pendingBranchFetch: Promise<void> | null = null;
+let invalidationCounter = 0;
+let branchInvalidationCounter = 0;
+
+function parseGitStatusOutput(output: string): { staged: number; unstaged: number; untracked: number } {
+  let staged = 0;
+  let unstaged = 0;
+  let untracked = 0;
+
+  for (const line of output.split("\n")) {
+    if (!line) continue;
+    const x = line[0];
+    const y = line[1];
+
+    if (x === "?" && y === "?") {
+      untracked++;
+      continue;
+    }
+
+    if (x && x !== " " && x !== "?") {
+      staged++;
+    }
+
+    if (y && y !== " ") {
+      unstaged++;
+    }
+  }
+
+  return { staged, unstaged, untracked };
+}
+
+function runGit(args: string[], timeoutMs = 200): Promise<string | null> {
+  return new Promise((resolve) => {
+    const proc = spawn("git", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let resolved = false;
+
+    const finish = (result: string | null) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timeoutId);
+      resolve(result);
+    };
+
+    proc.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+
+    proc.on("close", (code) => {
+      finish(code === 0 ? stdout.trim() : null);
+    });
+
+    proc.on("error", () => {
+      finish(null);
+    });
+
+    const timeoutId = setTimeout(() => {
+      proc.kill();
+      finish(null);
+    }, timeoutMs);
+  });
+}
+
+async function fetchGitBranch(): Promise<string | null> {
+  const branch = await runGit(["branch", "--show-current"]);
+  if (branch === null) return null;
+  if (branch) return branch;
+
+  const sha = await runGit(["rev-parse", "--short", "HEAD"]);
+  return sha ? `${sha} (detached)` : "detached";
+}
+
+async function fetchGitStatus(): Promise<{ staged: number; unstaged: number; untracked: number } | null> {
+  const output = await runGit(["status", "--porcelain"], 500);
+  if (output === null) return null;
+  return parseGitStatusOutput(output);
+}
+
+export function getCurrentBranch(providerBranch: string | null): string | null {
+  const now = Date.now();
+
+  if (cachedBranch && now - cachedBranch.timestamp < BRANCH_TTL_MS) {
+    return cachedBranch.branch;
+  }
+
+  if (!pendingBranchFetch) {
+    const fetchId = branchInvalidationCounter;
+    pendingBranchFetch = fetchGitBranch().then((result) => {
+      if (fetchId === branchInvalidationCounter) {
+        cachedBranch = {
+          branch: result,
+          timestamp: Date.now(),
+        };
+      }
+      pendingBranchFetch = null;
+    });
+  }
+
+  return cachedBranch ? cachedBranch.branch : providerBranch;
+}
+
+export function getGitStatus(providerBranch: string | null): GitStatus {
+  const now = Date.now();
+  const branch = getCurrentBranch(providerBranch);
+
+  if (cachedStatus && now - cachedStatus.timestamp < CACHE_TTL_MS) {
+    return {
+      branch,
+      staged: cachedStatus.staged,
+      unstaged: cachedStatus.unstaged,
+      untracked: cachedStatus.untracked,
+    };
+  }
+
+  if (!pendingFetch) {
+    const fetchId = invalidationCounter;
+    pendingFetch = fetchGitStatus().then((result) => {
+      if (fetchId === invalidationCounter) {
+        cachedStatus = result
+          ? { staged: result.staged, unstaged: result.unstaged, untracked: result.untracked, timestamp: Date.now() }
+          : { staged: 0, unstaged: 0, untracked: 0, timestamp: Date.now() };
+      }
+      pendingFetch = null;
+    });
+  }
+
+  if (cachedStatus) {
+    return {
+      branch,
+      staged: cachedStatus.staged,
+      unstaged: cachedStatus.unstaged,
+      untracked: cachedStatus.untracked,
+    };
+  }
+
+  return { branch, staged: 0, unstaged: 0, untracked: 0 };
+}
+
+export function invalidateGitStatus(): void {
+  cachedStatus = null;
+  invalidationCounter++;
+}
+
+export function invalidateGitBranch(): void {
+  cachedBranch = null;
+  branchInvalidationCounter++;
+}

package/extensions/opl-footer/icons.ts

@@ -0,0 +1,49 @@
+export interface IconSet {
+  pi: string;
+  folder: string;
+  branch: string;
+  git: string;
+  separator: string;
+}
+
+// Nerd Font icons
+export const NERD_ICONS: IconSet = {
+  pi: "\uE22C",         // nf-oct-pi
+  folder: "\uF115",     // nf-fa-folder_open
+  branch: "\uF126",     // nf-fa-code_fork
+  git: "\uF1D3",        // nf-fa-git
+  separator: "|",
+};
+
+// ASCII/Unicode fallback icons
+export const ASCII_ICONS: IconSet = {
+  pi: "π",
+  folder: "📂",
+  branch: "⎇",
+  git: "⎇",
+  separator: "|",
+};
+
+// Detect Nerd Font support
+export function hasNerdFonts(): boolean {
+  if (process.env.FOOTER_NERD_FONTS === "1") return true;
+  if (process.env.FOOTER_NERD_FONTS === "0") return false;
+
+  if (process.env.GHOSTTY_RESOURCES_DIR) return true;
+
+  const termProg = (process.env.TERM_PROGRAM || "").toLowerCase();
+  const nerdTerms = ["iterm", "wezterm", "kitty", "ghostty", "alacritty", "foot", "rio", "contour"];
+  if (nerdTerms.some(t => termProg.includes(t))) return true;
+
+  const term = (process.env.TERM || "").toLowerCase();
+  const nerdTermVars = ["xterm-kitty", "xterm-ghostty", "alacritty", "foot", "rio", "contour"];
+  return nerdTermVars.some(t => term.includes(t));
+}
+
+export function getIcons(customIcons?: Partial<IconSet>): IconSet {
+  const baseIcons = hasNerdFonts() ? NERD_ICONS : ASCII_ICONS;
+  if (!customIcons || Object.keys(customIcons).length === 0) {
+    return baseIcons;
+  }
+  return { ...baseIcons, ...customIcons };
+}