@tmustier/pi-usage-extension 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.6.0] - 2026-07-17
+
+### Added
+- **Interactive graph explorer.** New third view mode (cycle with `v`): a braille line chart of usage over time for the active period, with a legend showing per-series totals and shares.
+  - Metrics (`m`): cost, tokens, messages, reasoning tokens.
+  - Grouping (`g`): by provider, by model, by thinking level, or total only — top 6 series plus an `other` rollup, with a bold Total line always drawn.
+  - Cumulative running totals or per-bucket rates (`c`), hourly buckets for day/week periods and daily buckets for Last 30 Days / All Time.
+  - Legend filtering: `↑`/`↓` moves the cursor, `Enter`/`Space` hides or shows a series, `a` shows all. The y-axis rescales to the visible series so small series can be inspected by hiding large ones.
+- **Thinking level and reasoning tokens.** Session parsing now replays `thinking_level_change` entries (compact and spaced JSON styles) to attribute a thinking level to each assistant message, and records `usage.reasoning` token counts. Messages before the first recorded change appear as `unknown`.
+
+### Changed
+- On-disk cache format bumped to v2 (per-message thinking level and reasoning tokens). The first open after upgrading does a one-off full rebuild; older caches are ignored safely.
+
 ## [0.5.0] - 2026-07-17
 
 ### Added

package/README.md

@@ -7,7 +7,7 @@ A Pi extension that displays aggregated usage statistics across all sessions.
 ## Compatibility
 
 - **Pi version:** 0.42.4+
-- **Last updated:** 2026-07-17 (0.5.0)
+- **Last updated:** 2026-07-17 (0.6.0)
 
 ## Installation
 
@@ -57,15 +57,28 @@ In Pi, run:
 
 ### Views
 
-`/usage` has two view modes, toggled with `v`:
+`/usage` has three view modes, cycled with `v`:
 
 - **Table** (default) — per-provider / per-model stats with cost and token breakdown (screenshot at the top of this page).
 - **Insights** — narrative characteristics of your cost for the active time period, e.g. *"X% of your cost was at >150k context"*. Insights are **independent characteristics**, not a breakdown, so they overlap and can sum to more than 100%.
+- **Graphs** — an interactive braille line-chart explorer for usage over time (details below).
 
 ![Insights view of /usage](insights-screenshot.png)
 
 **Unit:** insights are always weighted by recorded API cost (USD). Periods with no recorded cost show an explicit empty state rather than silently switching to a different unit.
 
+### Graph explorer
+
+The **Graphs** view plots usage over time for the active period as a braille line chart, with a legend showing per-series totals and shares.
+
+- **Metric** (`m` to cycle): cost, tokens (input + output + cache write), messages, reasoning tokens.
+- **Grouping** (`g` to cycle): by provider, by model, by thinking level, or total only. The top 6 series are shown individually; the rest merge into an `other` series. A bold **Total** line is always drawn.
+- **Cumulative vs per-bucket** (`c` to toggle): running total across the period (default), or the raw per-bucket rate.
+- **Filtering**: move the legend cursor with `↑`/`↓` and toggle series visibility with `Enter`/`Space` (`a` shows all again). The y-axis rescales to the visible series — hide the big lines to zoom into the small ones.
+- **Buckets**: hourly for Today / This Week / Last Week, daily for Last 30 Days / All Time.
+
+Thinking levels are replayed from `thinking_level_change` entries in each session file; messages before the first recorded change appear as `unknown`. Reasoning token counts come from `usage.reasoning` where providers report them.
+
 The insights currently shown:
 
 | Insight | Threshold |
@@ -114,9 +127,13 @@ On narrow terminals, `/usage` automatically switches to a compact table instead
 | Key | Action |
 |-----|--------|
 | `Tab` / `←` `→` | Switch time period |
-| `↑` `↓` | Select provider *(table view)* |
-| `Enter` / `Space` | Expand/collapse provider to show models *(table view)* |
-| `v` | Toggle between Table and Insights view |
+| `↑` `↓` | Select provider *(table)* / move legend cursor *(graphs)* |
+| `Enter` / `Space` | Expand/collapse provider *(table)* / toggle series visibility *(graphs)* |
+| `v` | Cycle Table → Insights → Graphs view |
+| `m` | Cycle metric: cost / tokens / messages / reasoning *(graphs)* |
+| `g` | Cycle grouping: provider / model / thinking level / total *(graphs)* |
+| `c` | Toggle cumulative vs per-bucket *(graphs)* |
+| `a` | Show all series *(graphs)* |
 | `q` / `Esc` | Close |
 
 ## Performance & Caching
@@ -126,6 +143,7 @@ On narrow terminals, `/usage` automatically switches to a compact table instead
 - **On-disk cache.** Per-file extraction results are cached in `<agentDir>/usage-extension-cache.json` (respects `PI_CODING_AGENT_DIR`), keyed by file size + mtime. Warm opens only re-parse session files that changed since the last run — on a 5.2 GB / 3,310-file corpus that takes the open from ~17 s to ~0.3 s.
 - **First open** after install (or after deleting the cache) does a one-off full build, showing the usual cancellable loader. Cancelling saves partial progress, so the next open resumes where it left off.
 - The cache is safe to delete at any time; it is rebuilt automatically. Corrupt or version-mismatched caches are ignored and rebuilt rather than trusted.
+- **0.6.0 bumps the cache format to v2** (adds thinking level and reasoning tokens per message). The first open after upgrading does a one-off full rebuild, then warm opens are fast again.
 
 ## Provider Notes
 

package/data.ts

@@ -81,12 +81,51 @@ export interface TimeFilteredStats {
 	insights: PeriodInsights;
 }
 
+/**
+ * One (provider, model, thinkingLevel) cell inside an hourly bucket.
+ * Powers the graph explorer; built post-dedupe so it matches table totals.
+ */
+export interface HourlyCell {
+	messages: number;
+	cost: number;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	reasoning: number;
+}
+
+/** Composite key: `${provider}\u0000${model}\u0000${thinkingLevel}` */
+export type HourlyKey = string;
+
+export const HOURLY_KEY_SEP = "\u0000";
+
+export function makeHourlyKey(provider: string, model: string, thinkingLevel: string): HourlyKey {
+	return provider + HOURLY_KEY_SEP + model + HOURLY_KEY_SEP + thinkingLevel;
+}
+
+export function splitHourlyKey(key: HourlyKey): { provider: string; model: string; thinkingLevel: string } {
+	const [provider = "", model = "", thinkingLevel = ""] = key.split(HOURLY_KEY_SEP);
+	return { provider, model, thinkingLevel };
+}
+
+export interface PeriodBounds {
+	todayMs: number;
+	weekStartMs: number;
+	lastWeekStartMs: number;
+	last30DaysStartMs: number;
+	nowMs: number;
+}
+
 export interface UsageData {
 	today: TimeFilteredStats;
 	thisWeek: TimeFilteredStats;
 	lastWeek: TimeFilteredStats;
 	last30Days: TimeFilteredStats;
 	allTime: TimeFilteredStats;
+	/** Deduped usage bucketed by hour start (ms) → series key → metrics. */
+	hourly: Map<number, Map<HourlyKey, HourlyCell>>;
+	bounds: PeriodBounds;
 }
 
 export type TabName = "today" | "thisWeek" | "lastWeek" | "last30Days" | "allTime";
@@ -96,11 +135,15 @@ export const TAB_ORDER: TabName[] = ["today", "thisWeek", "lastWeek", "last30Day
 export interface SessionMessage {
 	provider: string;
 	model: string;
+	/** Thinking level active when the message was produced; "" when unknown. */
+	thinkingLevel: string;
 	cost: number;
 	input: number;
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	/** Reasoning output tokens reported by the provider (0 when absent). */
+	reasoning: number;
 	timestamp: number;
 }
 
@@ -171,6 +214,8 @@ const PATTERN_ASSISTANT_COMPACT = Buffer.from('"role":"assistant"');
 const PATTERN_ASSISTANT_SPACED = Buffer.from('"role": "assistant"');
 const PATTERN_SESSION_COMPACT = Buffer.from('"type":"session"');
 const PATTERN_SESSION_SPACED = Buffer.from('"type": "session"');
+const PATTERN_THINKING_COMPACT = Buffer.from('"type":"thinking_level_change"');
+const PATTERN_THINKING_SPACED = Buffer.from('"type": "thinking_level_change"');
 
 const PARSE_YIELD_EVERY_LINES = 2000;
 
@@ -178,8 +223,10 @@ function lineMightBeRelevant(line: Buffer): boolean {
 	return (
 		line.includes(PATTERN_ASSISTANT_COMPACT) ||
 		line.includes(PATTERN_SESSION_COMPACT) ||
+		line.includes(PATTERN_THINKING_COMPACT) ||
 		line.includes(PATTERN_ASSISTANT_SPACED) ||
-		line.includes(PATTERN_SESSION_SPACED)
+		line.includes(PATTERN_SESSION_SPACED) ||
+		line.includes(PATTERN_THINKING_SPACED)
 	);
 }
 
@@ -191,6 +238,11 @@ function lineMightBeRelevant(line: Buffer): boolean {
 export async function parseSessionBuffer(buffer: Buffer, signal?: AbortSignal): Promise<ParsedSessionFile> {
 	const messages: SessionMessage[] = [];
 	let sessionId = "";
+	// Assistant messages don't carry the thinking level; pi records it as separate
+	// thinking_level_change entries, always written before the first assistant
+	// message of a session. Replaying them in append order attributes each message
+	// to the level active when it was produced.
+	let thinkingLevel = "";
 	let start = 0;
 	let lineNumber = 0;
 
@@ -210,6 +262,8 @@ export async function parseSessionBuffer(buffer: Buffer, signal?: AbortSignal):
 
 				if (entry.type === "session") {
 					sessionId = entry.id;
+				} else if (entry.type === "thinking_level_change") {
+					if (typeof entry.thinkingLevel === "string") thinkingLevel = entry.thinkingLevel;
 				} else if (entry.type === "message" && entry.message?.role === "assistant") {
 					const msg = entry.message;
 					if (msg.usage && msg.provider && msg.model) {
@@ -217,11 +271,13 @@ export async function parseSessionBuffer(buffer: Buffer, signal?: AbortSignal):
 						messages.push({
 							provider: msg.provider,
 							model: msg.model,
+							thinkingLevel,
 							cost: msg.usage.cost?.total || 0,
 							input: msg.usage.input || 0,
 							output: msg.usage.output || 0,
 							cacheRead: msg.usage.cacheRead || 0,
 							cacheWrite: msg.usage.cacheWrite || 0,
+							reasoning: msg.usage.reasoning || 0,
 							timestamp: msg.timestamp || (Number.isNaN(fallbackTs) ? 0 : fallbackTs),
 						});
 					}
@@ -241,7 +297,7 @@ export async function parseSessionBuffer(buffer: Buffer, signal?: AbortSignal):
 // On-disk cache
 // =============================================================================
 
-const CACHE_VERSION = 1;
+const CACHE_VERSION = 2;
 
 type CachedMessageTuple = [
 	providerIdx: number,
@@ -252,6 +308,8 @@ type CachedMessageTuple = [
 	cacheRead: number,
 	cacheWrite: number,
 	timestamp: number,
+	thinkingLevelIdx: number,
+	reasoning: number,
 ];
 
 interface CacheFileEntry {
@@ -293,25 +351,28 @@ export async function loadUsageCache(cachePath: string): Promise<Map<string, Cac
 		const messages: SessionMessage[] = [];
 		let valid = true;
 		for (const tuple of entry.messages) {
-			if (!Array.isArray(tuple) || tuple.length !== 8) {
+			if (!Array.isArray(tuple) || tuple.length !== 10) {
 				valid = false;
 				break;
 			}
 			const provider = names[tuple[0]];
 			const model = names[tuple[1]];
-			if (typeof provider !== "string" || typeof model !== "string") {
+			const thinkingLevel = names[tuple[8]];
+			if (typeof provider !== "string" || typeof model !== "string" || typeof thinkingLevel !== "string") {
 				valid = false;
 				break;
 			}
 			messages.push({
 				provider,
 				model,
+				thinkingLevel,
 				cost: Number(tuple[2]) || 0,
 				input: Number(tuple[3]) || 0,
 				output: Number(tuple[4]) || 0,
 				cacheRead: Number(tuple[5]) || 0,
 				cacheWrite: Number(tuple[6]) || 0,
 				timestamp: Number(tuple[7]) || 0,
+				reasoning: Number(tuple[9]) || 0,
 			});
 		}
 		if (!valid) continue;
@@ -352,6 +413,8 @@ export async function saveUsageCache(cachePath: string, states: Map<string, Cach
 				m.cacheRead,
 				m.cacheWrite,
 				m.timestamp,
+				intern(m.thinkingLevel),
+				m.reasoning,
 			]),
 		};
 	}
@@ -392,16 +455,43 @@ function emptyPeriodRawData(): PeriodRawData {
 	return { messages: [], sessionCosts: new Map() };
 }
 
-function emptyUsageData(): UsageData {
+function emptyUsageData(bounds: PeriodBounds): UsageData {
 	return {
 		today: emptyTimeFilteredStats(),
 		thisWeek: emptyTimeFilteredStats(),
 		lastWeek: emptyTimeFilteredStats(),
 		last30Days: emptyTimeFilteredStats(),
 		allTime: emptyTimeFilteredStats(),
+		hourly: new Map(),
+		bounds,
 	};
 }
 
+const HOUR_MS = 3_600_000;
+
+function addToHourlyBuckets(hourly: Map<number, Map<HourlyKey, HourlyCell>>, msg: SessionMessage): void {
+	if (msg.timestamp <= 0) return; // Unknown time can't be placed on a time axis.
+	const hour = Math.floor(msg.timestamp / HOUR_MS) * HOUR_MS;
+	let bucket = hourly.get(hour);
+	if (!bucket) {
+		bucket = new Map();
+		hourly.set(hour, bucket);
+	}
+	const key = makeHourlyKey(msg.provider, msg.model, msg.thinkingLevel);
+	let cell = bucket.get(key);
+	if (!cell) {
+		cell = { messages: 0, cost: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0 };
+		bucket.set(key, cell);
+	}
+	cell.messages++;
+	cell.cost += msg.cost;
+	cell.input += msg.input;
+	cell.output += msg.output;
+	cell.cacheRead += msg.cacheRead;
+	cell.cacheWrite += msg.cacheWrite;
+	cell.reasoning += msg.reasoning;
+}
+
 // Helper to accumulate stats into a target
 function accumulateStats(
 	target: BaseStats,
@@ -461,6 +551,8 @@ function addMessagesToUsageData(
 			}
 		}
 
+		addToHourlyBuckets(data.hourly, msg);
+
 		const periods = getPeriodsForTimestamp(msg.timestamp, todayMs, weekStartMs, lastWeekStartMs, last30DaysStartMs);
 		const tokens = {
 			// Count fresh tokens processed this turn.
@@ -659,7 +751,7 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 	}
 
 	// 6. Aggregate in sorted path order with cross-file dedupe.
-	const data = emptyUsageData();
+	const data = emptyUsageData({ todayMs, weekStartMs, lastWeekStartMs, last30DaysStartMs, nowMs: now.getTime() });
 	const rawByPeriod: Record<TabName, PeriodRawData> = {
 		today: emptyPeriodRawData(),
 		thisWeek: emptyPeriodRawData(),

package/graph.ts

@@ -0,0 +1,386 @@
+/**
+ * Graph explorer model + braille chart rendering for /usage.
+ *
+ * Everything here is pure and theme-free: series building works off the hourly
+ * buckets produced by data.ts, and the renderer emits plain text plus a
+ * colorize callback so the UI layer owns all styling. This keeps the module
+ * fully unit-testable.
+ */
+
+// Explicit .ts extension so plain `node --test` (type stripping) can resolve
+// this module too; pi's extension loader accepts it as well.
+import type { HourlyCell, HourlyKey, PeriodBounds, TabName } from "./data.ts";
+import { splitHourlyKey } from "./data.ts";
+
+// =============================================================================
+// Options and model types
+// =============================================================================
+
+export type GraphMetric = "cost" | "tokens" | "messages" | "reasoning";
+export type GraphGroupBy = "provider" | "model" | "thinking" | "total";
+
+export const METRIC_ORDER: GraphMetric[] = ["cost", "tokens", "messages", "reasoning"];
+export const GROUP_ORDER: GraphGroupBy[] = ["provider", "model", "thinking", "total"];
+
+export const METRIC_LABELS: Record<GraphMetric, string> = {
+	cost: "cost",
+	tokens: "tokens",
+	messages: "messages",
+	reasoning: "reasoning tokens",
+};
+
+export const GROUP_LABELS: Record<GraphGroupBy, string> = {
+	provider: "by provider",
+	model: "by model",
+	thinking: "by thinking level",
+	total: "total only",
+};
+
+/** Series beyond this cap are merged into a single "other" series. */
+export const MAX_GROUP_SERIES = 6;
+
+export const TOTAL_SERIES_KEY = "\u0000total";
+export const OTHER_SERIES_KEY = "\u0000other";
+
+export interface GraphOptions {
+	period: TabName;
+	metric: GraphMetric;
+	groupBy: GraphGroupBy;
+	cumulative: boolean;
+	/** Series keys hidden via the legend. */
+	hidden?: ReadonlySet<string>;
+	bounds: PeriodBounds;
+}
+
+export interface GraphSeries {
+	key: string;
+	label: string;
+	/** One value per bucket. Cumulative when options.cumulative. */
+	points: number[];
+	/** Period total for this series (not affected by cumulative). */
+	total: number;
+	hidden: boolean;
+}
+
+export interface GraphModel {
+	series: GraphSeries[];
+	/** Bucket start timestamps (ms), ascending. */
+	bucketStarts: number[];
+	bucketMs: number;
+	domainStartMs: number;
+	domainEndMs: number;
+	/** Max point value across visible series (y-axis scale). */
+	yMax: number;
+	/** Sum of totals across grouped (non-total) series, for legend percentages. */
+	groupedTotal: number;
+}
+
+// =============================================================================
+// Series building
+// =============================================================================
+
+const HOUR_MS = 3_600_000;
+const DAY_MS = 24 * HOUR_MS;
+/** Periods spanning at most this many hours use hourly buckets; otherwise daily. */
+const MAX_HOURLY_BUCKETS = 8 * 24;
+
+function metricOf(cell: HourlyCell, metric: GraphMetric): number {
+	switch (metric) {
+		case "cost":
+			return cell.cost;
+		case "tokens":
+			// Matches the dashboard formula: fresh tokens = input + output + cacheWrite.
+			return cell.input + cell.output + cell.cacheWrite;
+		case "messages":
+			return cell.messages;
+		case "reasoning":
+			return cell.reasoning;
+	}
+}
+
+function groupKeyOf(key: HourlyKey, groupBy: GraphGroupBy): string {
+	if (groupBy === "total") return TOTAL_SERIES_KEY;
+	const { provider, model, thinkingLevel } = splitHourlyKey(key);
+	if (groupBy === "provider") return provider;
+	if (groupBy === "model") return model;
+	return thinkingLevel === "" ? "unknown" : thinkingLevel;
+}
+
+function domainFor(period: TabName, bounds: PeriodBounds, hourly: Map<number, Map<HourlyKey, HourlyCell>>): { startMs: number; endMs: number } {
+	switch (period) {
+		case "today":
+			return { startMs: bounds.todayMs, endMs: bounds.nowMs };
+		case "thisWeek":
+			return { startMs: bounds.weekStartMs, endMs: bounds.nowMs };
+		case "lastWeek":
+			return { startMs: bounds.lastWeekStartMs, endMs: bounds.weekStartMs };
+		case "last30Days":
+			return { startMs: bounds.last30DaysStartMs, endMs: bounds.nowMs };
+		case "allTime": {
+			let first = Number.POSITIVE_INFINITY;
+			for (const hour of hourly.keys()) if (hour < first) first = hour;
+			if (!Number.isFinite(first)) first = bounds.todayMs;
+			return { startMs: Math.min(first, bounds.nowMs), endMs: bounds.nowMs };
+		}
+	}
+}
+
+/**
+ * Build the graph model for one (period, metric, groupBy) view.
+ *
+ * Buckets are hourly for short periods and daily for long ones. Group series
+ * are capped at MAX_GROUP_SERIES by period total; the rest merge into "other".
+ * A Total series is always present (first). Hidden series keep their points
+ * but are excluded from the y-axis scale.
+ */
+export function buildGraphModel(
+	hourly: Map<number, Map<HourlyKey, HourlyCell>>,
+	options: GraphOptions
+): GraphModel {
+	const { startMs, endMs } = domainFor(options.period, options.bounds, hourly);
+	const spanMs = Math.max(endMs - startMs, 1);
+	const bucketMs = spanMs / HOUR_MS <= MAX_HOURLY_BUCKETS ? HOUR_MS : DAY_MS;
+
+	// Bucket starts aligned to the domain start so "day" buckets follow the
+	// local-midnight period boundaries computed by data.ts (DST shifts move a
+	// boundary by an hour, which is invisible at graph resolution).
+	const bucketCount = Math.max(1, Math.ceil(spanMs / bucketMs));
+	const bucketStarts: number[] = [];
+	for (let i = 0; i < bucketCount; i++) bucketStarts.push(startMs + i * bucketMs);
+
+	// Accumulate per-group bucket values.
+	const groupValues = new Map<string, number[]>();
+	const groupTotals = new Map<string, number>();
+	const totalPoints = new Array<number>(bucketCount).fill(0);
+	let totalSum = 0;
+
+	for (const [hour, bucket] of hourly) {
+		if (hour < startMs || hour >= endMs) continue;
+		const idx = Math.min(bucketCount - 1, Math.floor((hour - startMs) / bucketMs));
+		for (const [key, cell] of bucket) {
+			const value = metricOf(cell, options.metric);
+			if (value === 0) continue;
+			totalPoints[idx] += value;
+			totalSum += value;
+			if (options.groupBy !== "total") {
+				const groupKey = groupKeyOf(key, options.groupBy);
+				let points = groupValues.get(groupKey);
+				if (!points) {
+					points = new Array<number>(bucketCount).fill(0);
+					groupValues.set(groupKey, points);
+				}
+				points[idx] += value;
+				groupTotals.set(groupKey, (groupTotals.get(groupKey) ?? 0) + value);
+			}
+		}
+	}
+
+	// Rank groups and cap at MAX_GROUP_SERIES; merge the tail into "other".
+	const ranked = Array.from(groupTotals.entries()).sort((a, b) => b[1] - a[1]);
+	const kept = ranked.slice(0, MAX_GROUP_SERIES);
+	const merged = ranked.slice(MAX_GROUP_SERIES);
+
+	const hidden = options.hidden ?? new Set<string>();
+	const series: GraphSeries[] = [];
+
+	series.push({
+		key: TOTAL_SERIES_KEY,
+		label: "Total",
+		points: totalPoints.slice(),
+		total: totalSum,
+		hidden: hidden.has(TOTAL_SERIES_KEY),
+	});
+
+	for (const [groupKey, total] of kept) {
+		series.push({
+			key: groupKey,
+			label: groupKey,
+			points: groupValues.get(groupKey)!,
+			total,
+			hidden: hidden.has(groupKey),
+		});
+	}
+
+	if (merged.length > 0) {
+		const points = new Array<number>(bucketCount).fill(0);
+		let total = 0;
+		for (const [groupKey, groupTotal] of merged) {
+			const groupPoints = groupValues.get(groupKey)!;
+			for (let i = 0; i < bucketCount; i++) points[i] += groupPoints[i]!;
+			total += groupTotal;
+		}
+		series.push({
+			key: OTHER_SERIES_KEY,
+			label: `other (${merged.length})`,
+			points,
+			total,
+			hidden: hidden.has(OTHER_SERIES_KEY),
+		});
+	}
+
+	if (options.cumulative) {
+		for (const s of series) {
+			let running = 0;
+			s.points = s.points.map((v) => (running += v));
+		}
+	}
+
+	let yMax = 0;
+	for (const s of series) {
+		if (s.hidden) continue;
+		for (const v of s.points) if (v > yMax) yMax = v;
+	}
+
+	return {
+		series,
+		bucketStarts,
+		bucketMs,
+		domainStartMs: startMs,
+		domainEndMs: endMs,
+		yMax,
+		groupedTotal: totalSum,
+	};
+}
+
+// =============================================================================
+// Braille chart rendering
+// =============================================================================
+
+/**
+ * Style callback: seriesIndex is the index into model.series, or -1 for
+ * chart furniture (axes). Return the text styled for the terminal.
+ */
+export type ChartColorize = (seriesIndex: number, text: string) => string;
+
+export interface ChartRenderOptions {
+	width: number;
+	/** Text rows for the plot area (each row is 4 braille dots tall). */
+	height: number;
+	formatValue: (value: number) => string;
+	formatTime: (ms: number) => string;
+	colorize?: ChartColorize;
+}
+
+const BRAILLE_BASE = 0x2800;
+// Dot bit masks by (x: 0=left, 1=right) and (y: 0=top .. 3=bottom).
+const DOT_BITS = [
+	[0x01, 0x02, 0x04, 0x40],
+	[0x08, 0x10, 0x20, 0x80],
+] as const;
+
+/**
+ * Render the model as a braille line chart with a y-axis and an x-axis line.
+ * Returns exactly height + 1 lines (plot rows + x-axis labels).
+ */
+export function renderChart(model: GraphModel, options: ChartRenderOptions): string[] {
+	const colorize: ChartColorize = options.colorize ?? ((_i, text) => text);
+	const plotHeightForLabels = Math.max(options.height, 4);
+	const midRowForLabels = Math.floor((plotHeightForLabels - 1) / 2);
+	const midValue = (model.yMax * (plotHeightForLabels - 1 - midRowForLabels)) / (plotHeightForLabels - 1);
+	const yLabelWidth = Math.max(
+		options.formatValue(model.yMax).length,
+		options.formatValue(midValue).length,
+		options.formatValue(0).length
+	);
+	const axisWidth = yLabelWidth + 2; // label + " ┤" / " │"
+	const plotWidth = Math.max(options.width - axisWidth, 10);
+	const plotHeight = Math.max(options.height, 4);
+	const dotW = plotWidth * 2;
+	const dotH = plotHeight * 4;
+
+	// masks[row][col] per series index — draw order decides which color wins a cell.
+	const cellMasks: number[][] = Array.from({ length: plotHeight }, () => new Array<number>(plotWidth).fill(0));
+	const cellOwner: number[][] = Array.from({ length: plotHeight }, () => new Array<number>(plotWidth).fill(-1));
+
+	const yMax = model.yMax > 0 ? model.yMax : 1;
+	const bucketCount = model.bucketStarts.length;
+
+	const plot = (seriesIndex: number, points: number[]) => {
+		let prevX = -1;
+		let prevY = -1;
+		for (let i = 0; i < bucketCount; i++) {
+			const x = bucketCount === 1 ? dotW - 1 : Math.round((i / (bucketCount - 1)) * (dotW - 1));
+			const y = Math.round((1 - (points[i]! / yMax)) * (dotH - 1));
+			if (prevX >= 0) {
+				// Connect with a vertical-stepped segment for continuity.
+				const steps = Math.max(Math.abs(x - prevX), Math.abs(y - prevY), 1);
+				for (let s = 1; s <= steps; s++) {
+					const ix = Math.round(prevX + ((x - prevX) * s) / steps);
+					const iy = Math.round(prevY + ((y - prevY) * s) / steps);
+					setDot(ix, iy, seriesIndex);
+				}
+			} else {
+				setDot(x, y, seriesIndex);
+			}
+			prevX = x;
+			prevY = y;
+		}
+	};
+
+	const setDot = (x: number, y: number, seriesIndex: number) => {
+		if (x < 0 || y < 0 || x >= dotW || y >= dotH) return;
+		const col = Math.floor(x / 2);
+		const row = Math.floor(y / 4);
+		cellMasks[row]![col]! |= DOT_BITS[x % 2]![y % 4]!;
+		cellOwner[row]![col] = seriesIndex;
+	};
+
+	// Draw least-important first so important series own contested cells:
+	// other → smallest groups → largest group → total.
+	const drawOrder = model.series
+		.map((s, i) => ({ s, i }))
+		.filter(({ s }) => !s.hidden)
+		.sort((a, b) => {
+			const rank = (entry: { s: GraphSeries; i: number }) =>
+				entry.s.key === TOTAL_SERIES_KEY ? Number.POSITIVE_INFINITY : entry.s.key === OTHER_SERIES_KEY ? -1 : entry.s.total;
+			return rank(a) - rank(b);
+		});
+	for (const { s, i } of drawOrder) plot(i, s.points);
+
+	// Compose text rows.
+	const lines: string[] = [];
+	const midRow = Math.floor((plotHeight - 1) / 2);
+	for (let row = 0; row < plotHeight; row++) {
+		let label = "";
+		if (row === 0) label = options.formatValue(model.yMax);
+		else if (row === midRow && plotHeight > 2) label = options.formatValue(midValue);
+		else if (row === plotHeight - 1) label = options.formatValue(0);
+		const axisChar = label ? "┤" : "│";
+		let line = colorize(-1, label.padStart(yLabelWidth) + " " + axisChar);
+		// Batch consecutive cells with the same owning series into one colorize
+		// call to keep ANSI overhead proportional to color changes, not cells.
+		let runOwner = -2;
+		let runText = "";
+		const flush = () => {
+			if (!runText) return;
+			line += runOwner === -2 ? runText : colorize(runOwner, runText);
+			runText = "";
+		};
+		for (let col = 0; col < plotWidth; col++) {
+			const mask = cellMasks[row]![col]!;
+			const owner = mask === 0 ? -2 : cellOwner[row]![col]!;
+			if (owner !== runOwner) {
+				flush();
+				runOwner = owner;
+			}
+			runText += mask === 0 ? " " : String.fromCharCode(BRAILLE_BASE + mask);
+		}
+		flush();
+		lines.push(line);
+	}
+
+	// X-axis labels: start, optional middle, end.
+	const startLabel = options.formatTime(model.domainStartMs);
+	const endLabel = options.formatTime(model.domainEndMs);
+	const midLabel = plotWidth >= startLabel.length + endLabel.length + 14 ? options.formatTime(model.domainStartMs + (model.domainEndMs - model.domainStartMs) / 2) : "";
+	let axis = " ".repeat(yLabelWidth + 2) + startLabel;
+	if (midLabel) {
+		const midPos = yLabelWidth + 2 + Math.floor(plotWidth / 2 - midLabel.length / 2);
+		axis = axis.padEnd(midPos) + midLabel;
+	}
+	const endPos = yLabelWidth + 2 + plotWidth - endLabel.length;
+	axis = axis.padEnd(Math.max(endPos, axis.length + 1)) + endLabel;
+	lines.push(colorize(-1, axis));
+
+	return lines;
+}

package/index.ts

@@ -15,8 +15,20 @@ import { CancellableLoader, Container, Spacer, matchesKey, visibleWidth, truncat
 
 import { collectUsageData, TAB_ORDER } from "./data";
 import type { BaseStats, TabName, UsageData } from "./data";
+import {
+	buildGraphModel,
+	renderChart,
+	GROUP_LABELS,
+	GROUP_ORDER,
+	METRIC_LABELS,
+	METRIC_ORDER,
+	TOTAL_SERIES_KEY,
+} from "./graph";
+import type { GraphGroupBy, GraphMetric, GraphModel } from "./graph";
 
-type ViewMode = "table" | "insights";
+type ViewMode = "table" | "insights" | "graph";
+
+const VIEW_CYCLE: ViewMode[] = ["table", "insights", "graph"];
 
 // =============================================================================
 // Column Configuration
@@ -137,6 +149,32 @@ function formatNumber(n: number): string {
 	return n.toLocaleString();
 }
 
+// Compact axis/legend formatters for the graph view.
+function formatAxisCost(v: number): string {
+	if (v === 0) return "$0";
+	if (v < 1) return `$${v.toFixed(2)}`;
+	if (v < 100) return `$${v.toFixed(1)}`;
+	if (v < 10_000) return `$${Math.round(v)}`;
+	if (v < 1_000_000) return `$${(v / 1000).toFixed(1)}k`;
+	return `$${(v / 1_000_000).toFixed(2)}M`;
+}
+
+function formatAxisCount(v: number): string {
+	if (v === 0) return "0";
+	if (v < 1000) return String(Math.round(v));
+	if (v < 1_000_000) return `${(v / 1000).toFixed(v < 10_000 ? 1 : 0)}k`;
+	if (v < 1_000_000_000) return `${(v / 1_000_000).toFixed(1)}M`;
+	return `${(v / 1_000_000_000).toFixed(1)}B`;
+}
+
+// Bright ANSI palette for graph series (Total uses index 0).
+const SERIES_COLORS = ["\x1b[97m", "\x1b[96m", "\x1b[95m", "\x1b[93m", "\x1b[92m", "\x1b[94m", "\x1b[91m", "\x1b[90m"];
+const COLOR_RESET = "\x1b[39m";
+
+function seriesColor(index: number): string {
+	return SERIES_COLORS[index % SERIES_COLORS.length]!;
+}
+
 function formatInsightPercent(p: number): string {
 	if (p >= 10) return `${Math.round(p)}%`;
 	return `${Math.round(p * 10) / 10}%`;
@@ -225,6 +263,13 @@ class UsageComponent {
 	private requestRender: () => void;
 	private done: () => void;
 
+	// Graph explorer state.
+	private graphMetric: GraphMetric = "cost";
+	private graphGroupBy: GraphGroupBy = "provider";
+	private graphCumulative = true;
+	private graphHidden = new Set<string>();
+	private graphLegendIndex = 0;
+
 	constructor(theme: Theme, data: UsageData, requestRender: () => void, done: () => void) {
 		this.theme = theme;
 		this.requestRender = requestRender;
@@ -248,11 +293,16 @@ class UsageComponent {
 		}
 
 		if (matchesKey(data, "v")) {
-			this.viewMode = this.viewMode === "table" ? "insights" : "table";
+			const idx = VIEW_CYCLE.indexOf(this.viewMode);
+			this.viewMode = VIEW_CYCLE[(idx + 1) % VIEW_CYCLE.length]!;
 			this.requestRender();
 			return;
 		}
 
+		if (this.viewMode === "graph" && this.handleGraphInput(data)) {
+			return;
+		}
+
 		if (matchesKey(data, "tab") || matchesKey(data, "right")) {
 			const idx = TAB_ORDER.indexOf(this.activeTab);
 			this.activeTab = TAB_ORDER[(idx + 1) % TAB_ORDER.length]!;
@@ -263,6 +313,8 @@ class UsageComponent {
 			this.activeTab = TAB_ORDER[(idx - 1 + TAB_ORDER.length) % TAB_ORDER.length]!;
 			this.updateProviderOrder();
 			this.requestRender();
+		} else if (this.viewMode === "graph") {
+			// Graph-specific keys were handled above; swallow table-only keys.
 		} else if (this.viewMode === "table" && matchesKey(data, "up")) {
 			if (this.selectedIndex > 0) {
 				this.selectedIndex--;
@@ -290,7 +342,57 @@ class UsageComponent {
 	// Render Methods
 	// -------------------------------------------------------------------------
 
+	private handleGraphInput(data: string): boolean {
+		if (matchesKey(data, "m")) {
+			const idx = METRIC_ORDER.indexOf(this.graphMetric);
+			this.graphMetric = METRIC_ORDER[(idx + 1) % METRIC_ORDER.length]!;
+		} else if (matchesKey(data, "g")) {
+			const idx = GROUP_ORDER.indexOf(this.graphGroupBy);
+			this.graphGroupBy = GROUP_ORDER[(idx + 1) % GROUP_ORDER.length]!;
+			this.graphHidden.clear();
+			this.graphLegendIndex = 0;
+		} else if (matchesKey(data, "c")) {
+			this.graphCumulative = !this.graphCumulative;
+		} else if (matchesKey(data, "a")) {
+			this.graphHidden.clear();
+		} else if (matchesKey(data, "up")) {
+			this.graphLegendIndex = Math.max(0, this.graphLegendIndex - 1);
+		} else if (matchesKey(data, "down")) {
+			const count = this.buildGraphModelForView().series.length;
+			this.graphLegendIndex = Math.min(Math.max(count - 1, 0), this.graphLegendIndex + 1);
+		} else if (matchesKey(data, "enter") || matchesKey(data, "space")) {
+			const model = this.buildGraphModelForView();
+			const target = model.series[this.graphLegendIndex];
+			if (target) {
+				if (this.graphHidden.has(target.key)) this.graphHidden.delete(target.key);
+				else this.graphHidden.add(target.key);
+			}
+		} else {
+			return false;
+		}
+		this.requestRender();
+		return true;
+	}
+
+	private buildGraphModelForView(): GraphModel {
+		return buildGraphModel(this.data.hourly, {
+			period: this.activeTab,
+			metric: this.graphMetric,
+			groupBy: this.graphGroupBy,
+			cumulative: this.graphCumulative,
+			hidden: this.graphHidden,
+			bounds: this.data.bounds,
+		});
+	}
+
 	render(width: number): string[] {
+		if (this.viewMode === "graph") {
+			return clampLines(
+				[...this.renderTitle(), ...this.renderTabs(width, getTableLayout(width)), ...this.renderGraph(width), ...this.renderHelp(width)],
+				width
+			);
+		}
+
 		if (this.viewMode === "insights") {
 			return clampLines(
 				[
@@ -320,10 +422,67 @@ class UsageComponent {
 
 	private renderTitle(): string[] {
 		const th = this.theme;
-		const label = this.viewMode === "insights" ? "Usage Insights" : "Usage Statistics";
+		const label =
+			this.viewMode === "insights" ? "Usage Insights" : this.viewMode === "graph" ? "Usage Graphs" : "Usage Statistics";
 		return [th.fg("accent", th.bold(label)), ""];
 	}
 
+	private renderGraph(width: number): string[] {
+		const th = this.theme;
+		const model = this.buildGraphModelForView();
+		const lines: string[] = [];
+
+		const modeLabel = `${this.graphCumulative ? "Cumulative" : "Per bucket"} ${METRIC_LABELS[this.graphMetric]} · ${GROUP_LABELS[this.graphGroupBy]}`;
+		lines.push(th.fg("muted", modeLabel));
+		lines.push("");
+
+		if (model.groupedTotal === 0 && model.series.every((s) => s.total === 0)) {
+			lines.push(th.fg("dim", "  No usage data for this period"));
+			lines.push("");
+			return lines;
+		}
+
+		const formatValue = this.graphMetric === "cost" ? formatAxisCost : formatAxisCount;
+		const spanMs = model.domainEndMs - model.domainStartMs;
+		const formatTime = (ms: number): string => {
+			const d = new Date(ms);
+			if (spanMs <= 26 * 3_600_000) {
+				return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+			}
+			return d.toLocaleDateString(undefined, { day: "numeric", month: "short" });
+		};
+
+		const chartHeight = 12;
+		const chart = renderChart(model, {
+			width: Math.max(Math.min(width, 110), 30),
+			height: chartHeight,
+			formatValue,
+			formatTime,
+			colorize: (seriesIndex, text) => {
+				if (seriesIndex < 0) return th.fg("dim", text);
+				return seriesColor(seriesIndex) + text + COLOR_RESET;
+			},
+		});
+		lines.push(...chart);
+		lines.push("");
+
+		// Legend with selection cursor and hide/show state.
+		for (let i = 0; i < model.series.length; i++) {
+			const s = model.series[i]!;
+			const cursor = i === this.graphLegendIndex ? th.fg("accent", "▸ ") : "  ";
+			const marker = s.hidden ? th.fg("dim", "○") : seriesColor(i) + "●" + COLOR_RESET;
+			const value = this.graphMetric === "cost" ? formatAxisCost(s.total) : formatAxisCount(s.total);
+			const pct =
+				s.key !== TOTAL_SERIES_KEY && model.groupedTotal > 0
+					? ` ${th.fg("dim", `${Math.round((s.total / model.groupedTotal) * 100)}%`)}`
+					: "";
+			const label = s.hidden ? th.fg("dim", s.label) : s.key === TOTAL_SERIES_KEY ? th.bold(s.label) : s.label;
+			lines.push(`${cursor}${marker} ${padRight(label, 24)} ${padLeft(value, 8)}${pct}`);
+		}
+		lines.push("");
+		return lines;
+	}
+
 	private renderInsights(width: number): string[] {
 		const th = this.theme;
 		const stats = this.data[this.activeTab];
@@ -494,11 +653,19 @@ class UsageComponent {
 
 	private renderHelp(width: number): string[] {
 		const variants =
-			this.viewMode === "insights"
+			this.viewMode === "graph"
+				? [
+						"[Tab/←→] period  [m] metric  [g] group  [c] cumulative  [↑↓/Enter] filter  [a] all  [v] view  [q] close",
+						"[Tab] period  [m] metric  [g] group  [c] cumul  [↑↓/Enter] filter  [v] view  [q] close",
+						"[m] metric  [g] group  [c] cumul  [↑↓] filter  [q] close",
+						"[m] [g] [c] [↑↓] [q]",
+						"[q] close",
+				  ]
+				: this.viewMode === "insights"
 				? [
-						"[Tab/←→] period  [v] table view  [q] close",
-						"[Tab] period  [v] table  [q] close",
-						"[v] table  [q] close",
+						"[Tab/←→] period  [v] graph view  [q] close",
+						"[Tab] period  [v] graphs  [q] close",
+						"[v] graphs  [q] close",
 						"[q] close",
 				  ]
 				: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmustier/pi-usage-extension",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Usage statistics dashboard for Pi sessions.",
   "license": "MIT",
   "author": "Thomas Mustier",