pi-hud 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ludevdot
+
+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

@@ -57,9 +57,9 @@ Run `/hud` again, or press `f2`, to hide or show it. Press `ctrl+h` to minimize
 
 ## Commands
 
-| Command | Description |
-| --- | --- |
-| `/hud` | Toggle the hud. |
+| Command         | Description                                              |
+| --------------- | -------------------------------------------------------- |
+| `/hud`          | Toggle the hud.                                          |
 | `/hud-settings` | Configure position, shortcuts, auto-compact, and sizing. |
 
 ## Settings
@@ -98,7 +98,7 @@ Shortcut changes require `/reload` because shortcuts are registered when the ext
 
 ## Notes
 
-- MCP servers are shown only when Pi has `pi-mcp-adapter` installed; config files alone do not enable the section.
+- MCP servers are shown only when Pi has [`pi-mcp-adapter`](https://pi.dev/packages/pi-mcp-adapter?name=pi-mcp-adap) installed; config files alone do not enable the section.
 - Subagent status is based on Pi extension events and `pi-subagents` tool/result shapes when available.
 - The HUD auto-compacts for the full assistant turn and expands when the turn ends, instead of changing state on each reasoning update.
 - The overlay is hidden on narrow terminals under the configured `minTerminalWidth`.
@@ -111,4 +111,4 @@ Shortcut changes require `/reload` because shortcuts are registered when the ext
 
 ## License
 
-MIT
+MIT

package/extensions/config/hud-settings.ts

@@ -0,0 +1,15 @@
+import type { OverlayAnchor } from "@earendil-works/pi-tui";
+import type { HudSettings } from "../types/hud.js";
+
+export const VALID_POSITIONS: OverlayAnchor[] = ["center", "top-left", "top-right", "bottom-left", "bottom-right", "top-center", "bottom-center", "left-center", "right-center"];
+
+export const DEFAULT_HUD_SETTINGS: HudSettings = {
+	position: "top-right",
+	shortcut: "f2",
+	minimizeShortcut: "ctrl+h",
+	autoCompactWhileStreaming: true,
+	expandedWidth: 42,
+	compactWidth: 26,
+	minTerminalWidth: 90,
+	margin: { top: 1, right: 1, bottom: 1 },
+};

package/extensions/git/git.ts

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+
+export function getGitBranch(cwd: string): string | null {
+	const gitPaths = findGitPaths(cwd);
+	if (!gitPaths) return null;
+	const result = spawnSync("git", ["--no-optional-locks", "symbolic-ref", "--quiet", "--short", "HEAD"], {
+		cwd: gitPaths.repoDir,
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "ignore"],
+	});
+	const branch = result.status === 0 ? result.stdout.trim() : "";
+	return branch || null;
+}
+
+function findGitPaths(cwd: string): { repoDir: string; headPath: string } | null {
+	let dir = cwd;
+	while (true) {
+		const gitPath = join(dir, ".git");
+		if (existsSync(gitPath)) {
+			try {
+				const stat = statSync(gitPath);
+				if (stat.isFile()) {
+					const content = readFileSync(gitPath, "utf8").trim();
+					if (content.startsWith("gitdir: ")) {
+						const gitDir = resolve(dir, content.slice(8).trim());
+						const headPath = join(gitDir, "HEAD");
+						if (!existsSync(headPath)) return null;
+						return { repoDir: dir, headPath };
+					}
+				} else if (stat.isDirectory()) {
+					const headPath = join(gitPath, "HEAD");
+					if (!existsSync(headPath)) return null;
+					return { repoDir: dir, headPath };
+				}
+			} catch {
+				return null;
+			}
+		}
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}

package/extensions/hud.ts

@@ -0,0 +1,437 @@
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, OverlayHandle, OverlayOptions, TUI } from "@earendil-works/pi-tui";
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { getGitBranch } from "./git/git.js";
+import { getMcpAdapterInfo } from "./mcp/mcp-adapter.js";
+import { getSubagentToolLabel, parseSubagentMessage, parseSubagentResultCounts } from "./parsers/subagents.js";
+import { getProjectPath, handleHudSettingsCommand, readHudSettings, toShortcutKey } from "./settings/hud-settings.js";
+import type { ActiveSubagentToolRun, AgentStatus, HudSettings, SessionStats, SubagentRunCounts, SubagentStatus } from "./types/hud.js";
+import { formatElapsed, formatNumber, formatShortcut } from "./utils/formatters.js";
+
+export default function (pi: ExtensionAPI) {
+	let hudHandle: OverlayHandle | null = null;
+	let refreshTimer: ReturnType<typeof setInterval> | null = null;
+	let hudTui: TUI | null = null;
+	let generation = 0;
+	let opening = false;
+	let assistantTurnActive = false;
+	let manualCompactOverride: boolean | undefined;
+	let currentHudSettings: HudSettings | undefined;
+	const agentStatus: AgentStatus = { running: 0, completed: 0 };
+	const subagentStatus: SubagentStatus = { running: 0, completed: 0, failed: 0, seen: false, tokens: 0 };
+	const subagentRuns = new Map<string, SubagentRunCounts>();
+	const activeSubagentTools = new Map<string, ActiveSubagentToolRun>();
+	let completedSubagentToolRuns = 0;
+	let failedSubagentToolRuns = 0;
+
+	const clearRefreshTimer = () => {
+		if (refreshTimer === null) return;
+		clearInterval(refreshTimer);
+		refreshTimer = null;
+	};
+
+	const resetHudState = () => {
+		clearRefreshTimer();
+		hudHandle = null;
+		hudTui = null;
+		opening = false;
+		currentHudSettings = undefined;
+	};
+
+	const hideHud = () => {
+		generation++;
+		const handle = hudHandle;
+		resetHudState();
+		handle?.hide();
+	};
+
+	const requestHudRender = () => {
+		hudTui?.requestRender();
+	};
+
+	const isCompact = (settings: HudSettings) => manualCompactOverride ?? (settings.autoCompactWhileStreaming && assistantTurnActive);
+
+	const recalculateSubagentStatus = () => {
+		subagentStatus.running = activeSubagentTools.size;
+		subagentStatus.completed = completedSubagentToolRuns;
+		subagentStatus.failed = failedSubagentToolRuns;
+		subagentStatus.seen = subagentRuns.size > 0 || activeSubagentTools.size > 0 || completedSubagentToolRuns > 0 || failedSubagentToolRuns > 0;
+		subagentStatus.activeLabel = undefined;
+		subagentStatus.activeStartedAt = undefined;
+		subagentStatus.tokens = 0;
+
+		for (const counts of subagentRuns.values()) {
+			subagentStatus.running += counts.running;
+			subagentStatus.completed += counts.completed;
+			subagentStatus.failed += counts.failed;
+			subagentStatus.tokens += counts.tokens;
+			if (!subagentStatus.activeLabel && counts.activeLabel) {
+				subagentStatus.activeLabel = counts.activeLabel;
+				subagentStatus.activeStartedAt = counts.activeStartedAt;
+			}
+		}
+		for (const activeRun of activeSubagentTools.values()) {
+			if (!subagentStatus.activeLabel) {
+				subagentStatus.activeLabel = activeRun.label;
+				subagentStatus.activeStartedAt = activeRun.startedAt;
+			}
+		}
+	};
+
+	const updateSubagentStatusFromMessage = (message: unknown): boolean => {
+		const parsed = parseSubagentMessage(message);
+		if (!parsed) return false;
+		subagentRuns.set(parsed.requestId, parsed.counts);
+		recalculateSubagentStatus();
+		return true;
+	};
+
+	const startRefreshTimer = (currentGeneration: number, tui: TUI) => {
+		clearRefreshTimer();
+		refreshTimer = setInterval(() => {
+			if (currentGeneration !== generation || hudHandle === null) {
+				clearRefreshTimer();
+				return;
+			}
+			tui.requestRender();
+		}, 1000);
+	};
+
+	const showHud = (ctx: ExtensionContext) => {
+		if (!ctx.hasUI || hudHandle !== null || opening) return;
+
+		const settings = readHudSettings(getProjectPath(ctx));
+		currentHudSettings = settings;
+		const currentGeneration = ++generation;
+		opening = true;
+		try {
+			ctx.ui
+				.custom<void>((tui, theme, _keybindings, done) => {
+					hudTui = tui;
+					return new HudComponent(pi, ctx, tui, theme, done, subagentStatus, settings, () => isCompact(settings));
+				}, {
+					overlay: true,
+					overlayOptions: () => createHudOverlayOptions(settings, isCompact(settings)),
+					onHandle: (handle) => {
+						if (currentGeneration !== generation) {
+							handle.hide();
+							return;
+						}
+						hudHandle = handle;
+						opening = false;
+						if (hudTui !== null) {
+							startRefreshTimer(currentGeneration, hudTui);
+						}
+					},
+				})
+				.catch(() => {
+					if (currentGeneration !== generation) return;
+					resetHudState();
+				});
+		} catch {
+			if (currentGeneration === generation) resetHudState();
+		}
+	};
+
+	const toggleHud = (ctx: ExtensionContext) => {
+		if (!ctx.hasUI) return;
+		if (hudHandle !== null || opening) {
+			hideHud();
+			return;
+		}
+		showHud(ctx);
+	};
+
+	const toggleCompact = () => {
+		const settings = currentHudSettings ?? readHudSettings(process.cwd());
+		manualCompactOverride = !isCompact(settings);
+		requestHudRender();
+	};
+
+	pi.on("agent_start", () => {
+		agentStatus.running++;
+		requestHudRender();
+	});
+
+	pi.on("agent_end", () => {
+		agentStatus.running = Math.max(0, agentStatus.running - 1);
+		agentStatus.completed++;
+		requestHudRender();
+	});
+
+	pi.on("turn_start", () => {
+		if (assistantTurnActive) return;
+		assistantTurnActive = true;
+		requestHudRender();
+	});
+
+	pi.on("turn_end", () => {
+		if (!assistantTurnActive) return;
+		assistantTurnActive = false;
+		requestHudRender();
+	});
+
+	pi.on("message_start", (event) => {
+		if (updateSubagentStatusFromMessage(event.message)) requestHudRender();
+	});
+
+	pi.on("message_update", (event) => {
+		if (updateSubagentStatusFromMessage(event.message)) requestHudRender();
+	});
+
+	pi.on("message_end", (event) => {
+		if (updateSubagentStatusFromMessage(event.message)) requestHudRender();
+	});
+
+	pi.on("tool_execution_start", (event) => {
+		if (event.toolName !== "subagent") return;
+		activeSubagentTools.set(event.toolCallId, {
+			label: getSubagentToolLabel(event.args),
+			startedAt: Date.now(),
+		});
+		recalculateSubagentStatus();
+		requestHudRender();
+	});
+
+	pi.on("tool_execution_end", (event) => {
+		if (event.toolName !== "subagent") return;
+		if (activeSubagentTools.delete(event.toolCallId)) {
+			const resultCounts = parseSubagentResultCounts(event.result);
+			if (resultCounts) {
+				completedSubagentToolRuns += resultCounts.completed;
+				failedSubagentToolRuns += resultCounts.failed;
+			} else if (event.isError) failedSubagentToolRuns++;
+			else completedSubagentToolRuns++;
+		}
+		recalculateSubagentStatus();
+		requestHudRender();
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		showHud(ctx);
+	});
+
+	pi.on("session_shutdown", () => {
+		hideHud();
+		agentStatus.running = 0;
+		agentStatus.completed = 0;
+		assistantTurnActive = false;
+		manualCompactOverride = undefined;
+		subagentRuns.clear();
+		activeSubagentTools.clear();
+		completedSubagentToolRuns = 0;
+		failedSubagentToolRuns = 0;
+		recalculateSubagentStatus();
+	});
+
+	pi.registerCommand("hud", {
+		description: "Toggle the session HUD overlay",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			toggleHud(ctx);
+		},
+	});
+
+	pi.registerCommand("hud-settings", {
+		description: "Configure the session HUD",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			await handleHudSettingsCommand(args, ctx);
+		},
+	});
+
+	const startupSettings = readHudSettings(process.cwd());
+	const startupShortcut = toShortcutKey(startupSettings.shortcut);
+	if (startupShortcut) {
+		pi.registerShortcut(startupShortcut, {
+			description: "Toggle the session HUD",
+			handler: (ctx: ExtensionContext) => {
+				toggleHud(ctx);
+			},
+		});
+	}
+	const startupMinimizeShortcut = toShortcutKey(startupSettings.minimizeShortcut);
+	if (startupMinimizeShortcut) {
+		pi.registerShortcut(startupMinimizeShortcut, {
+			description: "Minimize or expand the session HUD",
+			handler: () => {
+				toggleCompact();
+			},
+		});
+	}
+
+}
+
+class HudComponent implements Component {
+	constructor(
+		private pi: ExtensionAPI,
+		private ctx: ExtensionContext,
+		private tui: TUI,
+		private theme: Theme,
+		private done: () => void,
+		private subagentStatus: SubagentStatus,
+		private settings: HudSettings,
+		private isCompact: () => boolean,
+	) {}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+			this.done();
+			return;
+		}
+
+		if (matchesKey(data, "r")) {
+			this.tui.requestRender();
+		}
+	}
+
+	render(width: number): string[] {
+		const stats = this.computeStats();
+		const model = this.ctx.model;
+		const sessionName = this.pi.getSessionName() ?? this.ctx.sessionManager.getSessionName() ?? "New session";
+		const sessionId = this.ctx.sessionManager.getSessionId();
+		const projectPath = this.ctx.sessionManager.getCwd() || this.ctx.cwd;
+		const gitBranch = getGitBranch(projectPath);
+		const mcpAdapter = getMcpAdapterInfo(this.pi, projectPath);
+		const contextUsage = this.ctx.getContextUsage?.();
+		const contextWindow = contextUsage?.contextWindow ?? model?.contextWindow ?? 0;
+		const contextTokens = contextUsage?.tokens ?? stats.totalTokens;
+		const contextPercent = contextUsage?.percent ?? (contextWindow > 0 ? (contextTokens / contextWindow) * 100 : null);
+		const innerWidth = Math.max(1, width - 2);
+		const lines: string[] = [];
+
+		if (this.isCompact()) {
+			this.pushTopBorder(lines, innerWidth, "HUD");
+			this.pushLine(lines, innerWidth, this.theme.fg("accent", model?.name ?? model?.id ?? "No model"));
+			this.pushLine(lines, innerWidth, contextPercent === null ? "ctx unknown" : `${contextPercent.toFixed(1)}% ctx`);
+			this.pushLine(lines, innerWidth, `${this.theme.fg("warning", `${this.subagentStatus.running} run`)} · ${this.theme.fg("error", `${this.subagentStatus.failed} err`)}`);
+			if (this.subagentStatus.activeLabel) {
+				this.pushLine(lines, innerWidth, this.theme.fg("accent", `[·] ${this.subagentStatus.activeLabel}`));
+			}
+			this.pushBottomBorder(lines, innerWidth);
+			return lines;
+		}
+
+		this.pushTopBorder(lines, innerWidth, "Session");
+		this.pushLine(lines, innerWidth, this.theme.fg("accent", sessionName));
+		this.pushLine(lines, innerWidth, this.theme.fg("dim", sessionId));
+		this.pushBlank(lines, innerWidth);
+		this.pushLine(lines, innerWidth, `Model ${model?.name ?? model?.id ?? "No model"}`);
+		this.pushLine(lines, innerWidth, this.theme.fg("dim", `${formatNumber(contextWindow)} ctx`));
+
+		this.pushSection(lines, innerWidth, "Subagents");
+		this.pushLine(
+			lines,
+			innerWidth,
+			`${this.theme.fg("warning", `${this.subagentStatus.running} run`)} · ${this.theme.fg("success", `${this.subagentStatus.completed} done`)} · ${this.theme.fg("error", `${this.subagentStatus.failed} err`)}`,
+		);
+		if (this.subagentStatus.activeLabel) {
+			this.pushLine(lines, innerWidth, this.theme.fg("accent", `[·] ${this.subagentStatus.activeLabel}`));
+			this.pushLine(lines, innerWidth, this.theme.fg("dim", `  ↳ ◷ ${formatElapsed(this.subagentStatus.activeStartedAt)} ${formatNumber(this.subagentStatus.tokens)} ctx`));
+		} else if (this.subagentStatus.seen) {
+			this.pushLine(lines, innerWidth, this.theme.fg("dim", `subagents ${this.subagentStatus.running} run · ${this.subagentStatus.completed} done`));
+		} else {
+			this.pushLine(lines, innerWidth, this.theme.fg("dim", "subagents idle"));
+		}
+
+		this.pushSection(lines, innerWidth, "Context");
+		this.pushLine(lines, innerWidth, contextTokens === null ? "tokens unknown" : `${formatNumber(contextTokens)} tokens`);
+		this.pushLine(lines, innerWidth, contextPercent === null ? "usage unknown" : `${contextPercent.toFixed(1)}% used`);
+		this.pushLine(lines, innerWidth, `$${stats.cost.toFixed(4)} spent`);
+		this.pushLine(lines, innerWidth, this.theme.fg("dim", `in ${formatNumber(stats.inputTokens)} out ${formatNumber(stats.outputTokens)}`));
+		this.pushLine(lines, innerWidth, this.theme.fg("dim", `cache ${formatNumber(stats.cacheReadTokens)}/${formatNumber(stats.cacheWriteTokens)}`));
+
+		this.pushSection(lines, innerWidth, "Project");
+		this.pushLine(lines, innerWidth, projectPath);
+		if (gitBranch) {
+			this.pushLine(lines, innerWidth, this.theme.fg("dim", `branch ${gitBranch}`));
+		}
+
+		if (mcpAdapter.available) {
+			this.pushSection(lines, innerWidth, "MCP");
+			if (mcpAdapter.servers.length === 0) {
+				this.pushLine(lines, innerWidth, this.theme.fg("dim", "adapter installed"));
+			} else {
+				for (const server of mcpAdapter.servers) {
+					this.pushLine(lines, innerWidth, server);
+				}
+			}
+		}
+
+		this.pushSection(lines, innerWidth, "Help");
+		this.pushLine(lines, innerWidth, this.theme.fg("dim", `/hud or ${formatShortcut(this.settings.shortcut)} hide/show`));
+		this.pushLine(lines, innerWidth, this.theme.fg("dim", `${formatShortcut(this.settings.minimizeShortcut)} minimize/expand`));
+		this.pushBottomBorder(lines, innerWidth);
+
+		return lines;
+	}
+
+	invalidate(): void {}
+
+	private computeStats(): SessionStats {
+		const stats: SessionStats = {
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 0,
+			totalTokens: 0,
+			cost: 0,
+			assistantMessages: 0,
+		};
+
+		for (const entry of this.ctx.sessionManager.getBranch()) {
+			if (entry.type !== "message" || entry.message.role !== "assistant") continue;
+
+			const message = entry.message as AssistantMessage;
+			stats.inputTokens += message.usage.input || 0;
+			stats.outputTokens += message.usage.output || 0;
+			stats.cacheReadTokens += message.usage.cacheRead || 0;
+			stats.cacheWriteTokens += message.usage.cacheWrite || 0;
+			stats.totalTokens += message.usage.totalTokens || 0;
+			stats.cost += message.usage.cost.total || 0;
+			stats.assistantMessages++;
+		}
+
+		return stats;
+	}
+
+	private pushTopBorder(lines: string[], innerWidth: number, title: string): void {
+		const border = this.theme.fg("border", `╭${"─".repeat(innerWidth)}╮`);
+		lines.push(border);
+		this.pushLine(lines, innerWidth, this.theme.fg("accent", this.theme.bold(` ${title}`)));
+		this.pushSeparator(lines, innerWidth);
+	}
+
+	private pushBottomBorder(lines: string[], innerWidth: number): void {
+		lines.push(this.theme.fg("border", `╰${"─".repeat(innerWidth)}╯`));
+	}
+
+	private pushSeparator(lines: string[], innerWidth: number): void {
+		lines.push(this.theme.fg("border", `├${"─".repeat(innerWidth)}┤`));
+	}
+
+	private pushSection(lines: string[], innerWidth: number, title: string): void {
+		this.pushBlank(lines, innerWidth);
+		this.pushLine(lines, innerWidth, this.theme.fg("accent", title));
+	}
+
+	private pushBlank(lines: string[], innerWidth: number): void {
+		this.pushLine(lines, innerWidth, "");
+	}
+
+	private pushLine(lines: string[], innerWidth: number, text: string): void {
+		const content = truncateToWidth(` ${text}`, innerWidth, "…", true);
+		lines.push(this.theme.fg("border", "│") + content + this.theme.fg("border", "│"));
+	}
+}
+
+function createHudOverlayOptions(settings: HudSettings, compact: boolean): OverlayOptions {
+	return {
+		anchor: settings.position,
+		width: compact ? settings.compactWidth : settings.expandedWidth,
+		maxHeight: "100%",
+		margin: settings.margin,
+		visible: (termWidth) => termWidth >= settings.minTerminalWidth,
+		nonCapturing: true,
+	};
+}
+

package/extensions/mcp/mcp-adapter.ts

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "../utils/records.js";
+
+export function getMcpAdapterInfo(pi: ExtensionAPI, cwd: string): { available: boolean; servers: string[] } {
+	const hasAdapter = pi.getAllTools().some((tool) => isMcpAdapterSource(tool.sourceInfo.source)) || pi.getCommands().some((command) => isMcpAdapterSource(command.sourceInfo.source));
+	if (!hasAdapter) return { available: false, servers: [] };
+	return { available: true, servers: getConfiguredMcpServers(cwd) };
+}
+
+function isMcpAdapterSource(source: string): boolean {
+	return source.includes("pi-mcp-adapter") || source.includes("nicobailon/pi-mcp-adapter");
+}
+
+function getConfiguredMcpServers(cwd: string): string[] {
+	const names = new Set<string>();
+	for (const path of getMcpConfigPaths(cwd)) {
+		for (const name of readMcpServerNames(path)) {
+			names.add(name);
+		}
+	}
+	return [...names].sort((a, b) => a.localeCompare(b));
+}
+
+function getMcpConfigPaths(cwd: string): string[] {
+	const agentDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+	return [join(homedir(), ".config", "mcp", "mcp.json"), join(agentDir, "mcp.json"), join(cwd, ".mcp.json"), join(cwd, ".pi", "mcp.json")];
+}
+
+function readMcpServerNames(path: string): string[] {
+	if (!existsSync(path)) return [];
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (!isRecord(parsed) || !isRecord(parsed.mcpServers)) return [];
+		return Object.keys(parsed.mcpServers);
+	} catch {
+		return [];
+	}
+}

package/extensions/parsers/subagents.ts

@@ -0,0 +1,77 @@
+import type { SubagentRunCounts } from "../types/hud.js";
+import { isRecord } from "../utils/records.js";
+
+export function parseSubagentMessage(message: unknown): { requestId: string; counts: SubagentRunCounts } | undefined {
+	if (!isRecord(message)) return undefined;
+	if (message.role !== "custom" || message.customType !== "subagent-slash-result") return undefined;
+	const details = message.details;
+	if (!isRecord(details) || typeof details.requestId !== "string") return undefined;
+	const result = details.result;
+	if (!isRecord(result)) return undefined;
+	const resultDetails = result.details;
+	if (!isRecord(resultDetails)) return undefined;
+
+	const statusSources = collectSubagentStatusSources(resultDetails);
+	if (statusSources.length === 0) return undefined;
+
+	const counts: SubagentRunCounts = { running: 0, completed: 0, failed: 0, tokens: 0 };
+	for (const source of statusSources) {
+		if (typeof source.tokens === "number") counts.tokens += source.tokens;
+		if (source.status === "running") {
+			counts.running++;
+			if (!counts.activeLabel) counts.activeLabel = getSubagentProgressLabel(source);
+			if (!counts.activeStartedAt) counts.activeStartedAt = Date.now() - getDurationMs(source);
+		} else if (source.status === "completed" || source.status === "complete") counts.completed++;
+		else if (source.status === "failed") counts.failed++;
+	}
+	return { requestId: details.requestId, counts };
+}
+
+export function parseSubagentResultCounts(result: unknown): Pick<SubagentRunCounts, "completed" | "failed"> | undefined {
+	if (!isRecord(result)) return undefined;
+	const details = result.details;
+	if (!isRecord(details)) return undefined;
+	const statusSources = collectSubagentStatusSources(details);
+	if (statusSources.length === 0) return undefined;
+	const counts = { completed: 0, failed: 0 };
+	for (const source of statusSources) {
+		if (source.status === "failed") counts.failed++;
+		else if (source.status === "completed" || source.status === "complete") counts.completed++;
+	}
+	return counts.completed > 0 || counts.failed > 0 ? counts : undefined;
+}
+
+export function getSubagentToolLabel(args: unknown): string {
+	if (!isRecord(args)) return "subagent";
+	const agent = typeof args.agent === "string" ? args.agent : undefined;
+	const task = typeof args.task === "string" ? args.task : undefined;
+	if (task) return task;
+	if (agent) return agent;
+	if (Array.isArray(args.tasks) && args.tasks.length > 0) return `${args.tasks.length} subagents`;
+	if (Array.isArray(args.chain) && args.chain.length > 0) return `${args.chain.length} step chain`;
+	return "subagent";
+}
+
+function collectSubagentStatusSources(resultDetails: Record<string, unknown>): Array<Record<string, unknown>> {
+	if (Array.isArray(resultDetails.progress)) {
+		return resultDetails.progress.filter(isRecord);
+	}
+	if (!Array.isArray(resultDetails.results)) return [];
+	return resultDetails.results.filter(isRecord).flatMap((result) => {
+		if (isRecord(result.progress)) return [result.progress];
+		if (typeof result.exitCode === "number") {
+			return [{ status: result.exitCode === 0 ? "completed" : "failed" }];
+		}
+		return [];
+	});
+}
+
+function getSubagentProgressLabel(progress: Record<string, unknown>): string {
+	const task = typeof progress.task === "string" ? progress.task : undefined;
+	const agent = typeof progress.agent === "string" ? progress.agent : undefined;
+	return task || agent || "subagent";
+}
+
+function getDurationMs(progress: Record<string, unknown>): number {
+	return typeof progress.durationMs === "number" ? Math.max(0, progress.durationMs) : 0;
+}

package/extensions/settings/hud-settings.ts

@@ -0,0 +1,219 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { KeyId, OverlayAnchor, OverlayMargin } from "@earendil-works/pi-tui";
+import { DEFAULT_HUD_SETTINGS, VALID_POSITIONS } from "../config/hud-settings.js";
+import type { HudSettings } from "../types/hud.js";
+import { formatHudSettings } from "../utils/formatters.js";
+import { isRecord } from "../utils/records.js";
+
+export function getProjectPath(ctx: ExtensionContext): string {
+	return ctx.sessionManager.getCwd() || ctx.cwd;
+}
+
+export function readHudSettings(cwd: string): HudSettings {
+	let settings = { ...DEFAULT_HUD_SETTINGS, margin: { ...DEFAULT_HUD_SETTINGS.margin } };
+	for (const path of getSettingsPaths(cwd)) {
+		const hud = readHudSettingsObject(path);
+		if (hud) settings = normalizeHudSettings(hud, settings);
+	}
+	return settings;
+}
+
+export async function handleHudSettingsCommand(args: string, ctx: ExtensionCommandContext): Promise<void> {
+	const projectPath = getProjectPath(ctx);
+	const settings = readHudSettings(projectPath);
+	const trimmed = args.trim();
+	if (trimmed.length > 0) {
+		const updated = updateHudSettingFromArgs(settings, trimmed);
+		if (!updated) {
+			ctx.ui.notify("Usage: /hud-settings position|shortcut|minimizeShortcut|autoCompactWhileStreaming|expandedWidth|compactWidth|minTerminalWidth <value>", "warning");
+			return;
+		}
+		writeProjectHudSettings(projectPath, updated.settings);
+		ctx.ui.notify(updated.message, "info");
+		return;
+	}
+
+	const choice = await ctx.ui.select("HUD settings", ["position", "shortcut", "minimizeShortcut", "autoCompactWhileStreaming", "expandedWidth", "compactWidth", "minTerminalWidth", "show current"]);
+	if (!choice) return;
+	if (choice === "show current") {
+		ctx.ui.notify(formatHudSettings(settings), "info");
+		return;
+	}
+
+	if (choice === "position") {
+		const position = await ctx.ui.select("HUD position", VALID_POSITIONS);
+		if (!position) return;
+		const updated = { ...settings, position: position as OverlayAnchor };
+		writeProjectHudSettings(projectPath, updated);
+		ctx.ui.notify(`HUD position set to ${position}. Reopen /hud if it is currently visible.`, "info");
+		return;
+	}
+
+	if (choice === "shortcut" || choice === "minimizeShortcut") {
+		const shortcut = await ctx.ui.input(`HUD ${choice}`, settings[choice]);
+		if (shortcut === undefined) return;
+		const normalizedShortcut = normalizeShortcut(shortcut, "");
+		if (normalizedShortcut.length === 0) {
+			ctx.ui.notify("Invalid HUD shortcut. Do not use enter, return, alt+m, ctrl+m, ctrl+shift+m, ctrl+j, or ctrl+shift+j because they conflict with Pi or terminal input keys.", "warning");
+			return;
+		}
+		const updated = { ...settings, [choice]: normalizedShortcut };
+		writeProjectHudSettings(projectPath, updated);
+		ctx.ui.notify(`HUD ${choice} saved. Run /reload for the shortcut registration to change.`, "info");
+		return;
+	}
+
+	if (choice === "autoCompactWhileStreaming") {
+		const value = await ctx.ui.select("Auto-compact while streaming", ["enabled", "disabled"]);
+		if (!value) return;
+		const updated = { ...settings, autoCompactWhileStreaming: value === "enabled" };
+		writeProjectHudSettings(projectPath, updated);
+		ctx.ui.notify(`HUD auto-compact ${value}.`, "info");
+		return;
+	}
+
+	const numericChoice = choice as "expandedWidth" | "compactWidth" | "minTerminalWidth";
+	const value = await ctx.ui.input(`HUD ${numericChoice}`, String(settings[numericChoice]));
+	if (value === undefined) return;
+	const updated = updateHudSettingFromArgs(settings, `${numericChoice} ${value}`);
+	if (!updated) {
+		ctx.ui.notify(`Invalid value for ${numericChoice}.`, "warning");
+		return;
+	}
+	writeProjectHudSettings(projectPath, updated.settings);
+	ctx.ui.notify(updated.message, "info");
+}
+
+export function toShortcutKey(shortcut: string): KeyId | undefined {
+	const normalized = normalizeShortcut(shortcut, "");
+	return normalized.length > 0 ? (normalized as KeyId) : undefined;
+}
+
+function getSettingsPaths(cwd: string): string[] {
+	const agentDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+	return [join(agentDir, "settings.json"), join(cwd, ".pi", "settings.json")];
+}
+
+function readHudSettingsObject(path: string): Record<string, unknown> | undefined {
+	if (!existsSync(path)) return undefined;
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (!isRecord(parsed) || !isRecord(parsed.hud)) return undefined;
+		return parsed.hud;
+	} catch {
+		return undefined;
+	}
+}
+
+function normalizeHudSettings(input: Record<string, unknown>, base: HudSettings): HudSettings {
+	return {
+		position: normalizePosition(input.position, base.position),
+		shortcut: typeof input.shortcut === "string" ? normalizeShortcut(input.shortcut, base.shortcut) : base.shortcut,
+		minimizeShortcut: typeof input.minimizeShortcut === "string" ? normalizeShortcut(input.minimizeShortcut, base.minimizeShortcut) : base.minimizeShortcut,
+		autoCompactWhileStreaming: typeof input.autoCompactWhileStreaming === "boolean" ? input.autoCompactWhileStreaming : base.autoCompactWhileStreaming,
+		expandedWidth: normalizePositiveInteger(input.expandedWidth, base.expandedWidth, 20, 80),
+		compactWidth: normalizePositiveInteger(input.compactWidth, base.compactWidth, 16, 60),
+		minTerminalWidth: normalizePositiveInteger(input.minTerminalWidth, base.minTerminalWidth, 40, 300),
+		margin: normalizeMargin(input.margin, base.margin),
+	};
+}
+
+function normalizePosition(value: unknown, fallback: OverlayAnchor): OverlayAnchor {
+	return typeof value === "string" && VALID_POSITIONS.includes(value as OverlayAnchor) ? (value as OverlayAnchor) : fallback;
+}
+
+function normalizeShortcut(value: string, fallback: string): string {
+	const shortcut = value.trim();
+	const parts = shortcut.toLowerCase().split("+");
+	const key = parts.at(-1);
+	if (key === "enter" || key === "return" || shortcut.toLowerCase() === "alt+m") return fallback;
+	if (parts.includes("ctrl") && (key === "m" || key === "j")) return fallback;
+	return shortcut;
+}
+
+function normalizePositiveInteger(value: unknown, fallback: number, min: number, max: number): number {
+	if (typeof value !== "number" || !Number.isInteger(value)) return fallback;
+	return Math.min(max, Math.max(min, value));
+}
+
+function normalizeMargin(value: unknown, fallback: OverlayMargin): OverlayMargin {
+	if (!isRecord(value)) return { ...fallback };
+	return {
+		top: normalizeMarginValue(value.top, fallback.top),
+		right: normalizeMarginValue(value.right, fallback.right),
+		bottom: normalizeMarginValue(value.bottom, fallback.bottom),
+		left: normalizeMarginValue(value.left, fallback.left),
+	};
+}
+
+function normalizeMarginValue(value: unknown, fallback: number | undefined): number | undefined {
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 0) return fallback;
+	return Math.min(20, value);
+}
+
+function updateHudSettingFromArgs(settings: HudSettings, args: string): { settings: HudSettings; message: string } | undefined {
+	const [key, ...valueParts] = args.split(/\s+/);
+	const value = valueParts.join(" ").trim();
+	if (!key || value.length === 0) return undefined;
+	if (key === "position") {
+		const position = normalizePosition(value, settings.position);
+		if (position !== value) return undefined;
+		return { settings: { ...settings, position }, message: `HUD position set to ${position}. Reopen /hud if it is currently visible.` };
+	}
+	if (key === "shortcut" || key === "minimizeShortcut") {
+		const shortcut = normalizeShortcut(value, "");
+		if (shortcut.length === 0) return undefined;
+		return { settings: { ...settings, [key]: shortcut }, message: `HUD ${key} saved. Run /reload for the shortcut registration to change.` };
+	}
+	if (key === "autoCompactWhileStreaming") {
+		const enabled = parseBoolean(value);
+		if (enabled === undefined) return undefined;
+		return { settings: { ...settings, autoCompactWhileStreaming: enabled }, message: `HUD auto-compact ${enabled ? "enabled" : "disabled"}.` };
+	}
+	if (key === "expandedWidth" || key === "compactWidth" || key === "minTerminalWidth") {
+		const parsed = Number(value);
+		if (!Number.isInteger(parsed)) return undefined;
+		const updated = { ...settings, [key]: parsed };
+		return { settings: normalizeHudSettings(updated, settings), message: `HUD ${key} set to ${parsed}.` };
+	}
+	return undefined;
+}
+
+function parseBoolean(value: string): boolean | undefined {
+	const normalized = value.toLowerCase();
+	if (["true", "on", "yes", "1", "enabled"].includes(normalized)) return true;
+	if (["false", "off", "no", "0", "disabled"].includes(normalized)) return false;
+	return undefined;
+}
+
+function writeProjectHudSettings(cwd: string, hud: HudSettings): void {
+	const path = join(cwd, ".pi", "settings.json");
+	let root: Record<string, unknown> = {};
+	if (existsSync(path)) {
+		try {
+			const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+			if (isRecord(parsed)) root = { ...parsed };
+		} catch {
+			root = {};
+		}
+	}
+	root.hud = serializeHudSettings(hud);
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(root, null, "\t")}\n`, "utf8");
+}
+
+function serializeHudSettings(settings: HudSettings): Record<string, unknown> {
+	return {
+		position: settings.position,
+		shortcut: settings.shortcut,
+		minimizeShortcut: settings.minimizeShortcut,
+		autoCompactWhileStreaming: settings.autoCompactWhileStreaming,
+		expandedWidth: settings.expandedWidth,
+		compactWidth: settings.compactWidth,
+		minTerminalWidth: settings.minTerminalWidth,
+		margin: settings.margin,
+	};
+}

package/extensions/types/hud.ts

@@ -0,0 +1,51 @@
+import type { OverlayAnchor, OverlayMargin } from "@earendil-works/pi-tui";
+
+export interface SessionStats {
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+	totalTokens: number;
+	cost: number;
+	assistantMessages: number;
+}
+
+export interface AgentStatus {
+	running: number;
+	completed: number;
+}
+
+export interface SubagentStatus {
+	running: number;
+	completed: number;
+	failed: number;
+	seen: boolean;
+	activeLabel?: string;
+	activeStartedAt?: number;
+	tokens: number;
+}
+
+export interface SubagentRunCounts {
+	running: number;
+	completed: number;
+	failed: number;
+	tokens: number;
+	activeLabel?: string;
+	activeStartedAt?: number;
+}
+
+export interface ActiveSubagentToolRun {
+	label: string;
+	startedAt: number;
+}
+
+export interface HudSettings {
+	position: OverlayAnchor;
+	shortcut: string;
+	minimizeShortcut: string;
+	autoCompactWhileStreaming: boolean;
+	expandedWidth: number;
+	compactWidth: number;
+	minTerminalWidth: number;
+	margin: OverlayMargin;
+}

package/extensions/utils/formatters.ts

@@ -0,0 +1,23 @@
+import type { HudSettings } from "../types/hud.js";
+
+export function formatHudSettings(settings: HudSettings): string {
+	return `HUD position=${settings.position}, shortcut=${settings.shortcut || "disabled"}, minimizeShortcut=${settings.minimizeShortcut || "disabled"}, autoCompactWhileStreaming=${settings.autoCompactWhileStreaming}, expandedWidth=${settings.expandedWidth}, compactWidth=${settings.compactWidth}, minTerminalWidth=${settings.minTerminalWidth}`;
+}
+
+export function formatShortcut(shortcut: string): string {
+	const trimmed = shortcut.trim();
+	return trimmed.length > 0 ? trimmed : "disabled";
+}
+
+export function formatElapsed(startedAt: number | undefined): string {
+	const elapsedSeconds = startedAt ? Math.max(0, Math.floor((Date.now() - startedAt) / 1000)) : 0;
+	const minutes = Math.floor(elapsedSeconds / 60);
+	const seconds = elapsedSeconds % 60;
+	return `${minutes.toString().padStart(2, "0")}:${seconds.toString().padStart(2, "0")}`;
+}
+
+export function formatNumber(value: number): string {
+	if (value < 1000) return value.toLocaleString();
+	if (value < 1_000_000) return `${(value / 1000).toFixed(1)}k`;
+	return `${(value / 1_000_000).toFixed(1)}m`;
+}

package/extensions/utils/records.ts

@@ -0,0 +1,3 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hud",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A persistent hud for Pi with context, project, and subagent status.",
   "type": "module",
   "license": "MIT",
@@ -8,6 +8,7 @@
     "type": "git",
     "url": "git+https://github.com/ludevdot/pi-hud.git"
   },
+  "packageManager": "pnpm@10.30.2",
   "keywords": [
     "pi-package",
     "pi",
@@ -19,8 +20,16 @@
     "extensions",
     "assets",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "scripts"
   ],
+  "scripts": {
+    "test": "vitest --run",
+    "pack:dry": "pnpm pack --dry-run",
+    "verify:package": "node scripts/verify-package-files.mjs",
+    "prepack": "pnpm test && pnpm run verify:package",
+    "prepublishOnly": "pnpm test && pnpm run verify:package"
+  },
   "pi": {
     "extensions": [
       "./extensions"
@@ -42,9 +51,5 @@
   },
   "engines": {
     "node": ">=20.0.0"
-  },
-  "scripts": {
-    "test": "vitest --run",
-    "pack:dry": "pnpm pack --dry-run"
   }
-}
+}

package/scripts/verify-package-files.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(fileURLToPath(new URL("..", import.meta.url)));
+
+const requiredPaths = [
+	"assets/pi-hud.jpeg",
+	"assets/pi-hud-logo-only.jpg",
+	"extensions/config/hud-settings.ts",
+	"extensions/git/git.ts",
+	"extensions/hud.ts",
+	"extensions/mcp/mcp-adapter.ts",
+	"extensions/parsers/subagents.ts",
+	"extensions/settings/hud-settings.ts",
+	"extensions/types/hud.ts",
+	"extensions/utils/formatters.ts",
+	"extensions/utils/records.ts",
+	"LICENSE",
+	"README.md",
+	"package.json",
+];
+
+const missing = requiredPaths.filter((relativePath) => {
+	const absolutePath = join(root, relativePath);
+	return !existsSync(absolutePath) || !statSync(absolutePath).isFile();
+});
+
+if (missing.length > 0) {
+	console.error("pi-hud package is missing required Pi resources:");
+	for (const relativePath of missing) {
+		console.error(`- ${relativePath}`);
+	}
+	console.error("\nRefusing to pack/publish an incomplete npm package.");
+	process.exit(1);
+}
+
+console.log(
+	`pi-hud package resource check passed (${requiredPaths.length} files).`,
+);