Pi Readable Footer

readme.md

readable-footer

A clean, labeled footer for pi that replaces the default cryptic stats bar with human-readable labels, color-coded context warnings, and IDR cost conversion.

Features

• Labeled stats --- input:, output:, cache:, context:, cost: instead of ↑ ↓ R CH $
• Cache as separate section --- input: 89.8k · cache: 52k (58.0%) · output: 31.8k with clean middle-dot separators
• Color-coded context bar --- 20-block progress bar (full blocks only) that turns green → yellow → red as context fills up
• Thinking level colorized --- each level (off--xhigh) gets its own theme color
• IDR cost conversion --- fetches live USD→IDR rate from open.er-api.com, cached per session
• MCP server status --- shows MCP: 2/3 servers from the pi-mcp-adapter extension below the stats line
• Model + provider + git branch on the left side

Screenshot

model: deepseek:deepseek-v4-flash · level: high · speed: ~45t/s · latency: ~1.23s · git: main
input: 89.8k · cache: 52k (58.0%) · output: 31.8k · context: ██████████░░░░░░░░░░ 50.00% · cost: Rp3.006
MCP: 2/3 servers

Installation

Drop into:

~/.pi/agent/extensions/readable-footer.ts

Run:

curl -o ~/.pi/agent/extensions/readable-footer.ts \
https://gist.githubusercontent.com/.../readable-footer.ts

The extension auto-enables on next startup. No configuration needed.

Usage

Command	Action
(auto)	Enabled on startup
/readable-footer	Toggle on/off
/reload	Reload extension (also re-fetches IDR rate)

Requirements

• pi ≥ latest
• pi-mcp-adapter extension (optional --- for MCP server status line)
• Internet access (optional --- for live IDR rate; falls back to ~Rp16k/USD)

License

MIT

pi-readable-footer.ts

/**
 * Readable Footer Extension
 *
 * Replaces pi's default footer with one that has clear labels
 * so you can actually understand what each number means.
 *
 * Auto-enables on startup. Toggle with: /readable-footer
 *
 * Self-contained: no relative imports, safe to drop into any
 * pi extensions folder as a single file.
 */

import type { AssistantMessage } from "@earendil-works/pi-ai";
import type { ExtensionAPI, ThemeColor } from "@earendil-works/pi-coding-agent";
import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";

// ============================================================================
// Currency conversion (USD -> IDR)
// ============================================================================

const FALLBACK_IDR_RATE = 16000;
const CURRENCY_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour

class CurrencyConverter {
	private rate: number | null = null;
	private fetchedAt = 0;
	private pending: Promise<number> | null = null;

	/** Returns the cached rate immediately (or the fallback) without fetching. */
	getCachedRate(): number {
		return this.rate ?? FALLBACK_IDR_RATE;
	}

	/** Refreshes the rate in the background if stale; safe to call repeatedly. */
	async refresh(): Promise<number> {
		const isFresh = this.rate !== null && Date.now() - this.fetchedAt < CURRENCY_CACHE_TTL_MS;
		if (isFresh) return this.rate as number;
		if (this.pending) return this.pending;

		this.pending = this.fetchRate().finally(() => {
			this.pending = null;
		});
		return this.pending;
	}

	private async fetchRate(): Promise<number> {
		try {
			const res = await fetch("https://open.er-api.com/v6/latest/USD");
			const data = (await res.json()) as { rates?: Record<string, number> };
			this.rate = data.rates?.IDR ?? FALLBACK_IDR_RATE;
		} catch {
			this.rate = this.rate ?? FALLBACK_IDR_RATE;
		}
		this.fetchedAt = Date.now();
		return this.rate;
	}

	formatIdr(usd: number): string {
		const idr = Math.round(usd * this.getCachedRate());
		return `Rp${groupThousands(idr)}`;
	}
}

function groupThousands(n: number): string {
	const s = n.toString();
	const parts: string[] = [];
	for (let i = s.length; i > 0; i -= 3) {
		parts.unshift(s.slice(Math.max(0, i - 3), i));
	}
	return parts.join(".");
}

// ============================================================================
// Streaming speed tracker (tokens/sec, time-to-first-token)
// ============================================================================

interface StreamSnapshot {
	tokensPerSecond: number;
	timeToFirstTokenMs: number;
}

/**
 * Tracks tokens-per-second and time-to-first-token for the in-flight
 * assistant message. Instantiated per-session (not module-global), so
 * multiple sessions/extension-reloads never share or clobber state.
 */
class StreamSpeedTracker {
	private isStreaming = false;
	private startedAt = 0;
	private lastSampleAt = 0;
	private lastCharCount = 0;
	private tokensPerSecond = 0;
	private timeToFirstTokenMs = 0;
	private firstTokenRecorded = false;

	/** Call on every message_update event for the active assistant message. */
	onUpdate(charCount: number, now: number = Date.now()): void {
		if (!this.isStreaming) {
			this.beginStream(charCount, now);
			return;
		}

		const elapsedMs = now - this.lastSampleAt;
		if (elapsedMs > 0 && charCount > this.lastCharCount) {
			this.tokensPerSecond = (charCount - this.lastCharCount) / (elapsedMs / 1000);
		}
		if (!this.firstTokenRecorded && charCount > 0) {
			this.timeToFirstTokenMs = now - this.startedAt;
			this.firstTokenRecorded = true;
		}
		this.lastSampleAt = now;
		this.lastCharCount = charCount;
	}

	/** Call once the agent reports idle, to reset for the next message. */
	onIdle(): void {
		this.isStreaming = false;
	}

	snapshot(): StreamSnapshot {
		return {
			tokensPerSecond: this.tokensPerSecond,
			timeToFirstTokenMs: this.timeToFirstTokenMs,
		};
	}

	private beginStream(charCount: number, now: number): void {
		this.isStreaming = true;
		this.startedAt = now;
		this.lastSampleAt = now;
		this.lastCharCount = charCount;
		this.tokensPerSecond = 0;
		this.timeToFirstTokenMs = 0;
		this.firstTokenRecorded = false;
	}
}

function charCountOf(message: { content: unknown }): number {
	const content = message.content;
	if (!Array.isArray(content)) return 0;
	return content.reduce((sum: number, block: any) => sum + (block?.text?.length ?? 0), 0);
}

// ============================================================================
// Usage / cost aggregation
// ============================================================================

interface ModelOverrideRates {
	input: number;
	output: number;
	cacheRead: number;
}

interface UsageTotals {
	inputTokens: number;
	inputMissTokens: number;
	outputTokens: number;
	cacheRead: number;
	cacheWrite: number;
	costUsd: number;
}

/**
 * Some providers report inflated/incorrect costs via m.usage.cost.total;
 * for those we recompute from corrected per-token rates instead.
 */
const CORRECTED_RATES: Record<string, ModelOverrideRates> = {
	"deepseek:deepseek-v4-flash": { input: 0.14, output: 0.28, cacheRead: 0.0028 },
	"deepseek:deepseek-v4-pro": { input: 0.435, output: 0.87, cacheRead: 0.003625 },
	"xiaomi:mimo-v2.5": { input: 0.14, output: 0.28, cacheRead: 0.0028 },
	"xiaomi:mimo-v2.5-pro": { input: 0.435, output: 0.87, cacheRead: 0.0036 },
};

function modelKeyFor(provider: string | undefined, id: string | undefined): string {
	return `${provider ?? "?"}:${id ?? ""}`;
}

function computeUsageTotals(
	branch: Iterable<{ type: string; message: { role: string } }>,
	provider: string | undefined,
	modelId: string | undefined,
): UsageTotals {
	const totals: UsageTotals = {
		inputTokens: 0,
		inputMissTokens: 0,
		outputTokens: 0,
		cacheRead: 0,
		cacheWrite: 0,
		costUsd: 0,
	};

	const overrideRates = CORRECTED_RATES[modelKeyFor(provider, modelId)];

	for (const entry of branch) {
		if (entry.type !== "message" || entry.message.role !== "assistant") continue;

		const message = entry.message as AssistantMessage;
		const totalInput = message.usage.input;
		const cachedInput = message.usage.cacheRead;
		const uncachedInput = Math.max(0, totalInput - cachedInput);

		totals.inputTokens += totalInput;
		totals.inputMissTokens += uncachedInput;
		totals.outputTokens += message.usage.output;
		totals.cacheRead += cachedInput;
		totals.cacheWrite += message.usage.cacheWrite;

		totals.costUsd += overrideRates
			? (uncachedInput * overrideRates.input +
					cachedInput * overrideRates.cacheRead +
					message.usage.output * overrideRates.output) /
				1_000_000
			: message.usage.cost.total;
	}

	return totals;
}

// ============================================================================
// Presentation helpers (progress bar, colors, number formatting)
// ============================================================================

const BLOCK_FULL = "█";
function progressBar(percent: number, width = 20): string {
	const clamped = Math.max(0, Math.min(100, percent));
	const fullBlocks = Math.min(Math.ceil((clamped / 100) * width), width);
	const emptyBlocks = width - fullBlocks;
	return BLOCK_FULL.repeat(fullBlocks) + "░".repeat(emptyBlocks);
}

function contextUsageColor(percent: number): ThemeColor {
	if (percent > 80) return "error";
	if (percent > 50) return "warning";
	return "success";
}

const THINKING_LEVEL_COLORS: Record<string, ThemeColor> = {
	off: "thinkingOff",
	minimal: "thinkingMinimal",
	low: "thinkingLow",
	medium: "thinkingMedium",
	high: "thinkingHigh",
	xhigh: "thinkingXhigh",
};

function thinkingLevelColor(level: string): ThemeColor {
	return THINKING_LEVEL_COLORS[level] ?? "dim";
}

/** Formats a token count as e.g. "12.3k" or "1.20M". */
function formatTokenCount(n: number): string {
	return n < 1_000_000 ? `${(n / 1000).toFixed(1)}k` : `${(n / 1_000_000).toFixed(2)}M`;
}

function tokensPerSecondColor(tps: number): ThemeColor {
	if (tps > 100) return "success";
	if (tps > 30) return "accent";
	return "muted";
}

function latencyColor(ms: number): ThemeColor {
	if (ms < 1000) return "success";
	if (ms < 2000) return "accent";
	return "muted";
}

// ============================================================================
// Per-session state
// ============================================================================

/** A fresh instance is created each time the footer is enabled. */
class FooterSession {
	readonly currency = new CurrencyConverter();
	readonly speed = new StreamSpeedTracker();
}

// ============================================================================
// Rendering
// ============================================================================

function renderFooterLines(args: {
	ctx: any;
	pi: ExtensionAPI;
	theme: any;
	footerData: any;
	width: number;
	session: FooterSession;
}): string[] {
	const { ctx, pi, theme, footerData, width, session } = args;

	const totals = computeUsageTotals(
		ctx.sessionManager.getBranch(),
		ctx.model?.provider,
		ctx.model?.id,
	);

	const contextPercent = ctx.getContextUsage()?.percent ?? null;

	const left = renderLeftSection(ctx, pi, theme, footerData, session, contextPercent);
	const right = renderRightSection(theme, totals, session.currency);

	const padding = " ".repeat(Math.max(1, width - visibleWidth(left) - visibleWidth(right) - 2));
	const mainLine = truncateToWidth(` ${left}${padding}${right} `, width);

	const lines = [mainLine];

	const extensionStatus = footerData.getExtensionStatuses?.()?.get("mcp");
	if (extensionStatus) {
		lines.push(truncateToWidth(` ${theme.fg("dim", extensionStatus)} `, width));
	}

	return lines;
}

function renderLeftSection(
	ctx: any,
	pi: ExtensionAPI,
	theme: any,
	footerData: any,
	session: FooterSession,
	contextPercent: number | null,
): string {
	const dim = (s: string) => theme.fg("dim", s);

	const provider = ctx.model?.provider || "?";
	const model = ctx.model?.id || "no-model";
	const modelStr = `${dim("model:")} ${dim(`${provider}:`)}${theme.fg("accent", model)}`;

	const level = pi.getThinkingLevel();
	const levelStr = `${dim("· level:")} ${theme.fg(thinkingLevelColor(level), level)}`;

	const { tokensPerSecond, timeToFirstTokenMs } = session.speed.snapshot();
	const speedValueStr =
		tokensPerSecond > 0
			? theme.fg(tokensPerSecondColor(tokensPerSecond), `~${tokensPerSecond.toFixed(0)}t/s`)
			: dim("--");
	const latencyValueStr =
		timeToFirstTokenMs > 0
			? theme.fg(latencyColor(timeToFirstTokenMs), `~${(timeToFirstTokenMs / 1000).toFixed(2)}s`)
			: dim("--");
	const speedClusterStr = ` ${dim("·")} ${dim("speed:")} ${speedValueStr} ${dim("·")} ${dim("latency:")} ${latencyValueStr}`;

	const branch = footerData.getGitBranch();
	const branchStr = branch ? ` ${dim("· git:")} ${dim(branch)}` : "";

	const ctxColor = contextPercent != null ? contextUsageColor(contextPercent) : "dim";
	const ctxStr =
		contextPercent != null
			? ` ${dim("· context:")} ${theme.fg(ctxColor, progressBar(contextPercent))} ${theme.fg(ctxColor, `${contextPercent.toFixed(2)}%`)}`
			: ` ${dim("· context:")} ${dim("?")}`;

	return `${modelStr} ${levelStr}${ctxStr}${speedClusterStr}${branchStr}`;
}

function renderRightSection(
	theme: any,
	totals: UsageTotals,
	currency: CurrencyConverter,
): string {
	const dim = (s: string) => theme.fg("muted", s);
	const accent = (s: string) => theme.fg("accent", s);

	const totalInput = totals.inputTokens + totals.cacheRead;
	
	const cacheRatio =
		totalInput > 0 ? ((totals.cacheRead / totalInput) * 100).toFixed(1) : "0";

	const inputSection = `${dim("input:")} ${accent(formatTokenCount(totalInput))}`;
	const cacheSection =
		`${dim("cache:")} ${theme.fg("success", formatTokenCount(totals.cacheRead))} ${dim("(")}${theme.fg("success", `${cacheRatio}%`)}${dim(")")}`;

	const outputSection = `${dim("output:")} ${accent(formatTokenCount(totals.outputTokens))}`;

	const costSection = `${dim("cost:")} ${theme.fg("warning", currency.formatIdr(totals.costUsd))}`;

	return [inputSection, cacheSection, outputSection, costSection].join(dim(" · "));
}

// ============================================================================
// Extension entry point
// ============================================================================

export default function (pi: ExtensionAPI) {
	let enabled = false;
	let activeSession: FooterSession | null = null;

	function enable(ctx: any) {
		if (enabled) return; // guard against double-enable leaking subscriptions
		enabled = true;

		const session = new FooterSession();
		activeSession = session;

		// pi.on(...) has no unsubscribe — handlers live for the extension's
		// lifetime. On /reload, resetExtensionUI() disposes the *old* footer
		// component while the old message_update handler is still attached.
		// `live` lets that stale handler detect it's been superseded and
		// become a no-op instead of touching a torn-down session/tui.
		let live = true;

		let tui: any = null;

		pi.on("message_update", (event) => {
			if (!live) return;
			if (event.type !== "message_update") return;
			const msg = event.message as any;
			if (msg?.role !== "assistant") return;

			session.speed.onUpdate(charCountOf(msg));
			tui?.requestRender();
		});

		ctx.ui.setFooter((renderTui: any, theme: any, footerData: any) => {
			tui = renderTui;
			const unsubscribeBranch = footerData.onBranchChange(() => renderTui.requestRender());

			return {
				dispose: () => {
					live = false;
					unsubscribeBranch();
				},
				invalidate() {},
				render(width: number): string[] {
					if (ctx.isIdle()) session.speed.onIdle();
					return renderFooterLines({ ctx, pi, theme, footerData, width, session });
				},
			};
		});
	}

	function disable(ctx: any) {
		enabled = false;
		activeSession = null;
		ctx.ui.setFooter(undefined);
	}

	pi.registerCommand("readable-footer", {
		description: "Toggle a clean, labeled footer bar",
		handler: async (_args, ctx) => {
			if (enabled) {
				disable(ctx);
				ctx.ui.notify("Default footer restored", "info");
			} else {
				enable(ctx);
				ctx.ui.notify("Clean footer enabled", "info");
			}
		},
	});

	pi.on("session_start", (_event, ctx) => {
		enable(ctx);
		activeSession?.currency.refresh().then(() => {
			// Rate may have arrived after the first render; trigger a repaint.
			ctx.ui.requestRender?.();
		});
	});
}