@agnishc/edb-context-viewer 0.8.1 → 0.10.3

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.10.3] - 2026-05-15
+
+## [0.9.0] - 2026-05-15
+
+### Changed
+- Replaced `/system-prompt-data` and `/total-context-data` commands with a single unified `/context-viewer` command
+- New tabbed overlay UI with five tabs: **Stats**, **System**, **Tools**, **Messages**, **Full**
+- Tab navigation with `Tab` / `Shift+Tab`
+
+### Added
+- **Stats tab** — token distribution grid (10×5 colored blocks) + per-category breakdown table, inspired by [pi-context](https://github.com/ttttmr/pi-context)
+- **Tools tab** — scrollable view of all active tool definitions with parameter schemas
+- `formatTokens` utility (k/M suffixes)
+- `StatsTabContent`, `ScrollableTabContent`, `TabbedOverlay` components
+
+## [0.8.2] - 2026-05-11
+
 ## [0.8.1] - 2026-05-11
 
 ## [0.6.0] - 2026-05-11

package/README.md

@@ -1,25 +1,45 @@
 # @agnishc/edb-context-viewer
 
-Pi CLI extension for inspecting the LLM context. Two commands let you see exactly what the model sees:
+Pi CLI extension for inspecting the full LLM context. A single command opens a tabbed overlay where you can explore token usage, the system prompt, tool definitions, messages, and the complete context — all in one place.
 
-- **`/system-prompt-data`** — full system prompt with line numbers
-- **`/total-context-data`** — complete LLM context (system prompt + all messages + usage stats)
+## Command
 
-Both open as scrollable overlay popups with search and clipboard copy.
+```
+/context-viewer
+```
+
+Opens a tabbed overlay with five views you can navigate using `Tab` / `Shift+Tab`.
+
+## Tabs
+
+| Tab | What it shows |
+|-----|--------------|
+| **Stats** | Token distribution grid (10×5 colored blocks) + per-category breakdown table |
+| **System** | The full system prompt (includes tools, skills, guidelines, AGENTS.md, etc.) |
+| **Tools** | All active tool definitions with descriptions and parameter schemas |
+| **Messages** | All session messages (user, assistant, tool calls/results) |
+| **Full** | Complete context dump: system prompt + messages + usage stats |
+
+### Stats tab
+
+Visualizes how the context window is used, broken down by category:
 
-## Commands
+- **System Prompt** — the static system prompt text
+- **System Tools** — tool definition schemas
+- **Tool Calls** — tool call arguments and results
+- **Messages** — user/assistant conversation text
+- **Available** — unused context window space
 
-| Command | What it shows |
-|---------|--------------|
-| `/system-prompt-data` | The full system prompt (includes tools, skills, guidelines, AGENTS.md, etc.) |
-| `/total-context-data` | System prompt + all messages (user, assistant, tool calls/results) + context usage stats |
+Token counts are estimated using a 4-chars-per-token heuristic, then scaled proportionally to match the actual total reported by the API.
 
 ## Controls
 
 | Key | Action |
 |-----|--------|
-| `↑` / `k` | Scroll up |
-| `↓` / `j` | Scroll down |
+| `Tab` | Next tab |
+| `Shift+Tab` | Previous tab |
+| `↑` / `k` | Scroll up (content tabs) |
+| `↓` / `j` | Scroll down (content tabs) |
 | `Page Up` / `Ctrl+B` | Scroll up one page |
 | `Page Down` / `Ctrl+F` | Scroll down one page |
 | `Ctrl+U` / `Ctrl+D` | Scroll half page |
@@ -28,7 +48,7 @@ Both open as scrollable overlay popups with search and clipboard copy.
 | `/` | Search (live matching as you type) |
 | `n` / `N` | Next / previous match |
 | `y` | Copy full content to clipboard |
-| `Escape` / `q` | Close popup |
+| `Escape` / `q` | Close overlay |
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agnishc/edb-context-viewer",
-	"version": "0.8.1",
+	"version": "0.10.3",
 	"description": "Pi extension: inspect the system prompt and full LLM context in scrollable overlay popups",
 	"keywords": [
 		"pi-package",

package/src/index.ts

@@ -1,12 +1,17 @@
 /**
- * pi-context-viewer
+ * edb-context-viewer
  *
- * Two commands for inspecting what the LLM sees:
+ * Single command for inspecting the full LLM context in a tabbed overlay:
  *
- *   /system-prompt-data  — shows the full system prompt in a scrollable overlay
- *   /total-context-data  — shows the complete LLM context (system prompt + all messages)
+ *   /context-viewer  — 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)
  *
- * Both overlays support: line numbers, scroll, live search (/), clipboard copy (y).
+ * Tab / Shift+Tab navigates between views.
+ * Each content tab supports: line numbers, scroll, live search (/), clipboard copy (y).
  */
 
 import {
@@ -17,7 +22,10 @@ import {
 	type SessionContext,
 	type Theme,
 } from "@earendil-works/pi-coding-agent";
-import { ScrollableOverlay } from "./scrollable-overlay";
+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";
 
 // ── Helpers ────────────────────────────────────────────────────────────────────
 
@@ -156,66 +164,188 @@ export function buildTotalContextText(
 	return sections.join("\n");
 }
 
-/** Overlay options shared by both commands. */
+/** Format active tool definitions as readable text for the Tools tab. */
+function buildToolsText(activeToolDefs: { name: string; description?: string; parameters?: unknown }[]): 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 any;
+			if (params?.properties) {
+				for (const [key, val] of Object.entries(params.properties)) {
+					const v = val as any;
+					const required = params.required?.includes(key) ? "" : " (optional)";
+					const type = v.type ?? "unknown";
+					const desc = v.description ? `: ${v.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 buildTokenBreakdown(
+	systemPrompt: string,
+	activeToolDefs: unknown[],
+	branch: { type: string; message?: any; summary?: string }[],
+	usage: ContextUsage | undefined,
+): ContextTokenBreakdown | null {
+	if (!usage?.tokens || !usage.contextWindow) return null;
+
+	const estimateTokens = (text: string) => Math.ceil(text.length / 4);
+
+	const systemRaw = estimateTokens(systemPrompt);
+	const toolDefsRaw = estimateTokens(JSON.stringify(activeToolDefs));
+
+	let msgTokensRaw = 0;
+	let toolCallTokensRaw = 0;
+	let toolResultTokensRaw = 0;
+
+	for (const entry of branch) {
+		if (entry.type === "message" && entry.message) {
+			const m = entry.message;
+
+			if (m.role === "user") {
+				if (typeof m.content === "string") msgTokensRaw += estimateTokens(m.content);
+				else if (Array.isArray(m.content)) {
+					for (const p of m.content) {
+						if (p?.type === "text") msgTokensRaw += estimateTokens(p.text ?? "");
+					}
+				}
+			} else if (m.role === "assistant") {
+				if (typeof m.content === "string") msgTokensRaw += estimateTokens(m.content);
+				else if (Array.isArray(m.content)) {
+					for (const p of m.content) {
+						if (p?.type === "text") msgTokensRaw += estimateTokens(p.text ?? "");
+						else if (p?.type === "toolCall") toolCallTokensRaw += estimateTokens(JSON.stringify(p));
+					}
+				}
+			} else if (m.role === "toolResult") {
+				if (Array.isArray(m.content)) {
+					for (const p of m.content) {
+						if (p?.type === "text") toolResultTokensRaw += estimateTokens(p.text ?? "");
+					}
+				}
+			} else if (m.role === "bashExecution") {
+				toolCallTokensRaw += estimateTokens(m.command ?? "");
+				toolResultTokensRaw += estimateTokens(m.output ?? "");
+			}
+		} else if (entry.type === "branch_summary" || entry.type === "compaction") {
+			msgTokensRaw += estimateTokens((entry as any).summary ?? "");
+		}
+	}
+
+	const totalRaw = systemRaw + toolDefsRaw + msgTokensRaw + toolCallTokensRaw + toolResultTokensRaw;
+	const ratio = totalRaw > 0 ? usage.tokens / totalRaw : 1;
+
+	const sys = Math.round(systemRaw * ratio);
+	const tools = Math.round(toolDefsRaw * ratio);
+	const msgs = Math.round(msgTokensRaw * ratio);
+	const toolCalls = Math.round((toolCallTokensRaw + toolResultTokensRaw) * ratio);
+	const accounted = sys + tools + msgs + toolCalls;
+
+	return {
+		total: usage.tokens,
+		contextWindow: usage.contextWindow,
+		percent: usage.percent ?? (usage.tokens / usage.contextWindow) * 100,
+		systemPrompt: sys,
+		systemTools: tools,
+		toolCalls,
+		messages: msgs,
+		other: Math.max(0, usage.tokens - accounted),
+	};
+}
+
+/** Overlay options shared across all tabs. */
 const OVERLAY_OPTIONS = {
 	overlay: true,
 	overlayOptions: {
 		anchor: "center" as const,
 		width: "90%" as const,
 		minWidth: 60,
-		maxHeight: "80%" as const,
+		maxHeight: "90%" as const,
 	},
 };
 
 // ── Extension ──────────────────────────────────────────────────────────────────
 
 export default function contextViewerExtension(pi: ExtensionAPI): void {
-	// ── /system-prompt-data ──
-	pi.registerCommand("system-prompt-data", {
-		description: "Show the full system prompt in a scrollable popup",
+	pi.registerCommand("context-viewer", {
+		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;
 
-			const systemPrompt = ctx.getSystemPrompt();
-			if (!systemPrompt) {
-				ctx.ui.notify("No system prompt available yet. Send a message first.", "warning");
-				return;
-			}
+			// ── Gather data ─────────────────────────────────────────────────────
+			const systemPrompt = ctx.getSystemPrompt() ?? "";
+			const usage = ctx.getContextUsage();
 
-			const lineCount = systemPrompt.split("\n").length;
-			const charCount = systemPrompt.length;
+			const allTools = pi.getAllTools();
+			const activeToolNames = pi.getActiveTools();
+			const activeToolDefs = allTools.filter((t) => activeToolNames.includes(t.name));
 
-			await ctx.ui.custom<void>((_tui, theme, _keybindings, done) => {
-				const displayLines = buildNumberedLines(systemPrompt, theme);
-				return new ScrollableOverlay({
-					title: "System Prompt",
-					subtitle: `${charCount.toLocaleString()} chars · ${lineCount} lines`,
-					rawText: systemPrompt,
-					displayLines,
-					theme,
-					done,
-				});
-			}, OVERLAY_OPTIONS);
-		},
-	});
+			const branch = ctx.sessionManager.getBranch();
+			const context = buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId());
 
-	// ── /total-context-data ──
-	pi.registerCommand("total-context-data", {
-		description: "Show the complete LLM context (system prompt + all messages)",
-		handler: async (_args: string, ctx: ExtensionCommandContext) => {
-			if (!ctx.hasUI) return;
+			const breakdown = buildTokenBreakdown(systemPrompt, activeToolDefs, branch, usage);
+			const toolsText = buildToolsText(activeToolDefs);
+			const fullText = buildTotalContextText(systemPrompt, context, usage, ctx.model);
 
-			const systemPrompt = ctx.getSystemPrompt() ?? "";
-			const context = buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId());
-			const fullText = buildTotalContextText(systemPrompt, context, ctx.getContextUsage(), ctx.model);
+			// ── 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 displayLines = buildNumberedLines(fullText, theme);
-				return new ScrollableOverlay({
-					title: "Total Context Data",
-					subtitle: `${fullText.length.toLocaleString()} chars · ${displayLines.length} lines`,
-					rawText: fullText,
-					displayLines,
+				// Build messages text for the Messages tab
+				const messagesLines: string[] = [];
+				if (context.messages.length > 0) {
+					for (let i = 0; i < context.messages.length; i++) {
+						messagesLines.push(...formatMessageForDisplay(context.messages[i]!, i));
+					}
+				} else {
+					messagesLines.push("(no messages yet)");
+				}
+				const messagesText = messagesLines.join("\n");
+
+				const tabs = [
+					new StatsTabContent(breakdown, theme),
+					new ScrollableTabContent(
+						{ rawText: systemPrompt, displayLines: buildNumberedLines(systemPrompt, theme), theme },
+						"System",
+					),
+					new ScrollableTabContent(
+						{ rawText: toolsText, displayLines: buildNumberedLines(toolsText, theme), theme },
+						"Tools",
+					),
+					new ScrollableTabContent(
+						{ rawText: messagesText, displayLines: buildNumberedLines(messagesText, theme), theme },
+						"Messages",
+					),
+					new ScrollableTabContent(
+						{ rawText: fullText, displayLines: buildNumberedLines(fullText, theme), theme },
+						"Full",
+					),
+				];
+
+				return new TabbedOverlay({
+					title: "Context Viewer",
+					subtitle,
+					tabs,
 					theme,
 					done,
 				});

package/src/scrollable-tab-content.ts

@@ -0,0 +1,281 @@
+/**
+ * ScrollableTabContent — scrollable text viewer for use inside TabbedOverlay.
+ *
+ * Same scroll/search/copy logic as ScrollableOverlay, but without an outer frame.
+ * Renders only the content lines; the outer frame is handled by TabbedOverlay.
+ */
+
+import { copyToClipboard as copyTextToClipboard, type Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import type { TabContent } from "./tabbed-overlay.js";
+
+export interface ScrollableTabContentOptions {
+	/** The raw text to display (used for search & clipboard) */
+	rawText: string;
+	/** The styled display lines (with ANSI formatting, line numbers, etc.) */
+	displayLines: string[];
+	/** Active theme */
+	theme: Theme;
+}
+
+export class ScrollableTabContent implements TabContent {
+	private scrollOffset = 0;
+
+	// Search state
+	private searchMode = false;
+	private searchQuery = "";
+	private searchMatches: number[] = [];
+	private currentMatchIndex = -1;
+	private copyFlash = false;
+
+	constructor(
+		private opts: ScrollableTabContentOptions,
+		public readonly name: string = "",
+	) {}
+
+	/**
+	 * Returns the above-content line (search bar or match info),
+	 * or null if a plain border separator should be rendered.
+	 */
+	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}`)}`;
+		}
+		return null;
+	}
+
+	getFooterLeft(): string {
+		const th = this.opts.theme;
+		const total = 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";
+
+	/**
+	 * Handle keyboard input. Returns true if the key was consumed (prevents outer
+	 * overlay from acting on it — e.g. so Escape exits search mode instead of
+	 * closing the overlay).
+	 */
+	handleInput(data: string): boolean {
+		if (this.searchMode) {
+			if (matchesKey(data, Key.escape)) {
+				this.searchMode = false;
+				this.searchQuery = "";
+				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.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();
+				}
+				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();
+				}
+				return true;
+			}
+			return true; // swallow all other keys in search mode
+		}
+
+		// Normal mode — handle scroll/search/copy, NOT q/Escape (those go to TabbedOverlay)
+		if (matchesKey(data, Key.down) || data === "j") {
+			this.scrollDown(1);
+			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();
+			return true;
+		}
+		if (matchesKey(data, Key.pageDown) || matchesKey(data, Key.ctrl("f"))) {
+			this.scrollDown(28);
+			return true;
+		}
+		if (matchesKey(data, Key.pageUp) || matchesKey(data, Key.ctrl("b"))) {
+			this.scrollUp(28);
+			return true;
+		}
+		if (matchesKey(data, Key.ctrl("d"))) {
+			this.scrollDown(14);
+			return true;
+		}
+		if (matchesKey(data, Key.ctrl("u"))) {
+			this.scrollUp(14);
+			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; // not consumed — let TabbedOverlay handle it
+	}
+
+	renderContent(innerWidth: number, height: number): string[] {
+		const th = this.opts.theme;
+		const lines: string[] = [];
+		const total = this.opts.displayLines.length;
+
+		// Clamp scroll offset
+		const maxScroll = Math.max(0, total - 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 < total) {
+				let line = this.opts.displayLines[lineIdx]!;
+
+				const isCurrentMatch =
+					this.searchMatches.length > 0 &&
+					this.currentMatchIndex >= 0 &&
+					this.searchMatches[this.currentMatchIndex] === lineIdx;
+				const isOtherMatch =
+					this.searchMatches.length > 0 && this.searchMatches.includes(lineIdx) && !isCurrentMatch;
+
+				if (isCurrentMatch) {
+					line = th.bg("selectedBg", truncateToWidth(line, innerWidth));
+				} else if (isOtherMatch) {
+					line = th.fg("warning", truncateToWidth(line, innerWidth));
+				} else {
+					line = truncateToWidth(line, innerWidth);
+				}
+
+				lines.push(line);
+			} else {
+				lines.push(th.fg("dim", "~"));
+			}
+		}
+
+		return lines;
+	}
+
+	invalidate(): void {
+		// No cached state
+	}
+
+	// ── Private helpers ────────────────────────────────────────────────────────
+
+	private scrollDown(amount: number): void {
+		const maxOffset = Math.max(0, this.opts.displayLines.length - 1);
+		this.scrollOffset = Math.min(this.scrollOffset + amount, maxOffset);
+	}
+
+	private scrollUp(amount: number): void {
+		this.scrollOffset = Math.max(0, this.scrollOffset - amount);
+	}
+
+	private scrollToBottom(): void {
+		this.scrollOffset = Math.max(0, this.opts.displayLines.length - 1);
+	}
+
+	private findMatches(): void {
+		const query = this.searchQuery.toLowerCase();
+		const rawLines = this.opts.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);
+			}
+		}
+	}
+
+	private scrollToMatch(): void {
+		if (this.currentMatchIndex >= 0 && this.currentMatchIndex < this.searchMatches.length) {
+			const targetLine = this.searchMatches[this.currentMatchIndex]!;
+			const visibleLines = 28; // approximate; TabbedOverlay uses CONTENT_HEIGHT
+			if (targetLine < this.scrollOffset || targetLine >= this.scrollOffset + visibleLines) {
+				this.scrollOffset = Math.max(0, targetLine - Math.floor(visibleLines / 3));
+			}
+		}
+	}
+
+	private nextMatch(): void {
+		if (this.searchMatches.length === 0) return;
+		this.currentMatchIndex = (this.currentMatchIndex + 1) % this.searchMatches.length;
+		this.scrollToMatch();
+	}
+
+	private prevMatch(): void {
+		if (this.searchMatches.length === 0) return;
+		this.currentMatchIndex = (this.currentMatchIndex - 1 + this.searchMatches.length) % this.searchMatches.length;
+		this.scrollToMatch();
+	}
+
+	private async copyToClipboard(): Promise<void> {
+		this.copyFlash = true;
+		try {
+			await copyTextToClipboard(this.opts.rawText);
+		} catch {
+			// Silently fail if clipboard tools aren't available
+		}
+		setTimeout(() => {
+			this.copyFlash = false;
+		}, 1500);
+	}
+}

package/src/stats-tab-content.ts

@@ -0,0 +1,174 @@
+/**
+ * StatsTabContent — token distribution grid + category breakdown table.
+ *
+ * Adapts the visual dashboard from pi-context (github.com/ttttmr/pi-context)
+ * for use inside TabbedOverlay. Shows a colored 10×5 block grid on the left and
+ * a per-category token breakdown on the right.
+ */
+
+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
+
+export interface ContextTokenBreakdown {
+	total: number;
+	contextWindow: number;
+	percent: number;
+	systemPrompt: number;
+	systemTools: number;
+	toolCalls: number;
+	messages: number;
+	other: number;
+}
+
+interface Category {
+	label: string;
+	value: number;
+	color: string;
+}
+
+export class StatsTabContent implements TabContent {
+	readonly name = "Stats";
+	readonly footerHints = "";
+
+	constructor(
+		private breakdown: ContextTokenBreakdown | null,
+		private theme: Theme,
+	) {}
+
+	/** 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 } = this.breakdown;
+		return `${formatTokens(total)} / ${formatTokens(contextWindow)} (${percent.toFixed(1)}%)`;
+	}
+
+	/** 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-viewer.")}`,
+			];
+			while (lines.length < height) lines.push("");
+			return lines;
+		}
+
+		const { total, contextWindow, percent, systemPrompt, systemTools, toolCalls, messages, other } = this.breakdown;
+
+		const categories: Category[] = [
+			{ label: "System Prompt", value: systemPrompt, color: "muted" },
+			{ label: "System Tools", value: systemTools, color: "dim" },
+			{ label: "Tool Calls", value: toolCalls, color: "success" },
+			{ label: "Messages", value: messages, color: "accent" },
+		];
+
+		if (other > 10) {
+			categories.push({ label: "Other", value: other, color: "dim" });
+		}
+
+		const available = Math.max(0, contextWindow - total);
+
+		// ── Build grid blocks ────────────────────────────────────────────────────
+		const blocks: { color: string; filled: boolean }[] = [];
+		for (const cat of categories) {
+			let count = Math.round((cat.value / contextWindow) * TOTAL_BLOCKS);
+			if (count === 0 && cat.value > 0) count = 1;
+			for (let i = 0; i < count && blocks.length < TOTAL_BLOCKS; i++) {
+				blocks.push({ color: cat.color, filled: true });
+			}
+		}
+		while (blocks.length < TOTAL_BLOCKS) {
+			blocks.push({ color: "borderMuted", filled: false });
+		}
+
+		// ── Render grid rows ─────────────────────────────────────────────────────
+		const gridLines: string[] = [];
+		for (let r = 0; r < GRID_HEIGHT; r++) {
+			let row = "";
+			for (let c = 0; c < GRID_WIDTH; c++) {
+				const b = blocks[r * GRID_WIDTH + c]!;
+				row += th.fg(b.color as Parameters<typeof th.fg>[0], b.filled ? "■" : "□");
+				if (c < GRID_WIDTH - 1) row += " ";
+			}
+			gridLines.push(row);
+		}
+
+		// ── Build legend ─────────────────────────────────────────────────────────
+		const LABEL_W = 14;
+		const TOKEN_W = 7;
+
+		const legendLines: string[] = [];
+
+		// Total usage line (bold, no icon)
+		legendLines.push(
+			`  ${th.bold(th.fg("text", "Total Usage".padEnd(LABEL_W + 2)))} ` +
+				`${th.fg("accent", formatTokens(total).padStart(TOKEN_W))} ` +
+				`${th.fg("dim", `(${percent.toFixed(1).padStart(5)}%)`)}`,
+		);
+		legendLines.push(""); // blank separator before categories
+
+		// Per-category lines
+		for (const cat of categories) {
+			const pct = ((cat.value / contextWindow) * 100).toFixed(1);
+			legendLines.push(
+				`${th.fg(cat.color as Parameters<typeof th.fg>[0], "■")} ` +
+					`${th.fg("text", cat.label.padEnd(LABEL_W))} ` +
+					`${th.fg("accent", formatTokens(cat.value).padStart(TOKEN_W))} ` +
+					`${th.fg("dim", `(${pct.padStart(5)}%)`)}`,
+			);
+		}
+
+		// Available line
+		const availPct = ((available / contextWindow) * 100).toFixed(1);
+		legendLines.push(
+			`${th.fg("borderMuted" as Parameters<typeof th.fg>[0], "□")} ` +
+				`${th.fg("dim", "Available".padEnd(LABEL_W))} ` +
+				`${th.fg("dim", formatTokens(available).padStart(TOKEN_W))} ` +
+				`${th.fg("dim", `(${availPct.padStart(5)}%)`)}`,
+		);
+
+		// ── Combine grid + legend side by side ───────────────────────────────────
+		// Grid visible width: GRID_WIDTH * 2 - 1 (each "■ " or "□ " = 2, minus trailing space)
+		const GRID_VIS_W = GRID_WIDTH * 2 - 1;
+		const maxRows = Math.max(gridLines.length, legendLines.length);
+
+		const combined: string[] = [];
+		combined.push(""); // top padding
+
+		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 = legendLines[i] ?? "";
+			combined.push(`    ${leftRaw}${pad}    ${right}`);
+		}
+
+		combined.push(""); // bottom padding
+
+		// Fill or truncate to content height
+		const result: string[] = [];
+		for (let i = 0; i < height; i++) {
+			result.push(combined[i] ?? "");
+		}
+		return result;
+	}
+}

package/src/tabbed-overlay.ts

@@ -0,0 +1,173 @@
+/**
+ * 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, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+/** Number of lines shown in the content area of each tab. */
+export const CONTENT_HEIGHT = 28;
+
+/**
+ * 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[] = [];
+
+		// ANSI-aware padding: pad styled string to `len` visible columns.
+		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)}╯`);
+
+		// ── Top border ──────────────────────────────────────────────────────────
+		lines.push(borderTop);
+
+		// ── Title row ───────────────────────────────────────────────────────────
+		const title = ` ${th.fg("accent", th.bold(this.opts.title))}  ${th.fg("dim", `(${this.opts.subtitle})`)}`;
+		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(truncateToWidth(contentLines[i]!, innerW)));
+			} 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,11 @@
+/**
+ * Shared utility helpers for edb-context-viewer.
+ */
+
+/** Format a token count as a human-readable string (e.g. 45k, 1.2M). */
+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.round(n / 1_000)}k`;
+	return n.toString();
+};