pi-context-inspector 0.0.1

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Yuri Teixeira
+Copyright (c) 2026 YuGiMob
+Copyright (c) 2026 Agnish Chakraborty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# pi-context-inspector
+
+PS: *Forked from the extinct https://github.com/YuGiMob/pi-context-inspector*
+
+Opens a tabbed overlay with the full LLM context of the current session in [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent): token breakdown, system prompt, active tools, every message, and a complete context dump.
+
+## What you get
+
+- **One command, five views.** `/context` opens a centered overlay with Stats, System, Tools, Messages and Full tabs.
+- **Token breakdown that matches reality.** Raw character-based estimates are scaled to the provider-reported token count, so category percentages are proportional to the real usage — not to a guess.
+- **A visual usage grid.** A 10×5 colored grid (50 blocks, 2% each) shows at a glance how much of the context window is system prompt, tools, skills, messages, available space, and the auto-compact buffer.
+- **Scroll, search, copy.** Every content tab supports vim-style scrolling, live `/` search with match navigation, and `y` to copy the raw text to the clipboard.
+- **Skill-aware accounting.** Tool calls that read skill files (`.agents/skills/`, `.pi/agent/*/skills/`, `skills/*/SKILL.md`) are counted under Skills instead of Tools.
+
+## Quick start
+
+Run `/context` at any point during a session:
+
+```text
+/context
+```
+
+The overlay opens with the Stats tab active. `Tab` / `Shift+Tab` cycles tabs, `q` or `Escape` closes the overlay.
+
+## Installation
+
+```bash
+pi install npm:pi-context-inspector
+```
+
+From a local checkout:
+
+```bash
+pi install /path/to/pi-context-inspector
+```
+
+## The tabs
+
+| Tab | Shows |
+| --- | --- |
+| **Stats** | Model name, token usage vs. context window (with percent), a 10×5 colored usage grid, a per-category breakdown (system prompt, system tools, tools, skills, messages, available, auto-compact buffer), and safe-left tokens. |
+| **System** | The full system prompt, line-numbered, scrollable and searchable. |
+| **Tools** | Active tool definitions with their parameter schemas (required vs. optional, descriptions). |
+| **Messages** | All session messages formatted with roles, model, token usage, stop reasons, tool calls, image placeholders and errors. |
+| **Full** | Complete context dump: system prompt + messages + context usage, ready to copy. |
+
+## Keyboard
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Cycle tabs |
+| `↑` / `↓`, `j` / `k` | Scroll |
+| `g` / `G` | Jump to top / bottom |
+| `PgUp` / `PgDn`, `Ctrl+b` / `Ctrl+f`, `Ctrl+u` / `Ctrl+d` | Page scroll |
+| `/` | Live search (type, `Enter` to commit) |
+| `n` / `N` | Next / previous match |
+| `y` | Copy the tab's raw text to the clipboard |
+| `q` / `Escape` | Close the overlay |
+
+## How the token breakdown works
+
+Each category is estimated from raw text (chars ÷ 4, using pi's own per-message token estimator so thinking and image content are counted), then all estimates are scaled by a single ratio so they sum to the provider-reported token count. The grid reserves the auto-compact buffer as its own segment; the remaining blocks are filled proportionally by category. `safeAvailable` is the context window minus the reserve minus current usage — when it hits zero, the overlay reports that the auto-compact threshold has been reached.
+
+## Troubleshooting
+
+- **"No context usage data available."** Send a message first, then re-open `/context` — usage is only reported once a turn has run.
+- **The overlay doesn't open.** `/context` requires interactive (TUI) mode; it is a no-op when `ctx.hasUI` is false.
+- **Percentages look off.** The breakdown scales estimates to the provider's reported total, so category sizes are proportional — but the provider total itself is only as accurate as the provider's usage reporting.
+
+## Development
+
+Requires [Node.js](https://nodejs.org) ≥ 22.19 and npm.
+
+```bash
+npm install
+npm test
+npm run typecheck
+```
+
+## Credits
+
+- [badlogic](https://github.com/badlogic), pi-coding-agent and the TUI APIs this overlay is built on
+- [Agnish Chakraborty](https://github.com/agnishcc), author of [@agnishc/edb-context-viewer](https://github.com/agnishcc/pi-extention-monorepo/tree/main/packages/edb-context-viewer) — this package is a fork of that extension
+
+## License
+
+[MIT](LICENSE)

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.js";

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "pi-context-inspector",
+  "author": "yuriteixeira",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Pi extension: inspect the system prompt, active tools, messages, token breakdown and full LLM context in a tabbed overlay",
+  "main": "index.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yuriteixeira/pi-context-inspector.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "coding-agent",
+    "extension",
+    "context",
+    "inspector",
+    "overlay",
+    "tokens"
+  ],
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@types/node": "^24.0.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.9",
+    "@earendil-works/pi-tui": "^0.84.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,429 @@
+/**
+ * pi-context-inspector
+ *
+ * Single command for inspecting the full LLM context in a tabbed overlay:
+ *
+ *   /context  — opens a tabbed overlay with:
+ *                       [Stats]  token distribution grid + category breakdown
+ *                       [System] full system prompt (scrollable)
+ *                       [Tools]  active tool definitions (scrollable)
+ *                       [Messages] all session messages (scrollable)
+ *                       [Full]   complete context dump (scrollable)
+ *
+ * Tab / Shift+Tab navigates between views.
+ * Each content tab supports: line numbers, scroll, live search (/), clipboard copy (y).
+ */
+
+import {
+	buildSessionContext,
+	type ContextUsage,
+	DEFAULT_COMPACTION_SETTINGS,
+	estimateTokens,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+	type SessionContext,
+	type SessionEntry,
+	type Theme,
+	type ToolInfo,
+} from "@earendil-works/pi-coding-agent";
+import { ScrollableTabContent } from "./scrollable-tab-content.js";
+import { type ContextTokenBreakdown, StatsTabContent } from "./stats-tab-content.js";
+import { TabbedOverlay } from "./tabbed-overlay.js";
+import { formatTokens } from "./utils.js";
+
+type AgentMessage = SessionContext["messages"][number];
+type AssistantMessage = Extract<AgentMessage, { role: "assistant" }>;
+type ToolCallBlock = Extract<AssistantMessage["content"][number], { type: "toolCall" }>;
+type MessageContent = Extract<AgentMessage, { content: unknown }>["content"];
+type ToolDefView = Pick<ToolInfo, "name"> & { description?: string; parameters?: unknown };
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+/** Build display lines with line numbers from raw text. */
+export function buildNumberedLines(text: string, theme: Theme): string[] {
+	const rawLines = text.split("\n");
+	const numWidth = String(rawLines.length).length;
+	return rawLines.map((line, i) => {
+		const num = String(i + 1).padStart(numWidth, " ");
+		return `${theme.fg("dim", num)} ${theme.fg("dim", "│")} ${line}`;
+	});
+}
+
+function numberedTab(text: string, name: string, theme: Theme): ScrollableTabContent {
+	return new ScrollableTabContent(
+		{ rawText: text, displayLines: buildNumberedLines(text, theme), theme },
+		name,
+	);
+}
+
+function formatContent(content: MessageContent): string[] {
+	if (typeof content === "string") return [content];
+
+	const lines: string[] = [];
+	for (const block of content) {
+		switch (block.type) {
+			case "text":
+				lines.push(block.text);
+				break;
+			case "thinking":
+				lines.push(`[Thinking: ${block.thinking}]`);
+				break;
+			case "toolCall":
+				lines.push(`[Tool Call: ${block.name}(${JSON.stringify(block.arguments ?? {})})]`);
+				break;
+			case "image":
+				lines.push(`[Image: ${block.mimeType ?? "unknown"}]`);
+				break;
+			default:
+				lines.push(`[${(block as { type?: string }).type ?? "unknown"}]`);
+		}
+	}
+	return lines;
+}
+
+function formatUsage(usage: AssistantMessage["usage"]): string {
+	const parts: string[] = [];
+	parts.push(`input: ${usage.input}`);
+	parts.push(`output: ${usage.output}`);
+	parts.push(`cache-read: ${usage.cacheRead}`);
+	parts.push(`cache-write: ${usage.cacheWrite}`);
+	parts.push(`total: ${usage.totalTokens}`);
+	return `Tokens: ${parts.join(", ")}`;
+}
+export function formatMessageForDisplay(message: SessionContext["messages"][number], index: number): string[] {
+	const lines: string[] = ["", `──── Message ${index + 1} ────`, `Role: ${message.role}`];
+
+	if (message.role === "assistant") {
+		lines.push(`Model: ${[message.provider, message.model].filter(Boolean).join("/")}`);
+		lines.push(formatUsage(message.usage));
+		lines.push(`Stop: ${message.stopReason}`);
+		if (message.errorMessage) lines.push(`Error: ${message.errorMessage}`);
+	}
+
+	if (message.role === "toolResult") {
+		lines.push(`Tool: ${message.toolName ?? "unknown"}`);
+		lines.push(`Tool Call ID: ${message.toolCallId ?? "unknown"}`);
+		lines.push(`Error: ${message.isError ? "yes" : "no"}`);
+	}
+
+	if (message.role === "bashExecution") {
+		lines.push(`Command: ${message.command}`);
+		lines.push(...(message.output ? message.output.split("\n") : ["(no output)"]));
+		const status: string[] = [];
+		if (message.cancelled) status.push("cancelled");
+		if (message.truncated) status.push("truncated");
+		lines.push(
+			`Exit: ${message.exitCode == null ? "unknown" : message.exitCode}${status.length > 0 ? ` (${status.join(", ")})` : ""}`,
+		);
+		if (message.truncated && message.fullOutputPath) {
+			lines.push(`Full output: ${message.fullOutputPath}`);
+		}
+		return lines;
+	}
+
+	if (message.role === "branchSummary") {
+		lines.push(`Branch from: ${message.fromId}`);
+		lines.push(message.summary);
+		return lines;
+	}
+
+	if (message.role === "compactionSummary") {
+		lines.push(`Tokens before: ${message.tokensBefore}`);
+		lines.push(message.summary);
+		return lines;
+	}
+
+	if (message.role === "custom") {
+		lines.push(`Custom type: ${message.customType}`);
+	}
+
+	if ("content" in message) {
+		lines.push(...formatContent(message.content));
+	}
+	return lines;
+}
+
+export function formatMessagesText(context: SessionContext): string {
+	const lines: string[] = [];
+	if (context.messages.length > 0) {
+		for (let i = 0; i < context.messages.length; i++) {
+			lines.push(...formatMessageForDisplay(context.messages[i]!, i));
+		}
+	} else {
+		lines.push("(no messages yet)");
+	}
+	return lines.join("\n");
+}
+
+interface ContextViewerModelInfo {
+	provider: string;
+	id: string;
+	contextWindow?: number;
+}
+
+export function buildTotalContextText(
+	systemPrompt: string,
+	context: SessionContext,
+	usage: ContextUsage | undefined,
+	model: ContextViewerModelInfo | undefined,
+): string {
+	const sections: string[] = [];
+
+	sections.push("═══════════════════════════════════════════════════════");
+	sections.push("SYSTEM PROMPT");
+	sections.push("═══════════════════════════════════════════════════════");
+	sections.push(systemPrompt);
+	sections.push("");
+
+	sections.push("═══════════════════════════════════════════════════════");
+	sections.push("MESSAGES");
+	sections.push("═══════════════════════════════════════════════════════");
+
+	sections.push(formatMessagesText(context));
+
+	sections.push("");
+	sections.push("═══════════════════════════════════════════════════════");
+	sections.push("CONTEXT USAGE");
+	sections.push("═══════════════════════════════════════════════════════");
+	if (usage) {
+		sections.push(`Tokens: ${usage.tokens?.toLocaleString() ?? "unknown"}`);
+		if (model) {
+			sections.push(`Model: ${model.provider}/${model.id}`);
+			const contextWindow = model.contextWindow ?? usage.contextWindow;
+			if (contextWindow) {
+				const pct = usage.percent ?? (usage.tokens == null ? null : (usage.tokens / contextWindow) * 100);
+				sections.push(
+					`Usage: ${usage.tokens?.toLocaleString() ?? "unknown"} / ${contextWindow.toLocaleString()} (${pct == null ? "unknown" : `${pct.toFixed(1)}%`})`,
+				);
+			}
+		}
+	} else {
+		sections.push("(no usage data available)");
+	}
+
+	return sections.join("\n");
+}
+
+/** Format active tool definitions as readable text for the Tools tab. */
+export function buildToolsText(activeToolDefs: ToolDefView[]): string {
+	if (activeToolDefs.length === 0) return "(no active tools)";
+
+	const sections: string[] = [];
+	for (const tool of activeToolDefs) {
+		sections.push(`${"─".repeat(56)}`);
+		sections.push(`Tool: ${tool.name}`);
+		if (tool.description) {
+			sections.push(`Description: ${tool.description}`);
+		}
+		if (tool.parameters) {
+			sections.push("Parameters:");
+			const params = tool.parameters as { properties?: Record<string, { type?: string; description?: string }>; required?: string[] };
+			if (params?.properties) {
+				for (const [key, val] of Object.entries(params.properties)) {
+					const required = params.required?.includes(key) ? "" : " (optional)";
+					const type = val.type ?? "unknown";
+					const desc = val.description ? `: ${val.description}` : "";
+					sections.push(`  ${key} (${type}${required})${desc}`);
+				}
+			} else {
+				sections.push(`  ${JSON.stringify(tool.parameters, null, 2).split("\n").join("\n  ")}`);
+			}
+		}
+		sections.push("");
+	}
+
+	return sections.join("\n");
+}
+
+/** Build the token breakdown, scaling raw char-based estimates to match actual token count. */
+function isSkillPath(path: unknown): boolean {
+	if (typeof path !== "string") return false;
+	return /(^|\/)\.agents\/skills\/|(^|\/)\.pi\/agent\/.*\/skills\/|(^|\/)skills\/[^/]+\/SKILL\.md$/i.test(path);
+}
+
+function isSkillReadToolCall(block: ToolCallBlock): boolean {
+	if (block.name !== "read") return false;
+	return isSkillPath(block.arguments?.path);
+}
+
+const ESTIMATED_IMAGE_CHARS = 4800;
+
+export function buildTokenBreakdown(
+	systemPrompt: string,
+	activeToolDefs: ToolInfo[],
+	branch: SessionEntry[],
+	usage: ContextUsage | undefined,
+): ContextTokenBreakdown | null {
+	if (usage == null || usage.tokens == null || !usage.contextWindow) return null;
+
+	const estimateChars = (text: string) => Math.ceil(text.length / 4);
+	const reserveTokens = Math.min(DEFAULT_COMPACTION_SETTINGS.reserveTokens, usage.contextWindow);
+
+	const systemRaw = estimateChars(systemPrompt);
+	const toolDefsRaw = estimateChars(JSON.stringify(activeToolDefs));
+
+	let msgTokensRaw = 0;
+	let toolsRaw = 0;
+	let skillsRaw = 0;
+	const skillToolCallIds = new Set<string>();
+
+	for (const entry of branch) {
+		if (entry.type === "message") {
+			const message = entry.message;
+			const messageTotal = estimateTokens(message);
+			const weights = { messages: 0, tools: 0, skills: 0 };
+
+			if (message.role === "user" || message.role === "custom") {
+				if (typeof message.content === "string") {
+					weights.messages += estimateChars(message.content);
+				} else {
+					for (const block of message.content) {
+						if (block.type === "text") weights.messages += estimateChars(block.text);
+						else if (block.type === "image") weights.messages += ESTIMATED_IMAGE_CHARS;
+					}
+				}
+			} else if (message.role === "assistant") {
+				for (const block of message.content) {
+					if (block.type === "text") weights.messages += estimateChars(block.text);
+					else if (block.type === "thinking") weights.messages += estimateChars(block.thinking);
+					else if (block.type === "toolCall") {
+						if (isSkillReadToolCall(block)) {
+							weights.skills += estimateChars(JSON.stringify(block));
+							skillToolCallIds.add(block.id);
+						} else {
+							weights.tools += estimateChars(JSON.stringify(block));
+						}
+					}
+				}
+			} else if (message.role === "toolResult") {
+				const isSkillResult = skillToolCallIds.has(message.toolCallId);
+				for (const block of message.content) {
+					if (block.type === "text") {
+						if (isSkillResult) weights.skills += estimateChars(block.text);
+						else weights.tools += estimateChars(block.text);
+					}
+				}
+			} else if (message.role === "bashExecution") {
+				weights.tools += estimateChars(message.command) + estimateChars(message.output);
+			}
+
+			const weightSum = weights.messages + weights.tools + weights.skills;
+			if (weightSum > 0) {
+				const scale = messageTotal / weightSum;
+				msgTokensRaw += weights.messages * scale;
+				toolsRaw += weights.tools * scale;
+				skillsRaw += weights.skills * scale;
+			}
+		} else if (entry.type === "branch_summary" || entry.type === "compaction") {
+			msgTokensRaw += estimateChars(entry.summary);
+		}
+	}
+
+	const totalRaw = systemRaw + skillsRaw + toolDefsRaw + msgTokensRaw + toolsRaw;
+	const ratio = totalRaw > 0 ? usage.tokens / totalRaw : 1;
+
+	const exact = {
+		systemPrompt: systemRaw * ratio,
+		systemTools: toolDefsRaw * ratio,
+		tools: toolsRaw * ratio,
+		skills: skillsRaw * ratio,
+		messages: msgTokensRaw * ratio,
+	};
+	const allocated = { systemPrompt: 0, systemTools: 0, tools: 0, skills: 0, messages: 0 };
+	let remainder = usage.tokens;
+	const keys = Object.keys(exact) as (keyof typeof exact)[];
+	for (const key of keys) {
+		const value = Math.floor(exact[key]);
+		allocated[key] = value;
+		remainder -= value;
+	}
+	if (totalRaw > 0) {
+		const byFraction = [...keys].sort((a, b) => exact[b] % 1 - exact[a] % 1);
+		for (const key of byFraction) {
+			if (remainder <= 0) break;
+			allocated[key] += 1;
+			remainder -= 1;
+		}
+	}
+
+	return {
+		total: usage.tokens,
+		contextWindow: usage.contextWindow,
+		percent: usage.percent ?? (usage.tokens / usage.contextWindow) * 100,
+		reserveTokens,
+		safeAvailable: Math.max(0, usage.contextWindow - reserveTokens - usage.tokens),
+		systemPrompt: allocated.systemPrompt,
+		systemTools: allocated.systemTools,
+		tools: allocated.tools,
+		skills: allocated.skills,
+		messages: allocated.messages,
+		other: Math.max(0, usage.tokens - (allocated.systemPrompt + allocated.systemTools + allocated.tools + allocated.skills + allocated.messages)),
+	};
+}
+
+/** Overlay options shared across all tabs. */
+const OVERLAY_OPTIONS = {
+	overlay: true,
+	overlayOptions: {
+		anchor: "center" as const,
+		width: "90%" as const,
+		minWidth: 60,
+		maxHeight: "90%" as const,
+	},
+};
+
+// ── Extension ──────────────────────────────────────────────────────────────────
+
+export default function contextViewerExtension(pi: ExtensionAPI): void {
+	pi.registerCommand("context", {
+		description: "Inspect context usage, system prompt, tools, messages, and full LLM context in a tabbed overlay",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			if (!ctx.hasUI) return;
+
+			// ── Gather data ─────────────────────────────────────────────────────
+			const systemPrompt = ctx.getSystemPrompt() ?? "";
+			const usage = ctx.getContextUsage();
+
+			const allTools = pi.getAllTools();
+			const activeToolNames = pi.getActiveTools();
+			const activeToolDefs = allTools.filter((t) => activeToolNames.includes(t.name));
+
+			const branch = ctx.sessionManager.getBranch();
+			const context = buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId());
+
+			const breakdown = buildTokenBreakdown(systemPrompt, activeToolDefs, branch, usage);
+			const toolsText = buildToolsText(activeToolDefs);
+			const fullText = buildTotalContextText(systemPrompt, context, usage, ctx.model);
+			const messagesText = formatMessagesText(context);
+
+			// ── Subtitle ────────────────────────────────────────────────────────
+			const subtitle =
+				usage?.tokens != null && usage.contextWindow != null
+					? `${formatTokens(usage.tokens)} / ${formatTokens(usage.contextWindow)} (${(usage.percent ?? (usage.tokens / usage.contextWindow) * 100).toFixed(1)}%)`
+					: "no usage data yet";
+
+			// ── Build and open the overlay ──────────────────────────────────────
+			await ctx.ui.custom<void>((_tui, theme, _keybindings, done) => {
+				const modelName = ctx.model?.id ?? "unknown model";
+
+				const tabs = [
+					new StatsTabContent(breakdown, theme, {
+						name: modelName,
+						contextWindow: ctx.model?.contextWindow ?? usage?.contextWindow,
+					}),
+					numberedTab(systemPrompt, "System", theme),
+					numberedTab(toolsText, "Tools", theme),
+					numberedTab(messagesText, "Messages", theme),
+					numberedTab(fullText, "Full", theme),
+				];
+
+				return new TabbedOverlay({
+					title: "Context Viewer",
+					subtitle,
+					tabs,
+					theme,
+					done,
+				});
+			}, OVERLAY_OPTIONS);
+		},
+	});
+}

package/src/scrollable-base.ts

@@ -0,0 +1,230 @@
+import { copyToClipboard as copyTextToClipboard, type Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, sliceByColumn, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { CONTENT_HEIGHT } from "./utils.js";
+
+export abstract class ScrollableBase {
+  protected scrollOffset = 0;
+  protected searchMode = false;
+  protected searchQuery = "";
+  protected searchMatches: number[] = [];
+  protected currentMatchIndex = -1;
+  protected copyFlash = false;
+  protected copyFlashTimer: ReturnType<typeof setTimeout> | undefined;
+  protected visualLines: string[] = [];
+  protected visualToLogical: number[] = [];
+  protected visualTotal = 0;
+
+  protected abstract get rawText(): string;
+  protected abstract get displayLines(): string[];
+  protected abstract get theme(): Theme;
+
+  protected getVisibleLines(): number {
+    return CONTENT_HEIGHT;
+  }
+
+  protected buildVisualLines(innerWidth: number): void {
+    const th = this.theme;
+    const total = this.displayLines.length;
+    const numWidth = String(total).length;
+    const prefixWidth = numWidth + 3;
+    const continuationPrefix = th.fg("dim", " ".repeat(numWidth) + " · ");
+
+    this.visualLines = [];
+    this.visualToLogical = [];
+
+    for (let logicalIdx = 0; logicalIdx < total; logicalIdx++) {
+      const displayLine = this.displayLines[logicalIdx]!;
+      const lineWidth = visibleWidth(displayLine);
+
+      if (lineWidth <= innerWidth) {
+        this.visualLines.push(displayLine);
+        this.visualToLogical.push(logicalIdx);
+        continue;
+      }
+
+      const contentMaxWidth = innerWidth - prefixWidth;
+      const origPrefix = sliceByColumn(displayLine, 0, prefixWidth);
+      const content = sliceByColumn(displayLine, prefixWidth, lineWidth - prefixWidth);
+      const wrapped = wrapTextWithAnsi(content, contentMaxWidth);
+
+      for (let w = 0; w < wrapped.length; w++) {
+        this.visualLines.push(w === 0 ? origPrefix + wrapped[w]! : continuationPrefix + wrapped[w]!);
+        this.visualToLogical.push(logicalIdx);
+      }
+    }
+
+    this.visualTotal = this.visualLines.length;
+  }
+
+  protected handleSearchInput(data: string): boolean {
+    if (!this.searchMode) return false;
+
+    if (matchesKey(data, Key.escape)) {
+      this.searchMode = false;
+      this.searchQuery = "";
+      this.searchMatches = [];
+      this.currentMatchIndex = -1;
+      return true;
+    }
+    if (matchesKey(data, Key.enter)) {
+      if (this.searchQuery.length > 0) {
+        this.findMatches();
+        if (this.searchMatches.length > 0) {
+          this.currentMatchIndex = 0;
+          this.scrollToMatch(this.getVisibleLines());
+        }
+      }
+      this.searchMode = false;
+      return true;
+    }
+    if (matchesKey(data, Key.backspace)) {
+      this.searchQuery = this.searchQuery.slice(0, -1);
+      this.findMatches();
+      if (this.searchMatches.length > 0) {
+        this.currentMatchIndex = 0;
+        this.scrollToMatch(this.getVisibleLines());
+      }
+      return true;
+    }
+    if (data.length === 1 && data.charCodeAt(0) >= 32) {
+      this.searchQuery += data;
+      this.findMatches();
+      if (this.searchMatches.length > 0) {
+        this.currentMatchIndex = 0;
+        this.scrollToMatch(this.getVisibleLines());
+      }
+      return true;
+    }
+    return true;
+  }
+
+  protected handleScrollKey(data: string): boolean {
+    if (this.handleSearchInput(data)) return true;
+
+    const visibleLines = this.getVisibleLines();
+    const maxOffset = Math.max(0, this.visualTotal - visibleLines);
+
+    if (matchesKey(data, Key.down) || data === "j") {
+      this.scrollDown(1, maxOffset);
+      return true;
+    }
+    if (matchesKey(data, Key.up) || data === "k") {
+      this.scrollUp(1);
+      return true;
+    }
+    if (matchesKey(data, Key.home) || data === "g") {
+      this.scrollOffset = 0;
+      return true;
+    }
+    if (matchesKey(data, Key.end) || data === "G") {
+      this.scrollToBottom(maxOffset);
+      return true;
+    }
+    if (matchesKey(data, Key.pageDown) || matchesKey(data, Key.ctrl("f"))) {
+      this.scrollDown(visibleLines - 2, maxOffset);
+      return true;
+    }
+    if (matchesKey(data, Key.pageUp) || matchesKey(data, Key.ctrl("b"))) {
+      this.scrollUp(visibleLines - 2);
+      return true;
+    }
+    if (matchesKey(data, Key.ctrl("d"))) {
+      this.scrollDown(Math.floor(visibleLines / 2), maxOffset);
+      return true;
+    }
+    if (matchesKey(data, Key.ctrl("u"))) {
+      this.scrollUp(Math.floor(visibleLines / 2));
+      return true;
+    }
+    if (data === "/") {
+      this.searchMode = true;
+      this.searchQuery = "";
+      this.searchMatches = [];
+      this.currentMatchIndex = -1;
+      return true;
+    }
+    if (data === "n") {
+      this.nextMatch();
+      return true;
+    }
+    if (data === "N") {
+      this.prevMatch();
+      return true;
+    }
+    if (data === "y") {
+      void this.copyToClipboard();
+      return true;
+    }
+
+    return false;
+  }
+  protected findMatches(): void {
+    const query = this.searchQuery.toLowerCase();
+    const rawLines = this.rawText.split("\n");
+    this.searchMatches = [];
+    if (query.length === 0) {
+      this.currentMatchIndex = -1;
+      return;
+    }
+    for (let i = 0; i < rawLines.length; i++) {
+      if (rawLines[i]!.toLowerCase().includes(query)) {
+        this.searchMatches.push(i);
+      }
+    }
+  }
+
+  protected scrollToMatch(visibleLines: number): void {
+    if (this.currentMatchIndex >= 0 && this.currentMatchIndex < this.searchMatches.length) {
+      const logicalLine = this.searchMatches[this.currentMatchIndex]!;
+      const targetLine = this.visualToLogical.indexOf(logicalLine);
+      if (targetLine >= 0) {
+        if (targetLine < this.scrollOffset || targetLine >= this.scrollOffset + visibleLines) {
+          this.scrollOffset = Math.max(0, targetLine - Math.floor(visibleLines / 3));
+        }
+      }
+    }
+  }
+
+  protected nextMatch(): void {
+    if (this.searchMatches.length === 0) return;
+    this.currentMatchIndex = (this.currentMatchIndex + 1) % this.searchMatches.length;
+    this.scrollToMatch(this.getVisibleLines());
+  }
+
+  protected prevMatch(): void {
+    if (this.searchMatches.length === 0) return;
+    this.currentMatchIndex = (this.currentMatchIndex - 1 + this.searchMatches.length) % this.searchMatches.length;
+    this.scrollToMatch(this.getVisibleLines());
+  }
+
+  protected async copyToClipboard(): Promise<void> {
+    this.copyFlash = true;
+    try {
+      await copyTextToClipboard(this.rawText);
+    } catch {
+      // Silently fail if clipboard tools aren't available
+    }
+    clearTimeout(this.copyFlashTimer);
+    this.copyFlashTimer = setTimeout(() => {
+      this.copyFlash = false;
+    }, 1500);
+  }
+
+  protected scrollDown(amount: number, maxOffset: number): void {
+    this.scrollOffset = Math.min(this.scrollOffset + amount, maxOffset);
+  }
+
+  protected scrollUp(amount: number): void {
+    this.scrollOffset = Math.max(0, this.scrollOffset - amount);
+  }
+
+  protected scrollToBottom(maxOffset: number): void {
+    this.scrollOffset = Math.max(0, maxOffset);
+  }
+
+  invalidate(): void {
+    this.visualLines = [];
+    this.visualToLogical = [];
+    this.visualTotal = 0;
+  }
+}

package/src/scrollable-tab-content.ts

@@ -0,0 +1,101 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { TabContent } from "./tabbed-overlay.js";
+import { ScrollableBase } from "./scrollable-base.js";
+
+export interface ScrollableTabContentOptions {
+  rawText: string;
+  displayLines: string[];
+  theme: Theme;
+}
+
+export class ScrollableTabContent extends ScrollableBase implements TabContent {
+  constructor(
+    private opts: ScrollableTabContentOptions,
+    public readonly name: string = "",
+  ) {
+    super();
+  }
+
+  protected get rawText(): string { return this.opts.rawText; }
+  protected get displayLines(): string[] { return this.opts.displayLines; }
+  protected get theme(): Theme { return this.opts.theme; }
+
+  getAboveContentLine(_innerWidth: number): string | null {
+    const th = this.opts.theme;
+    if (this.searchMode) {
+      return ` ${th.fg("accent", "/")} ${this.searchQuery}${th.fg("dim", "▏")}`;
+    }
+    if (this.searchMatches.length > 0) {
+      return ` ${th.fg("accent", "/")} ${th.fg("text", this.searchQuery)} ${th.fg("dim", "—")} ${th.fg("accent", `${this.currentMatchIndex + 1}/${this.searchMatches.length}`)}`;
+    }
+    if (this.searchQuery.length > 0) {
+      return ` ${th.fg("accent", "/")} ${th.fg("text", this.searchQuery)} ${th.fg("dim", "—")} ${th.fg("warning", "0 matches")}`;
+    }
+    return null;
+  }
+
+  getFooterLeft(): string {
+    const th = this.opts.theme;
+    const total = this.visualTotal > 0 ? this.visualTotal : this.opts.displayLines.length;
+    const maxScroll = Math.max(0, total - 1);
+    const visibleEnd = Math.min(this.scrollOffset + 1, total);
+
+    const scrollPercent =
+      total === 0
+        ? "All"
+        : this.scrollOffset === 0
+          ? "Top"
+          : this.scrollOffset >= maxScroll
+            ? "Bot"
+            : `${Math.round(((this.scrollOffset + 1) / total) * 100)}%`;
+
+    let left = `${visibleEnd}/${total} [${scrollPercent}]`;
+    if (this.copyFlash) {
+      left += th.fg("success", " ✓ Copied!");
+    }
+    return left;
+  }
+
+  readonly footerHints = "↑↓ scroll · / search · n/N next · y copy";
+
+  handleInput(data: string): boolean {
+    return this.handleScrollKey(data);
+  }
+
+  renderContent(innerWidth: number, height: number): string[] {
+    this.buildVisualLines(innerWidth);
+    const th = this.opts.theme;
+    const lines: string[] = [];
+
+    const maxScroll = Math.max(0, this.visualTotal - height);
+    this.scrollOffset = Math.min(this.scrollOffset, maxScroll);
+    this.scrollOffset = Math.max(0, this.scrollOffset);
+
+    for (let i = 0; i < height; i++) {
+      const lineIdx = this.scrollOffset + i;
+      if (lineIdx < this.visualTotal) {
+        let line = this.visualLines[lineIdx]!;
+
+        const logicalIdx = this.visualToLogical[lineIdx]!;
+        const isCurrentMatch =
+          this.searchMatches.length > 0 &&
+          this.currentMatchIndex >= 0 &&
+          this.searchMatches[this.currentMatchIndex] === logicalIdx;
+        const isOtherMatch =
+          this.searchMatches.length > 0 && this.searchMatches.includes(logicalIdx) && !isCurrentMatch;
+
+        if (isCurrentMatch) {
+          line = th.bg("selectedBg", line);
+        } else if (isOtherMatch) {
+          line = th.fg("warning", line);
+        }
+
+        lines.push(line);
+      } else {
+        lines.push(th.fg("dim", "~"));
+      }
+    }
+
+    return lines;
+  }
+}

package/src/stats-tab-content.ts

@@ -0,0 +1,258 @@
+/**
+ * StatsTabContent — token distribution grid + category breakdown table.
+ *
+ * Shows a compact model/context summary, then a colored 10×5 grid beside an
+ * estimated per-category usage breakdown. The final grid segment is reserved for
+ * Pi's auto-compaction response buffer.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { TabContent } from "./tabbed-overlay.js";
+import { formatTokens } from "./utils.js";
+
+const GRID_WIDTH = 10;
+const GRID_HEIGHT = 5;
+const TOTAL_BLOCKS = GRID_WIDTH * GRID_HEIGHT; // 50 blocks = 2% each
+
+const ANSI_RESET = "\x1b[0m";
+const ANSI_BOLD = "\x1b[1m";
+
+function fg(hex: string, text: string): string {
+	const normalized = hex.replace("#", "");
+	const r = Number.parseInt(normalized.slice(0, 2), 16);
+	const g = Number.parseInt(normalized.slice(2, 4), 16);
+	const b = Number.parseInt(normalized.slice(4, 6), 16);
+	return `\x1b[38;2;${r};${g};${b}m${text}${ANSI_RESET}`;
+}
+
+function bold(text: string): string {
+	return `${ANSI_BOLD}${text}${ANSI_RESET}`;
+}
+
+export interface ContextTokenBreakdown {
+	total: number;
+	contextWindow: number;
+	percent: number;
+	reserveTokens: number;
+	safeAvailable: number;
+	systemPrompt: number;
+	systemTools: number;
+	tools: number;
+	skills: number;
+	messages: number;
+	other: number;
+}
+
+export interface StatsModelInfo {
+	name: string;
+	contextWindow?: number;
+}
+
+interface Category {
+	key: keyof Pick<
+		ContextTokenBreakdown,
+		"systemPrompt" | "systemTools" | "tools" | "skills" | "messages" | "safeAvailable" | "reserveTokens"
+	>;
+	label: string;
+	icon: string;
+	value: number;
+	hex: string;
+	block: string;
+}
+
+const CATEGORY_META = {
+	systemPrompt: {
+		label: "System prompt",
+		icon: "󰈙",
+		hex: "#A78BFA",
+		block: "󰈙",
+	},
+	systemTools: {
+		label: "System tools",
+		icon: "󰒓",
+		hex: "#22D3EE",
+		block: "󰒓",
+	},
+	tools: {
+		label: "Tools",
+		icon: "󰐥",
+		hex: "#34D399",
+		block: "󰐥",
+	},
+	skills: {
+		label: "Skills",
+		icon: "󰌵",
+		hex: "#FBBF24",
+		block: "󰌵",
+	},
+	messages: {
+		label: "Messages",
+		icon: "󰍩",
+		hex: "#60A5FA",
+		block: "󰍩",
+	},
+	safeAvailable: {
+		label: "Available",
+		icon: "󰋙",
+		hex: "#6B7280",
+		block: "󰋙",
+	},
+	reserveTokens: {
+		label: "Auto-compact buffer",
+		icon: "󰅐",
+		hex: "#FB923C",
+		block: "󰅐",
+	},
+} as const;
+
+export class StatsTabContent implements TabContent {
+	readonly name = "Stats";
+	readonly footerHints = "";
+
+	constructor(
+		private breakdown: ContextTokenBreakdown | null,
+		private theme: Theme,
+		private modelInfo?: StatsModelInfo,
+	) {}
+
+	/** Stats view has no interactive search bar — always use border separator. */
+	getAboveContentLine(_innerWidth: number): string | null {
+		return null;
+	}
+
+	getFooterLeft(): string {
+		if (!this.breakdown) return "";
+		const { total, contextWindow, percent, safeAvailable } = this.breakdown;
+		return `${formatTokens(total)} / ${formatTokens(contextWindow)} (${percent.toFixed(1)}%) · ${formatTokens(safeAvailable)} safe left`;
+	}
+
+	/** Stats view has no keyboard interactions. */
+	handleInput(_data: string): boolean {
+		return false;
+	}
+
+	invalidate(): void {}
+
+	renderContent(_innerWidth: number, height: number): string[] {
+		const th = this.theme;
+
+		if (!this.breakdown) {
+			const lines: string[] = [
+				"",
+				`  ${th.fg("warning", "No context usage data available.")}`,
+				`  ${th.fg("dim", "Send a message first, then re-open /context.")}`,
+			];
+			while (lines.length < height) lines.push("");
+			return lines;
+		}
+
+		const { total, contextWindow, percent, reserveTokens, safeAvailable } = this.breakdown;
+		const modelName = this.modelInfo?.name ?? "unknown model";
+		const safeLeftText =
+			safeAvailable > 0 ? `${formatTokens(safeAvailable)} safe left` : "auto-compact threshold reached";
+
+		const categories = this.getCategories();
+		const gridLines = this.renderGrid(categories);
+		const breakdownLines = this.renderBreakdown(categories);
+
+		const lines: string[] = [
+			`  ${bold(`${modelName} · ${formatTokens(total)}/${formatTokens(contextWindow)} tokens (${percent.toFixed(1)}%)`)} ${th.fg("dim", `· ${safeLeftText}`)}`,
+			"",
+			"",
+			`  ${th.fg("dim", "Estimated usage by category")}`,
+			"",
+		];
+
+		const GRID_VIS_W = GRID_WIDTH * 2 - 1;
+		const maxRows = Math.max(gridLines.length, breakdownLines.length);
+		for (let i = 0; i < maxRows; i++) {
+			const leftRaw = gridLines[i] ?? "";
+			const leftVisW = visibleWidth(leftRaw);
+			const pad = " ".repeat(Math.max(0, GRID_VIS_W - leftVisW));
+			const right = breakdownLines[i] ?? "";
+			lines.push(`    ${leftRaw}${pad}    ${right}`);
+		}
+
+		if (safeAvailable <= 0) {
+			lines.push("");
+			lines.push(`  ${fg(CATEGORY_META.reserveTokens.hex, "Auto-compact buffer is being used")}`);
+		} else {
+			lines.push("");
+			lines.push(
+				`  ${th.fg("dim", `Auto-compact starts after ${formatTokens(contextWindow - reserveTokens)} tokens`)}`,
+			);
+		}
+
+		while (lines.length < height) lines.push("");
+		return lines.slice(0, height);
+	}
+
+	private getCategories(): Category[] {
+		const b = this.breakdown!;
+		return [
+			this.category("systemPrompt", b.systemPrompt),
+			this.category("systemTools", b.systemTools),
+			this.category("tools", b.tools),
+			this.category("skills", b.skills),
+			this.category("messages", b.messages + b.other),
+			this.category("safeAvailable", b.safeAvailable),
+			this.category("reserveTokens", b.reserveTokens),
+		];
+	}
+
+	private category(key: Category["key"], value: number): Category {
+		const meta = CATEGORY_META[key];
+		return { key, value, ...meta };
+	}
+
+	private renderGrid(categories: Category[]): string[] {
+		const blocks: string[] = [];
+		const { contextWindow, reserveTokens } = this.breakdown!;
+		const reserveBlockCount = reserveTokens > 0 ? Math.max(1, Math.round((reserveTokens / contextWindow) * TOTAL_BLOCKS)) : 0;
+		const safeBlockCount = Math.max(0, TOTAL_BLOCKS - reserveBlockCount);
+		const safeWindow = Math.max(1, contextWindow - reserveTokens);
+		const safeCategories = categories.filter((cat) => cat.key !== "reserveTokens");
+
+		for (const cat of safeCategories) {
+			let count = Math.round((cat.value / safeWindow) * safeBlockCount);
+			if (count === 0 && cat.value > 0) count = 1;
+			for (let j = 0; j < count && blocks.length < safeBlockCount; j++) {
+				blocks.push(fg(cat.hex, cat.block));
+			}
+		}
+
+		while (blocks.length < safeBlockCount) {
+			blocks.push(fg(CATEGORY_META.safeAvailable.hex, CATEGORY_META.safeAvailable.block));
+		}
+
+		for (let i = 0; i < reserveBlockCount && blocks.length < TOTAL_BLOCKS; i++) {
+			blocks.push(fg(CATEGORY_META.reserveTokens.hex, CATEGORY_META.reserveTokens.block));
+		}
+
+		const gridLines: string[] = [];
+		for (let r = 0; r < GRID_HEIGHT; r++) {
+			let row = "";
+			for (let c = 0; c < GRID_WIDTH; c++) {
+				row += blocks[r * GRID_WIDTH + c] ?? fg(CATEGORY_META.safeAvailable.hex, CATEGORY_META.safeAvailable.block);
+				if (c < GRID_WIDTH - 1) row += " ";
+			}
+			gridLines.push(row);
+		}
+		return gridLines;
+	}
+
+	private renderBreakdown(categories: Category[]): string[] {
+		const LABEL_W = 21;
+		const TOKEN_W = 7;
+
+		return categories.map((cat) => {
+			const pct = this.breakdown!.contextWindow > 0 ? (cat.value / this.breakdown!.contextWindow) * 100 : 0;
+			const icon = fg(cat.hex, cat.icon);
+			const label = fg(cat.hex, cat.label.padEnd(LABEL_W));
+			const tokens = fg(cat.hex, formatTokens(cat.value).padStart(TOKEN_W));
+			const percent = this.theme.fg("dim", `(${pct.toFixed(1).padStart(5)}%)`);
+			return `${icon} ${label} ${tokens} ${percent}`;
+		});
+	}
+}

package/src/tabbed-overlay.ts

@@ -0,0 +1,162 @@
+/**
+ * TabbedOverlay — a bordered overlay with a tab bar at the top.
+ *
+ * Manages multiple tab views (StatsTabContent, ScrollableTabContent) and renders
+ * the full frame (title, tab bar, borders, footer). Each tab handles its own content
+ * rendering and keyboard input.
+ *
+ * Navigation:
+ *   Tab / Shift+Tab  → cycle between tabs
+ *   Escape / q       → close the overlay (unless a tab has intercepted the key)
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+import { createBorderHelpers, createTitle, CONTENT_HEIGHT } from "./utils.js";
+
+/**
+ * Interface that each tab must implement.
+ *
+ * Key contract: `handleInput` returns `true` if the key was consumed (so the
+ * outer overlay won't act on it). This lets content tabs swallow Escape when
+ * in search mode rather than closing the overlay.
+ */
+export interface TabContent {
+	readonly name: string;
+
+	/**
+	 * Returns a styled string to render between the tab bar and the content area,
+	 * or `null` to render a plain border separator.
+	 * Used by scrollable tabs for the live search / match-info row.
+	 */
+	getAboveContentLine(innerWidth: number): string | null;
+
+	/** Render exactly `height` lines of content. */
+	renderContent(innerWidth: number, height: number): string[];
+
+	/** Left portion of the footer row (e.g. scroll position, copy flash). */
+	getFooterLeft(): string;
+
+	/** Hint items shown in the footer (right side). Omit Tab / q hints — they are added by TabbedOverlay. */
+	readonly footerHints: string;
+
+	/**
+	 * Handle a keyboard event. Return `true` if consumed (prevents TabbedOverlay
+	 * from acting on the key), `false` to let the outer overlay handle it.
+	 */
+	handleInput(data: string): boolean;
+
+	/** Reset any cached rendering state. */
+	invalidate(): void;
+}
+
+export interface TabbedOverlayOptions {
+	/** Title text shown in the top header row. */
+	title: string;
+	/** Subtitle / stats text shown dimmed after the title. */
+	subtitle: string;
+	/** Ordered list of tab views. */
+	tabs: TabContent[];
+	/** Active theme. */
+	theme: Theme;
+	/** Called when the user closes the overlay (Escape / q). */
+	done: () => void;
+}
+
+export class TabbedOverlay {
+	private activeTabIndex = 0;
+
+	constructor(private opts: TabbedOverlayOptions) {}
+
+	private get activeTab(): TabContent {
+		return this.opts.tabs[this.activeTabIndex]!;
+	}
+
+	handleInput(data: string): void {
+		// Tab / Shift+Tab always switch tabs (not delegated to content).
+		if (matchesKey(data, Key.tab)) {
+			this.activeTabIndex = (this.activeTabIndex + 1) % this.opts.tabs.length;
+			return;
+		}
+		if (matchesKey(data, Key.shift("tab"))) {
+			this.activeTabIndex = (this.activeTabIndex - 1 + this.opts.tabs.length) % this.opts.tabs.length;
+			return;
+		}
+
+		// Delegate to the active tab first. If it consumes the key, stop.
+		const consumed = this.activeTab.handleInput(data);
+		if (consumed) return;
+
+		// Outer-level: close the overlay.
+		if (matchesKey(data, Key.escape) || data === "q") {
+			this.opts.done();
+		}
+	}
+
+	render(width: number): string[] {
+		const th = this.opts.theme;
+		const innerW = width - 2;
+		const lines: string[] = [];
+
+		const { row, borderTop, borderSep, borderBottom } = createBorderHelpers(th, innerW);
+		const title = createTitle(th, this.opts.title, this.opts.subtitle);
+
+		lines.push(borderTop);
+		lines.push(row(title));
+
+		// ── Tab bar ─────────────────────────────────────────────────────────────
+		let tabBar = " ";
+		for (let i = 0; i < this.opts.tabs.length; i++) {
+			const tab = this.opts.tabs[i]!;
+			if (i === this.activeTabIndex) {
+				tabBar += th.fg("accent", th.bold(`[${tab.name}]`));
+			} else {
+				tabBar += th.fg("dim", `[${tab.name}]`);
+			}
+			if (i < this.opts.tabs.length - 1) tabBar += " ";
+		}
+		lines.push(row(tabBar));
+
+		// ── Above-content row (search bar or border) ─────────────────────────────
+		const aboveLine = this.activeTab.getAboveContentLine(innerW);
+		if (aboveLine !== null) {
+			lines.push(row(` ${aboveLine}`));
+		} else {
+			lines.push(borderSep);
+		}
+
+		// ── Content area ─────────────────────────────────────────────────────────
+		const contentLines = this.activeTab.renderContent(innerW, CONTENT_HEIGHT);
+		for (let i = 0; i < CONTENT_HEIGHT; i++) {
+			if (i < contentLines.length) {
+				lines.push(row(contentLines[i]!));
+			} else {
+				lines.push(row(th.fg("dim", "~")));
+			}
+		}
+
+		// ── Footer ───────────────────────────────────────────────────────────────
+		lines.push(borderSep);
+
+		const footerLeft = this.activeTab.getFooterLeft();
+		const tabHints = this.opts.tabs.length > 1 ? "Tab switch" : "";
+		const activeHints = this.activeTab.footerHints;
+		const hintParts = [tabHints, activeHints, "q close"].filter(Boolean);
+		const footerHintsText = th.fg("dim", hintParts.join(" · "));
+
+		let footerContent = footerHintsText;
+		if (footerLeft) {
+			footerContent = th.fg("dim", ` ${footerLeft}  `) + footerHintsText;
+		}
+		lines.push(row(footerContent));
+		lines.push(borderBottom);
+
+		return lines;
+	}
+
+	invalidate(): void {
+		for (const tab of this.opts.tabs) {
+			tab.invalidate();
+		}
+	}
+}

package/src/utils.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared utility helpers for pi-context-inspector.
+ */
+
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+export const formatTokens = (n: number | null | undefined): string => {
+	if (n == null) return "N/A";
+	if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+	if (n >= 1_000) return `${Math.min(999, Math.round(n / 1_000))}k`;
+	return n.toString();
+};
+
+export const CONTENT_HEIGHT = 28;
+
+export interface BorderHelpers {
+  pad: (s: string, len: number) => string;
+  row: (content: string) => string;
+  borderTop: string;
+  borderSep: string;
+  borderBottom: string;
+}
+
+export function createBorderHelpers(th: Theme, innerW: number): BorderHelpers {
+  const pad = (s: string, len: number) => s + " ".repeat(Math.max(0, len - visibleWidth(s)));
+  const row = (content: string) => th.fg("border", "│") + pad(content, innerW) + th.fg("border", "│");
+  const borderTop = th.fg("border", `╭${"─".repeat(innerW)}╮`);
+  const borderSep = th.fg("border", `├${"─".repeat(innerW)}┤`);
+  const borderBottom = th.fg("border", `╰${"─".repeat(innerW)}╯`);
+  return { pad, row, borderTop, borderSep, borderBottom };
+}
+
+export function createTitle(th: Theme, title: string, subtitle: string): string {
+  return ` ${th.fg("accent", th.bold(title))}  ${th.fg("dim", `(${subtitle})`)}`;
+}