pi-context-inspector 1.1.1 → 1.3.0

package/README.md

@@ -9,7 +9,7 @@ Opens a tabbed overlay with the full LLM context of the current session in [pi-c
 - **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.
+- **Scroll, search, copy, or inspect in an editor.** Every content tab supports vim style scrolling, live `/` search with match navigation, `y` to copy the raw text, and `e` to open a snapshot in `$EDITOR`.
 - **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
@@ -20,7 +20,7 @@ Run `/context` at any point during a session:
 /context
 ```
 
-The overlay opens with the Stats tab active. `Tab` / `Shift+Tab` cycles tabs, `q` or `Escape` closes the overlay.
+The overlay opens with the Stats tab active. `Tab` / `Shift+Tab` cycles tabs, `q` or `Escape` closes the overlay. On System, Tools, Messages, or Full, press `e` to open that view in `$EDITOR`. Pi resumes when the editor exits. Any edits to the temporary file are discarded and do not change the session. The editor removes color codes from tool results in Messages and Full; the overlay and copied text keep the original content. Stats and Skills do not have editor views; Skills is a category in Stats, not a separate tab.
 
 ## Installation
 
@@ -55,6 +55,7 @@ pi install /path/to/pi-context-inspector
 | `/` | Live search (type, `Enter` to commit) |
 | `n` / `N` | Next / previous match |
 | `y` | Copy the tab's raw text to the clipboard |
+| `e` | Open the current text tab in `$EDITOR` |
 | `q` / `Escape` | Close the overlay |
 
 ## How the token breakdown works
@@ -65,6 +66,7 @@ Each category is estimated from raw text (chars ÷ 4, using pi's own per-message
 
 - **"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.
+- **The editor doesn't open.** Set `$EDITOR` to a terminal editor command, such as `vim` or `code --wait`. The command must stay open until you finish viewing the file.
 - **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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-context-inspector",
   "author": "yuriteixeira",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "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",
@@ -39,11 +39,11 @@
     "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"
+    "@earendil-works/pi-coding-agent": "^0.87.0",
+    "@earendil-works/pi-tui": "^0.87.0",
+    "@types/node": "^26.6.2",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.1"
   },
   "scripts": {
     "test": "vitest run",

package/src/editor-colors.test.ts

@@ -0,0 +1,42 @@
+import type { SessionContext } from "@earendil-works/pi-coding-agent";
+import { describe, expect, it } from "vitest";
+import { buildTotalContextText, formatMessagesText } from "./index.js";
+
+const red = "\x1b[31m";
+const trueColor = "\x1b[38;2;255;0;0m";
+const reset = "\x1b[0m";
+const context = {
+	messages: [
+		{ role: "user", content: `${red}user${reset}` },
+		{
+			role: "toolResult",
+			toolName: "bash",
+			toolCallId: "1",
+			isError: false,
+			content: [
+				{ type: "text", text: `${red}error${reset}\n${trueColor}detail${reset}` },
+				{ type: "image", mimeType: "image/png" },
+			],
+		},
+	],
+} as SessionContext;
+
+describe("editor tool result colors", () => {
+	it("removes color codes only from tool results in the editor message view", () => {
+		const overlay = formatMessagesText(context);
+		const editor = formatMessagesText(context, true);
+		expect(overlay).toContain(`${red}error${reset}`);
+		expect(overlay).toContain(`${trueColor}detail${reset}`);
+		expect(editor).toContain("error\ndetail");
+		expect(editor).not.toContain(`${red}error`);
+		expect(editor).toContain(`${red}user${reset}`);
+		expect(editor).toContain("[Image: image/png]");
+	});
+
+	it("removes tool result colors in the editor full view without changing the system prompt", () => {
+		const full = buildTotalContextText(`${red}system${reset}`, context, undefined, undefined, true);
+		expect(full).toContain(`${red}system${reset}`);
+		expect(full).toContain("error\ndetail");
+		expect(full).not.toContain(`${trueColor}detail`);
+	});
+});

package/src/external-editor.test.ts

@@ -0,0 +1,49 @@
+import { readFile } from "node:fs/promises";
+import { EventEmitter } from "node:events";
+import type { TUI } from "@earendil-works/pi-tui";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { openInExternalEditor } from "./external-editor.js";
+
+const spawn = vi.hoisted(() => vi.fn());
+vi.mock("node:child_process", () => ({ spawn }));
+
+afterEach(() => {
+	vi.unstubAllEnvs();
+	spawn.mockReset();
+});
+
+describe("openInExternalEditor", () => {
+	it("opens the raw view, restores the terminal and removes the temporary file", async () => {
+		vi.stubEnv("EDITOR", "vim -R");
+		const events: string[] = [];
+		const tui = {
+			stop: () => events.push("stop"),
+			start: () => events.push("start"),
+			requestRender: () => events.push("render"),
+		} as unknown as TUI;
+		let path = "";
+		let content = "";
+		spawn.mockImplementation((_editor: string, args: string[]) => {
+			path = args.at(-1)!;
+			const child = new EventEmitter();
+			void readFile(path, "utf8").then((text) => {
+				content = text;
+				child.emit("close", 0);
+			});
+			return child;
+		});
+
+		await openInExternalEditor(tui, "Tools", "Tool: read\nParameters: {}\n");
+		expect(spawn).toHaveBeenCalledWith("vim", ["-R", path], expect.objectContaining({ stdio: "inherit" }));
+		expect(content).toBe("Tool: read\nParameters: {}\n");
+		expect(events).toEqual(["stop", "start", "render"]);
+		await expect(readFile(path, "utf8")).rejects.toMatchObject({ code: "ENOENT" });
+	});
+
+	it("does not stop the terminal without an editor", async () => {
+		vi.stubEnv("EDITOR", "");
+		const stop = vi.fn();
+		await expect(openInExternalEditor({ stop } as unknown as TUI, "Full", "text")).rejects.toThrow("Set $EDITOR");
+		expect(stop).not.toHaveBeenCalled();
+	});
+});

package/src/external-editor.ts

@@ -0,0 +1,32 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { TUI } from "@earendil-works/pi-tui";
+
+/** Show a snapshot in an external editor. Changes to the file do not change the session. */
+export async function openInExternalEditor(tui: TUI, name: string, text: string): Promise<void> {
+	const command = process.env.EDITOR?.trim();
+	if (!command) throw new Error("Set $EDITOR to open a context view in an editor.");
+
+	const directory = await mkdtemp(join(tmpdir(), "pi-context-"));
+	const filePath = join(directory, `${name.toLowerCase()}.txt`);
+	try {
+		await writeFile(filePath, text, { encoding: "utf8", mode: 0o600 });
+		const [editor, ...args] = command.split(/\s+/);
+		tui.stop();
+		try {
+			const exitCode = await new Promise<number>((resolve, reject) => {
+				const child = spawn(editor!, [...args, filePath], { stdio: "inherit", shell: process.platform === "win32" });
+				child.once("error", reject);
+				child.once("close", (code) => resolve(code ?? 1));
+			});
+			if (exitCode !== 0) throw new Error(`Editor exited with code ${exitCode}.`);
+		} finally {
+			tui.start();
+			tui.requestRender(true);
+		}
+	} finally {
+		await rm(directory, { recursive: true, force: true });
+	}
+}

package/src/index.ts

@@ -26,9 +26,10 @@ import {
 	type Theme,
 	type ToolInfo,
 } from "@earendil-works/pi-coding-agent";
+import { openInExternalEditor } from "./external-editor.js";
 import { ScrollableTabContent } from "./scrollable-tab-content.js";
 import { type ContextTokenBreakdown, StatsTabContent } from "./stats-tab-content.js";
-import { TabbedOverlay } from "./tabbed-overlay.js";
+import { OVERLAY_HEIGHT_PERCENT, TabbedOverlay } from "./tabbed-overlay.js";
 import { formatTokens } from "./utils.js";
 
 type AgentMessage = SessionContext["messages"][number];
@@ -48,21 +49,25 @@ export function buildNumberedLines(text: string, theme: Theme): string[] {
 	});
 }
 
-function numberedTab(text: string, name: string, theme: Theme): ScrollableTabContent {
+function numberedTab(text: string, name: string, theme: Theme, onOpenEditor: () => void): ScrollableTabContent {
 	return new ScrollableTabContent(
-		{ rawText: text, displayLines: buildNumberedLines(text, theme), theme },
+		{ rawText: text, displayLines: buildNumberedLines(text, theme), theme, onOpenEditor },
 		name,
 	);
 }
 
-function formatContent(content: MessageContent): string[] {
+function stripColorSequences(text: string): string {
+	return text.replace(/\x1b\[[0-9;:]*m/g, "");
+}
+
+function formatContent(content: MessageContent, stripColors = false): string[] {
 	if (typeof content === "string") return [content];
 
 	const lines: string[] = [];
 	for (const block of content) {
 		switch (block.type) {
 			case "text":
-				lines.push(block.text);
+				lines.push(stripColors ? stripColorSequences(block.text) : block.text);
 				break;
 			case "thinking":
 				lines.push(`[Thinking: ${block.thinking}]`);
@@ -89,7 +94,7 @@ function formatUsage(usage: AssistantMessage["usage"]): string {
 	parts.push(`total: ${usage.totalTokens}`);
 	return `Tokens: ${parts.join(", ")}`;
 }
-export function formatMessageForDisplay(message: SessionContext["messages"][number], index: number): string[] {
+export function formatMessageForDisplay(message: SessionContext["messages"][number], index: number, editorView = false): string[] {
 	const lines: string[] = ["", `──── Message ${index + 1} ────`, `Role: ${message.role}`];
 
 	if (message.role === "assistant") {
@@ -137,16 +142,16 @@ export function formatMessageForDisplay(message: SessionContext["messages"][numb
 	}
 
 	if ("content" in message) {
-		lines.push(...formatContent(message.content));
+		lines.push(...formatContent(message.content, editorView && message.role === "toolResult"));
 	}
 	return lines;
 }
 
-export function formatMessagesText(context: SessionContext): string {
+export function formatMessagesText(context: SessionContext, editorView = false): 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));
+			lines.push(...formatMessageForDisplay(context.messages[i]!, i, editorView));
 		}
 	} else {
 		lines.push("(no messages yet)");
@@ -165,6 +170,7 @@ export function buildTotalContextText(
 	context: SessionContext,
 	usage: ContextUsage | undefined,
 	model: ContextViewerModelInfo | undefined,
+	editorView = false,
 ): string {
 	const sections: string[] = [];
 
@@ -178,7 +184,7 @@ export function buildTotalContextText(
 	sections.push("MESSAGES");
 	sections.push("═══════════════════════════════════════════════════════");
 
-	sections.push(formatMessagesText(context));
+	sections.push(formatMessagesText(context, editorView));
 
 	sections.push("");
 	sections.push("═══════════════════════════════════════════════════════");
@@ -367,7 +373,7 @@ const OVERLAY_OPTIONS = {
 		anchor: "center" as const,
 		width: "90%" as const,
 		minWidth: 60,
-		maxHeight: "90%" as const,
+		maxHeight: `${OVERLAY_HEIGHT_PERCENT}%` as const,
 	},
 };
 
@@ -402,18 +408,30 @@ export default function contextViewerExtension(pi: ExtensionAPI): void {
 					: "no usage data yet";
 
 			// ── Build and open the overlay ──────────────────────────────────────
-			await ctx.ui.custom<void>((_tui, theme, _keybindings, done) => {
+			await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
 				const modelName = ctx.model?.id ?? "unknown model";
+				let editorOpen = false;
+				const editorAction = (name: string, text: string) => async () => {
+					if (editorOpen) return;
+					editorOpen = true;
+					try {
+						await openInExternalEditor(tui, name, text);
+					} catch (error) {
+						ctx.ui.notify(`Cannot open editor: ${error instanceof Error ? error.message : String(error)}`, "error");
+					} finally {
+						editorOpen = false;
+					}
+				};
 
 				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),
+					numberedTab(systemPrompt, "System", theme, editorAction("System", systemPrompt)),
+					numberedTab(toolsText, "Tools", theme, editorAction("Tools", toolsText)),
+					numberedTab(messagesText, "Messages", theme, editorAction("Messages", formatMessagesText(context, true))),
+					numberedTab(fullText, "Full", theme, editorAction("Full", buildTotalContextText(systemPrompt, context, usage, ctx.model, true))),
 				];
 
 				return new TabbedOverlay({
@@ -422,7 +440,7 @@ export default function contextViewerExtension(pi: ExtensionAPI): void {
 					tabs,
 					theme,
 					done,
-				});
+				}, tui);
 			}, OVERLAY_OPTIONS);
 		},
 	});

package/src/scrollable-base.ts

@@ -13,13 +13,14 @@ export abstract class ScrollableBase {
   protected visualLines: string[] = [];
   protected visualToLogical: number[] = [];
   protected visualTotal = 0;
+  protected visibleHeight = CONTENT_HEIGHT;
 
   protected abstract get rawText(): string;
   protected abstract get displayLines(): string[];
   protected abstract get theme(): Theme;
 
   protected getVisibleLines(): number {
-    return CONTENT_HEIGHT;
+    return this.visibleHeight;
   }
 
   protected buildVisualLines(innerWidth: number): void {
@@ -121,11 +122,11 @@ export abstract class ScrollableBase {
       return true;
     }
     if (matchesKey(data, Key.pageDown) || matchesKey(data, Key.ctrl("f"))) {
-      this.scrollDown(visibleLines - 2, maxOffset);
+      this.scrollDown(Math.max(1, visibleLines - 2), maxOffset);
       return true;
     }
     if (matchesKey(data, Key.pageUp) || matchesKey(data, Key.ctrl("b"))) {
-      this.scrollUp(visibleLines - 2);
+      this.scrollUp(Math.max(1, visibleLines - 2));
       return true;
     }
     if (matchesKey(data, Key.ctrl("d"))) {

package/src/scrollable-tab-content.test.ts

@@ -0,0 +1,20 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { describe, expect, it, vi } from "vitest";
+import { ScrollableTabContent } from "./scrollable-tab-content.js";
+
+describe("editor shortcut", () => {
+	it("opens the text tab but lets search accept the letter e", () => {
+		const onOpenEditor = vi.fn();
+		const tab = new ScrollableTabContent({
+			rawText: "example",
+			displayLines: ["example"],
+			theme: {} as Theme,
+			onOpenEditor,
+		}, "Tools");
+		expect(tab.handleInput("e")).toBe(true);
+		expect(onOpenEditor).toHaveBeenCalledOnce();
+		tab.handleInput("/");
+		tab.handleInput("e");
+		expect(onOpenEditor).toHaveBeenCalledOnce();
+	});
+});

package/src/scrollable-tab-content.ts

@@ -6,6 +6,7 @@ export interface ScrollableTabContentOptions {
   rawText: string;
   displayLines: string[];
   theme: Theme;
+  onOpenEditor?: () => void;
 }
 
 export class ScrollableTabContent extends ScrollableBase implements TabContent {
@@ -56,13 +57,21 @@ export class ScrollableTabContent extends ScrollableBase implements TabContent {
     return left;
   }
 
-  readonly footerHints = "↑↓ scroll · / search · n/N next · y copy";
+  get footerHints(): string {
+    return `↑↓ scroll · / search · n/N next · y copy${this.opts.onOpenEditor ? " · e editor" : ""}`;
+  }
 
   handleInput(data: string): boolean {
-    return this.handleScrollKey(data);
+    if (this.handleScrollKey(data)) return true;
+    if (data === "e" && this.opts.onOpenEditor) {
+      this.opts.onOpenEditor();
+      return true;
+    }
+    return false;
   }
 
   renderContent(innerWidth: number, height: number): string[] {
+    this.visibleHeight = height;
     this.buildVisualLines(innerWidth);
     const th = this.opts.theme;
     const lines: string[] = [];

package/src/tabbed-overlay.test.ts

@@ -0,0 +1,57 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
+import { describe, expect, it } from "vitest";
+import { ScrollableTabContent } from "./scrollable-tab-content.js";
+import { TabbedOverlay } from "./tabbed-overlay.js";
+
+const theme = {
+	fg: (_color: string, text: string) => text,
+	bold: (text: string) => text,
+} as Theme;
+
+function createOverlay(rows: number) {
+	const terminal = { rows };
+	const tab = new ScrollableTabContent({
+		rawText: Array.from({ length: 50 }, (_, i) => `line ${i}`).join("\n"),
+		displayLines: Array.from({ length: 50 }, (_, i) => `line ${i}`),
+		theme,
+	}, "Text");
+	const overlay = new TabbedOverlay({ title: "Context", subtitle: "test", tabs: [tab], theme, done: () => {} }, {
+		terminal,
+	} as TUI);
+	return { overlay, terminal };
+}
+
+describe("overlay height", () => {
+	it("keeps the footer inside the overlay at short terminal heights", () => {
+		const { overlay } = createOverlay(20);
+		const lines = overlay.render(80);
+		expect(lines).toHaveLength(18);
+		expect(lines.at(-2)).toContain("q close");
+		expect(lines.at(-1)).toContain("╰");
+	});
+
+	it("renders the complete frame when only seven rows fit", () => {
+		const { overlay } = createOverlay(8);
+		const lines = overlay.render(80);
+		expect(lines).toHaveLength(7);
+		expect(lines.at(-2)).toContain("q close");
+		expect(lines.at(-1)).toContain("╰");
+	});
+
+	it("uses the normal content height when there is enough room", () => {
+		const { overlay } = createOverlay(50);
+		expect(overlay.render(80)).toHaveLength(35);
+	});
+
+	it("updates page scrolling after a terminal resize", () => {
+		const { overlay, terminal } = createOverlay(50);
+		overlay.render(80);
+		terminal.rows = 20;
+		overlay.render(80);
+		overlay.handleInput("\x1b[6~");
+		const lines = overlay.render(80);
+		expect(lines[4]).toContain("line 9");
+		expect(lines.at(-2)).toContain("q close");
+	});
+});

package/src/tabbed-overlay.ts

@@ -11,7 +11,7 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { Key, matchesKey } from "@earendil-works/pi-tui";
+import { Key, matchesKey, type TUI } from "@earendil-works/pi-tui";
 import { createBorderHelpers, createTitle, CONTENT_HEIGHT } from "./utils.js";
 
 /**
@@ -63,10 +63,13 @@ export interface TabbedOverlayOptions {
 	done: () => void;
 }
 
+export const OVERLAY_HEIGHT_PERCENT = 90;
+const FRAME_HEIGHT = 7; // Top, title, tabs, separator, footer separator, footer, bottom.
+
 export class TabbedOverlay {
 	private activeTabIndex = 0;
 
-	constructor(private opts: TabbedOverlayOptions) {}
+	constructor(private opts: TabbedOverlayOptions, private tui: TUI) {}
 
 	private get activeTab(): TabContent {
 		return this.opts.tabs[this.activeTabIndex]!;
@@ -96,6 +99,9 @@ export class TabbedOverlay {
 	render(width: number): string[] {
 		const th = this.opts.theme;
 		const innerW = width - 2;
+		// Pi clips overlay lines beyond maxHeight from the bottom, including the footer.
+		const maxHeight = Math.max(1, Math.floor(this.tui.terminal.rows * OVERLAY_HEIGHT_PERCENT / 100));
+		const contentHeight = Math.min(CONTENT_HEIGHT, Math.max(0, maxHeight - FRAME_HEIGHT));
 		const lines: string[] = [];
 
 		const { row, borderTop, borderSep, borderBottom } = createBorderHelpers(th, innerW);
@@ -126,8 +132,8 @@ export class TabbedOverlay {
 		}
 
 		// ── Content area ─────────────────────────────────────────────────────────
-		const contentLines = this.activeTab.renderContent(innerW, CONTENT_HEIGHT);
-		for (let i = 0; i < CONTENT_HEIGHT; i++) {
+		const contentLines = this.activeTab.renderContent(innerW, contentHeight);
+		for (let i = 0; i < contentHeight; i++) {
 			if (i < contentLines.length) {
 				lines.push(row(contentLines[i]!));
 			} else {