@hank-warren/pi-stats 0.3.3 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @hank-warren/pi-stats
 
+## 0.4.1
+
+### Patch Changes
+
+- c079c51: Scan sessions through a bounded worker pool instead of one file at a time.
+
+  The stats scan now runs an ordered pool capped at eight concurrent readers, reduced by the discovery index, which shortens a cold scan over a large session history. Results stay in discovery order regardless of completion order, and progress is reported monotonically.
+
+  Cancellation is settled rather than abandoned: an abort stops further work being assigned and publishes nothing afterwards, but waits for reads already in flight, so the caller's `catch` never runs while file reads are still landing in the result array or progress is still being reported into a dashboard that is being torn down.
+
+## 0.4.0
+
+### Minor Changes
+
+- 5e0e3f5: Add Tools and Projects tabs to the `/stats` dashboard.
+
+  The Tools tab ranks every recorded tool call for the selected range by call count, with a share bar, error count, and error rate. Tool calls are now tallied from every tool result, not just the few that record model usage, and the `Source` column names the package that registered each tool so extension-provided tools are distinguishable from built-ins. Tools from extensions that are no longer installed still rank but show no source.
+
+  The Projects tab rolls sessions up by their recorded working directory, ranked by tokens, with session counts and cost.
+
+  Tool calls are counted separately from token usage and never affect model attribution. They de-duplicate on the provider tool-call id, so forked sessions do not inflate counts. `Tab` and the arrow keys now cycle four tabs and wrap in both directions.
+
+  The cache format is bumped to version 3 to store the new tool tallies, so the first run after upgrading performs one full rescan.
+
 ## 0.3.3
 
 ### Patch Changes

package/README.md

@@ -20,8 +20,8 @@ Do not install this standalone package on a host that also installs the aggregat
 
 Run `/stats` in interactive mode. The dashboard temporarily replaces the editor and closes with `Escape`.
 
-- `Tab` or `←`/`→`: switch Overview and Models
-- `↑`/`↓`: scroll the model list
+- `Tab` or `←`/`→`: cycle Overview, Models, Tools, and Projects (wraps in both directions)
+- `↑`/`↓`: scroll the list on Models, Tools, and Projects
 - `r`: cycle All time, Last 7 days, and Last 30 days
 - `e`: toggle compact totals (`1.5B`) and exact grouped digits (`1,486,201,553`)
 - `u`: force a full rescan and rebuild the session index
@@ -31,12 +31,18 @@ The Overview compares current-session, selected-range, and all-time usage in one
 
 The Models tab ranks models for the selected range with share bars and a totals row that reconciles with the range total. It attributes assistant usage to the provider response model and keeps otherwise unattributed nested usage in `Tools/summaries`.
 
-Both tabs are responsive: as the terminal narrows, lower-priority columns move to a labelled continuation line under each row instead of disappearing, and the layout stays within a standard 24-row terminal.
+The Tools tab ranks every recorded tool call for the selected range by call count, with a share bar, an error count, and an error rate. Most tool calls record no model usage at all, so they are counted separately from tokens and never affect model attribution. The `Source` column names the package that registered each tool, read from the live tool registry, so extension-provided tools are distinguishable from built-ins at a glance. Because the registry only knows what is installed right now, a tool from an extension you have since removed still appears in the ranking but shows `—` instead of a source.
+
+The Projects tab rolls sessions up by the working directory recorded in each session header, ranked by tokens, with session counts and recorded cost. Sessions whose header carries no working directory are omitted.
+
+Every tab is responsive: as the terminal narrows, lower-priority columns move to a labelled continuation line under each row instead of disappearing, and the layout stays within a standard 24-row terminal.
 
 ## What is counted
 
 Pi writes usage to assistant messages, usage-bearing tool results, compactions, and branch summaries. `pi-stats` recursively reads valid Pi session files and counts every recorded model call, including compacted and abandoned branches. Copied fork history is fingerprinted and counted once.
 
+Tool calls are counted separately from tokens, because most of them record no model usage. Every tool result in a session is tallied by name, along with whether it reported an error. Provider tool-call ids are reused verbatim when a session is forked, so they double as the de-duplication key and a forked branch never inflates the counts. Namespaced names such as `functions.bash` are ranked under their base name.
+
 Persisted subagent files in the conventional `run-*/session.jsonl` layout are included. `pi-processes` does not create model sessions; model usage around its tool calls already belongs to the parent Pi session and therefore needs no separate integration.
 
 ### Extension usage sidecars
@@ -70,6 +76,10 @@ Each variable is matched exactly: `PI_STATS_DISABLE_USAGE_SIDECARS=true` does no
 
 **Guardian or other extension usage is missing.** Sidecar reading is skipped entirely when `PI_STATS_DISABLE_USAGE_SIDECARS=1`. Otherwise confirm the writing extension is enabled and that `<agent dir>/<extension>/usage.jsonl` exists; sidecars are only discovered one level below the agent directory.
 
+**A tool shows `—` in the Source column.** The source is resolved from the live tool registry, which only knows currently installed tools. A tool recorded by an extension that is no longer installed keeps its ranking but cannot be attributed to a package. This is also expected for sessions created by a different Pi host.
+
+**Tool counts jumped after upgrading.** Versions before this one did not record tool calls at all, and the cache was rebuilt once on first run to backfill them from your existing sessions. The one-time rescan is expected; later runs reuse the cache as usual.
+
 **A model shows under `Tools/summaries` instead of its own row.** That bucket holds nested usage that carries no attributable response model, such as some compaction and branch-summary records. It also absorbs Pi's own placeholder turns — assistant messages whose model is `<synthetic>` or missing — but only when they recorded no tokens and no cost; a placeholder that was actually billed keeps its own row so the spend stays visible. Everything in the bucket is counted in the totals either way.
 
 **Costs read `$0.00` or look wrong.** Displayed cost is whatever Pi already recorded in the session; `pi-stats` performs no pricing lookup and contacts no billing API. Providers used through a subscription or proxy commonly record zero cost.
@@ -86,6 +96,6 @@ Sessions remain authoritative. For fast repeat opens, the extension stores one d
 ~/.pi/agent/pi-stats/cache.json
 ```
 
-The location follows `PI_CODING_AGENT_DIR`. The cache contains file stat identity, session IDs/timestamps/working directories, model names, usage counters, and de-duplication fingerprints. It never stores prompts, responses, tool output, or other conversation content. It is written atomically with mode `0600` and can be deleted at any time; the next `/stats` invocation rebuilds it.
+The location follows `PI_CODING_AGENT_DIR`. The cache contains file stat identity, session IDs/timestamps/working directories, model names, tool names with call and error counts, usage counters, and de-duplication fingerprints. It never stores prompts, responses, tool arguments, tool output, or other conversation content. It is written atomically with mode `0600` and can be deleted at any time; the next `/stats` invocation rebuilds it.
 
 No network or billing API is used. Displayed costs are the estimates already recorded by Pi.

package/cache.ts

@@ -5,7 +5,8 @@ import { homedir } from "node:os";
 import { makeIndex, parseSessionText, parseUsageSidecar } from "./stats.ts";
 import type { CachedFileRecord, ScanDiagnostics, SessionRecord, StatsCacheFile, StatsIndex, UsageRecord } from "./types.ts";
 
-const CACHE_VERSION = 2 as const;
+/** Bumped to 3 when tool-call records were added; older caches lack them and must be reparsed. */
+const CACHE_VERSION = 3 as const;
 const SKIP_DIRECTORIES = new Set(["subagent-artifacts"]);
 /** Extensions record out-of-transcript model usage in <agentDir>/<extension>/usage.jsonl. */
 const USAGE_SIDECAR_NAMES = new Set(["usage.jsonl", "usage.jsonl.1"]);
@@ -239,6 +240,64 @@ export function statsCachePath(agentDir: string): string {
 	return join(agentDir, "pi-stats", "cache.json");
 }
 
+export async function mapConcurrentOrdered<T, R>(
+	items: readonly T[],
+	limit: number,
+	worker: (item: T, index: number) => Promise<R>,
+	onProgress?: (completed: number, total: number) => void,
+	signal?: AbortSignal,
+): Promise<R[]> {
+	if (!Number.isSafeInteger(limit) || limit <= 0) throw new Error("concurrency limit must be positive");
+	const results = new Array<R>(items.length);
+	let nextIndex = 0;
+	let completed = 0;
+	// The first failure (an abort, a worker throw, or a progress callback that
+	// throws) stops work being assigned and stops anything else being published,
+	// but never abandons work already in flight: the caller's `catch` must not
+	// run while file reads are still landing in `results` and progress is still
+	// being reported into a widget that is about to be torn down.
+	let failure: unknown;
+	const failed = () => failure !== undefined;
+	const run = async () => {
+		while (!failed()) {
+			try {
+				signal?.throwIfAborted();
+			} catch (error) {
+				failure ??= error;
+				return;
+			}
+			const index = nextIndex;
+			if (index >= items.length) return;
+			nextIndex += 1;
+			try {
+				const value = await worker(items[index]!, index);
+				// Re-check *after* the await: an abort during the read must not still
+				// publish a result or a progress tick into a dashboard that is being
+				// torn down. A sibling runner may not have noticed the abort yet.
+				signal?.throwIfAborted();
+				if (failed()) return;
+				results[index] = value;
+				completed += 1;
+				onProgress?.(completed, items.length);
+			} catch (error) {
+				failure ??= error;
+				return;
+			}
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => run()));
+	if (failed()) throw failure;
+	return results;
+}
+
+type ScannedFile = {
+	file: string;
+	record?: CachedFileRecord;
+	reused: boolean;
+	unreadable: boolean;
+	changed: boolean;
+};
+
 export async function scanStats(options: ScanOptions): Promise<StatsIndex> {
 	const roots = await resolveSessionRoots(options);
 	const sessionFiles = await discoverJsonlFiles(roots, options.signal);
@@ -259,45 +318,65 @@ export async function scanStats(options: ScanOptions): Promise<StatsIndex> {
 	};
 	let changed = options.force === true || !loaded.valid;
 
-	for (let index = 0; index < files.length; index++) {
-		options.signal?.throwIfAborted();
-		const file = files[index]!;
-		try {
-			const metadata = await stat(file);
-			const previous = loaded.cache.files[file];
-			if (!options.force && sameFile(previous, metadata.size, metadata.mtimeMs)) {
-				next.files[file] = previous!;
-				diagnostics.reusedFiles++;
-			} else if (sidecars.has(file)) {
-				const parsed = parseUsageSidecar(file, await readFile(file, "utf8"));
-				next.files[file] = {
-					size: metadata.size,
-					mtimeMs: metadata.mtimeMs,
-					sidecar: parsed.records,
-					malformedLines: parsed.malformedLines,
-				};
-				diagnostics.parsedFiles++;
-				changed = true;
-			} else {
+	const scanned = await mapConcurrentOrdered(
+		files,
+		8,
+		async (file): Promise<ScannedFile> => {
+			options.signal?.throwIfAborted();
+			try {
+				const metadata = await stat(file);
+				const previous = loaded.cache.files[file];
+				if (!options.force && sameFile(previous, metadata.size, metadata.mtimeMs)) {
+					return { file, record: previous!, reused: true, unreadable: false, changed: false };
+				}
+				if (sidecars.has(file)) {
+					const parsed = parseUsageSidecar(file, await readFile(file, "utf8"));
+					return {
+						file,
+						record: {
+							size: metadata.size,
+							mtimeMs: metadata.mtimeMs,
+							sidecar: parsed.records,
+							malformedLines: parsed.malformedLines,
+						},
+						reused: false,
+						unreadable: false,
+						changed: true,
+					};
+				}
 				const parsed = parseSessionText(file, await readFile(file, "utf8"));
-				next.files[file] = {
-					size: metadata.size,
-					mtimeMs: metadata.mtimeMs,
-					...(parsed.ignored ? { ignored: true as const } : {}),
-					...(parsed.session ? { session: parsed.session } : {}),
-					malformedLines: parsed.malformedLines,
+				return {
+					file,
+					record: {
+						size: metadata.size,
+						mtimeMs: metadata.mtimeMs,
+						...(parsed.ignored ? { ignored: true as const } : {}),
+						...(parsed.session ? { session: parsed.session } : {}),
+						malformedLines: parsed.malformedLines,
+					},
+					reused: false,
+					unreadable: false,
+					changed: true,
 				};
-				diagnostics.parsedFiles++;
-				changed = true;
+			} catch {
+				options.signal?.throwIfAborted();
+				return { file, reused: false, unreadable: true, changed: true };
 			}
-			const current = next.files[file]!;
-			if (current.ignored) diagnostics.ignoredFiles++;
-			diagnostics.malformedLines += current.malformedLines;
-		} catch {
-			diagnostics.unreadableFiles++;
-			changed = true;
+		},
+		options.onProgress,
+		options.signal,
+	);
+
+	for (const result of scanned) {
+		if (result.record) {
+			next.files[result.file] = result.record;
+			if (result.reused) diagnostics.reusedFiles++;
+			else diagnostics.parsedFiles++;
+			if (result.record.ignored) diagnostics.ignoredFiles++;
+			diagnostics.malformedLines += result.record.malformedLines;
 		}
-		options.onProgress?.(index + 1, files.length);
+		if (result.unreadable) diagnostics.unreadableFiles++;
+		if (result.changed) changed = true;
 	}
 
 	if (Object.keys(loaded.cache.files).some((file) => !(file in next.files))) changed = true;

package/index.ts

@@ -1,6 +1,6 @@
 import { getAgentDir, type ExtensionAPI, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { isExternalSessionDirectory, scanStats } from "./cache.ts";
-import { buildSnapshot, makeIndex, usageFromEntries } from "./stats.ts";
+import { buildSnapshot, makeIndex, toolCallsFromEntries, usageFromEntries } from "./stats.ts";
 import type { SessionRecord, StatsIndex, StatsRange } from "./types.ts";
 import { StatsWidget } from "./widget.ts";
 
@@ -25,10 +25,30 @@ export function includeInMemorySession(index: StatsIndex, ctx: ExtensionCommandC
 		lastActivityAt: usage.reduce((latest, record) => Math.max(latest, record.timestamp), Number.isFinite(createdAt) ? createdAt : 0),
 		source: "main",
 		usage,
+		toolCalls: toolCallsFromEntries(sessionId, entries, Number.isFinite(createdAt) ? createdAt : Date.now()),
 	};
 	return makeIndex([...index.sessions, session], index.diagnostics, index.usage.filter((record) => record.kind === "sidecar"));
 }
 
+/**
+ * Map tool name to the package that registered it, for the Tools tab source column.
+ * Only currently-installed tools are known; historical tools from removed extensions stay unlabelled.
+ */
+function toolSourceMap(pi: ExtensionAPI): Map<string, string> {
+	const sources = new Map<string, string>();
+	try {
+		for (const tool of pi.getAllTools()) {
+			const source = tool.sourceInfo?.source;
+			if (typeof tool.name === "string" && typeof source === "string" && source.length > 0) {
+				sources.set(tool.name, source);
+			}
+		}
+	} catch {
+		// An older host without getAllTools() simply renders no source column values.
+	}
+	return sources;
+}
+
 export default function statsExtension(pi: ExtensionAPI): void {
 	pi.registerCommand("stats", {
 		description: "Open all-time Pi token statistics",
@@ -44,6 +64,8 @@ export default function statsExtension(pi: ExtensionAPI): void {
 			let currentIndex: StatsIndex | undefined;
 			let closed = false;
 
+			const toolSources = toolSourceMap(pi);
+
 			await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
 				const snapshot = (range: StatsRange) =>
 					currentIndex
@@ -54,6 +76,7 @@ export default function statsExtension(pi: ExtensionAPI): void {
 								range,
 								Date.now(),
 								ctx.sessionManager.getSessionFile() ?? "current-session.jsonl",
+								toolSources,
 							)
 						: undefined;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-stats",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "A compact /stats dashboard for all-time Pi token usage, including persisted subagents.",
   "type": "module",
   "keywords": [

package/stats.ts

@@ -6,10 +6,13 @@ import {
 	totalTokens,
 	type DayStats,
 	type ModelStats,
+	type ProjectStats,
 	type SessionRecord,
 	type StatsIndex,
 	type StatsRange,
 	type StatsSnapshot,
+	type ToolCallRecord,
+	type ToolStats,
 	type UsageRecord,
 	type UsageTotals,
 } from "./types.ts";
@@ -203,6 +206,39 @@ function normalizeEntry(
 	return undefined;
 }
 
+/**
+ * Extract a tool call from any toolResult entry, whether or not it recorded model usage.
+ * normalizeEntry deliberately drops usage-free results; this is the parallel path that keeps them.
+ */
+function normalizeToolCall(
+	entryValue: unknown,
+	sessionId: string,
+	lineIndex: number,
+	fallbackTimestamp: number,
+): ToolCallRecord | undefined {
+	const entry = object(entryValue);
+	if (!entry || entry.type !== "message") return undefined;
+	const message = object(entry.message);
+	if (!message || message.role !== "toolResult") return undefined;
+	const toolName = typeof message.toolName === "string" && message.toolName.length > 0 ? message.toolName : "tool";
+	const entryTimestamp = timestamp(entry.timestamp, fallbackTimestamp);
+	// The provider tool-call id survives session forks verbatim, so it is the natural dedup key.
+	const toolCallId = typeof message.toolCallId === "string" && message.toolCallId.length > 0 ? message.toolCallId : undefined;
+	return {
+		fingerprint: toolCallId ?? fingerprint([sessionId, lineIndex, toolName, entryTimestamp]).slice(0, 16),
+		timestamp: timestamp(message.timestamp, entryTimestamp),
+		toolName: normalizeToolName(toolName),
+		isError: message.isError === true,
+	};
+}
+
+/** Providers sometimes namespace tool names (`functions.bash`); rank them as one tool. */
+function normalizeToolName(toolName: string): string {
+	const separator = toolName.lastIndexOf(".");
+	const tail = separator >= 0 ? toolName.slice(separator + 1) : toolName;
+	return tail.length > 0 ? tail : toolName;
+}
+
 function sessionSource(filePath: string): "main" | "subagent" {
 	return /(?:^|\/)run-\d+\/session\.jsonl$/.test(filePath) ? "subagent" : "main";
 }
@@ -221,6 +257,7 @@ export function parseSessionText(filePath: string, text: string): ParseResult {
 
 	const headerTimestamp = timestamp(header.timestamp, 0);
 	const usage: UsageRecord[] = [];
+	const toolCalls: ToolCallRecord[] = [];
 	let malformedLines = 0;
 	let earliestActivityAt = Number.POSITIVE_INFINITY;
 	let lastActivityAt = headerTimestamp;
@@ -235,6 +272,8 @@ export function parseSessionText(filePath: string, text: string): ParseResult {
 				earliestActivityAt = Math.min(earliestActivityAt, entryTimestamp);
 				lastActivityAt = Math.max(lastActivityAt, entryTimestamp);
 			}
+			const toolCall = normalizeToolCall(entry, header.id, index, headerTimestamp || entryTimestamp);
+			if (toolCall) toolCalls.push(toolCall);
 			const normalized = normalizeEntry(entry, header.id, filePath, index, headerTimestamp || entryTimestamp);
 			if (normalized) {
 				usage.push(normalized);
@@ -260,6 +299,7 @@ export function parseSessionText(filePath: string, text: string): ParseResult {
 			lastActivityAt: Math.max(lastActivityAt, createdAt),
 			source: sessionSource(filePath),
 			usage,
+			toolCalls,
 		},
 	};
 }
@@ -319,10 +359,35 @@ export function usageFromEntries(
 	});
 }
 
+/** Tool calls for the live in-memory session, which has no file on disk to rescan. */
+export function toolCallsFromEntries(
+	sessionId: string,
+	entries: readonly unknown[],
+	fallbackTimestamp = Date.now(),
+): ToolCallRecord[] {
+	return entries.flatMap((entry, index) => {
+		const normalized = normalizeToolCall(entry, sessionId, index, fallbackTimestamp);
+		return normalized ? [normalized] : [];
+	});
+}
+
 function hasPersistedSubagentChild(record: UsageRecord, sessionPaths: ReadonlySet<string>): boolean {
 	return record.toolName === "subagent" && Boolean(record.childSessionFiles?.some((file) => sessionPaths.has(resolve(file))));
 }
 
+export function deduplicateToolCalls(sessions: readonly SessionRecord[]): ToolCallRecord[] {
+	const seen = new Set<string>();
+	const result: ToolCallRecord[] = [];
+	for (const session of sessions) {
+		for (const record of session.toolCalls ?? []) {
+			if (seen.has(record.fingerprint)) continue;
+			seen.add(record.fingerprint);
+			result.push(record);
+		}
+	}
+	return result;
+}
+
 export function deduplicateUsage(sessions: readonly SessionRecord[], sidecar: readonly UsageRecord[] = []): UsageRecord[] {
 	const sessionPaths = new Set(sessions.map((session) => resolve(session.path)));
 	const seen = new Set<string>();
@@ -383,6 +448,83 @@ function aggregateModels(records: readonly UsageRecord[]): ModelStats[] {
 		.sort((a, b) => b.total - a.total || a.model.localeCompare(b.model));
 }
 
+function aggregateTools(records: readonly ToolCallRecord[], sources: ReadonlyMap<string, string>): ToolStats[] {
+	const byTool = new Map<string, { calls: number; errors: number }>();
+	for (const record of records) {
+		const aggregate = byTool.get(record.toolName) ?? { calls: 0, errors: 0 };
+		aggregate.calls++;
+		if (record.isError) aggregate.errors++;
+		byTool.set(record.toolName, aggregate);
+	}
+	const grandTotal = [...byTool.values()].reduce((sum, entry) => sum + entry.calls, 0);
+	return [...byTool.entries()]
+		.map(([toolName, entry]): ToolStats => {
+			const source = sources.get(toolName);
+			return {
+				toolName,
+				...(source ? { source } : {}),
+				calls: entry.calls,
+				errors: entry.errors,
+				share: grandTotal > 0 ? entry.calls / grandTotal : 0,
+			};
+		})
+		.sort((a, b) => b.calls - a.calls || a.toolName.localeCompare(b.toolName));
+}
+
+/** Sessions carry an absolute cwd; the basename is the useful label, with a parent hint when ambiguous. */
+function projectLabel(cwd: string): string {
+	const normalized = cwd.replace(/[/\\]+$/, "");
+	const parts = normalized.split(/[/\\]/).filter((part) => part.length > 0);
+	return parts[parts.length - 1] ?? normalized;
+}
+
+/**
+ * Roll sessions up by working directory.
+ *
+ * `counted` holds the fingerprints that survived de-duplication, so forked history and usage
+ * already attributed to a persisted subagent child are not counted a second time here. Without
+ * it the project totals would exceed the all-time total they are supposed to partition.
+ */
+function aggregateProjects(
+	sessions: readonly SessionRecord[],
+	counted: ReadonlySet<string>,
+	cutoff: number,
+	now: number,
+): ProjectStats[] {
+	const byProject = new Map<string, { sessions: number; total: number; cost: number }>();
+	const seen = new Set<string>();
+	for (const session of sessions) {
+		if (!session.cwd) continue;
+		const records = session.usage.filter((record) => {
+			if (record.timestamp < cutoff || record.timestamp > now) return false;
+			if (!counted.has(record.fingerprint) || seen.has(record.fingerprint)) return false;
+			seen.add(record.fingerprint);
+			return true;
+		});
+		// A session counts toward its project whenever it was active in range, even with no billed usage.
+		const active = records.length > 0 || (session.lastActivityAt >= cutoff && session.lastActivityAt <= now);
+		if (!active) continue;
+		const aggregate = byProject.get(session.cwd) ?? { sessions: 0, total: 0, cost: 0 };
+		aggregate.sessions++;
+		for (const record of records) {
+			aggregate.total += totalTokens(record.usage);
+			aggregate.cost += record.usage.cost;
+		}
+		byProject.set(session.cwd, aggregate);
+	}
+	const grandTotal = [...byProject.values()].reduce((sum, entry) => sum + entry.total, 0);
+	return [...byProject.entries()]
+		.map(([cwd, entry]): ProjectStats => ({
+			cwd,
+			label: projectLabel(cwd),
+			sessions: entry.sessions,
+			total: entry.total,
+			cost: entry.cost,
+			share: grandTotal > 0 ? entry.total / grandTotal : 0,
+		}))
+		.sort((a, b) => b.total - a.total || b.sessions - a.sessions || a.label.localeCompare(b.label));
+}
+
 function streaks(days: readonly string[], now: number): { current: number; longest: number } {
 	const unique = [...new Set(days)].sort();
 	let longest = 0;
@@ -428,6 +570,7 @@ export function buildSnapshot(
 	range: StatsRange,
 	now = Date.now(),
 	currentSessionFile = "current-session.jsonl",
+	toolSources: ReadonlyMap<string, string> = new Map(),
 ): StatsSnapshot {
 	const cutoff = rangeStart(range, now);
 	const periodRecords = range === "all"
@@ -445,6 +588,11 @@ export function buildSnapshot(
 	const models = aggregateModels(periodRecords);
 	const allModels = aggregateModels(index.usage);
 	const sessions = uniqueSessions(index.sessions);
+	const periodToolCalls = range === "all"
+		? index.toolCalls
+		: index.toolCalls.filter((record) => record.timestamp >= cutoff && record.timestamp <= now);
+	const tools = aggregateTools(periodToolCalls, toolSources);
+	const projects = aggregateProjects(sessions, new Set(index.usage.map((record) => record.fingerprint)), cutoff, now);
 	const sessionPaths = new Set(index.sessions.map((session) => resolve(session.path)));
 	const currentRecords = usageFromEntries(currentSessionId, currentEntries, now, currentSessionFile)
 		.filter((record) => !hasPersistedSubagentChild(record, sessionPaths));
@@ -457,6 +605,8 @@ export function buildSnapshot(
 		period: total(periodRecords),
 		currentSession: total(currentRecords),
 		models,
+		tools,
+		projects,
 		days,
 		sessionCount: sessions.length,
 		mainSessionCount: sessions.filter((session) => session.source === "main").length,
@@ -479,5 +629,10 @@ export function makeIndex(
 	diagnostics: StatsIndex["diagnostics"],
 	sidecar: UsageRecord[] = [],
 ): StatsIndex {
-	return { sessions, usage: deduplicateUsage(sessions, sidecar), diagnostics };
+	return {
+		sessions,
+		usage: deduplicateUsage(sessions, sidecar),
+		toolCalls: deduplicateToolCalls(sessions),
+		diagnostics,
+	};
 }

package/types.ts

@@ -20,6 +20,19 @@ export interface UsageRecord {
 	childSessionFiles?: string[];
 }
 
+/**
+ * One recorded tool call. Kept separate from UsageRecord because most tool calls carry no
+ * model usage at all: mixing zero-usage records into the usage list would distort model
+ * attribution and call counts on the Models tab.
+ */
+export interface ToolCallRecord {
+	/** Provider tool-call id when present, else a synthetic hash. Copied forks repeat it, so it deduplicates. */
+	fingerprint: string;
+	timestamp: number;
+	toolName: string;
+	isError: boolean;
+}
+
 export interface SessionRecord {
 	path: string;
 	sessionId: string;
@@ -28,6 +41,7 @@ export interface SessionRecord {
 	lastActivityAt: number;
 	source: SessionSource;
 	usage: UsageRecord[];
+	toolCalls: ToolCallRecord[];
 }
 
 export interface CachedFileRecord {
@@ -41,7 +55,7 @@ export interface CachedFileRecord {
 }
 
 export interface StatsCacheFile {
-	version: 2;
+	version: 3;
 	files: Record<string, CachedFileRecord>;
 }
 
@@ -57,6 +71,7 @@ export interface ScanDiagnostics {
 export interface StatsIndex {
 	sessions: SessionRecord[];
 	usage: UsageRecord[];
+	toolCalls: ToolCallRecord[];
 	diagnostics: ScanDiagnostics;
 }
 
@@ -73,12 +88,34 @@ export interface DayStats {
 	total: number;
 }
 
+export interface ToolStats {
+	toolName: string;
+	/** Owning package/extension from the live tool registry, or undefined for tools no longer installed. */
+	source?: string;
+	calls: number;
+	errors: number;
+	share: number;
+}
+
+export interface ProjectStats {
+	/** Absolute working directory recorded in the session header. */
+	cwd: string;
+	/** Short display label, normally the directory basename. */
+	label: string;
+	sessions: number;
+	total: number;
+	cost: number;
+	share: number;
+}
+
 export interface StatsSnapshot {
 	range: StatsRange;
 	allTime: UsageTotals;
 	period: UsageTotals;
 	currentSession: UsageTotals;
 	models: ModelStats[];
+	tools: ToolStats[];
+	projects: ProjectStats[];
 	days: DayStats[];
 	sessionCount: number;
 	mainSessionCount: number;

package/widget.ts

@@ -1,6 +1,14 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
-import { totalTokens, type ModelStats, type StatsRange, type StatsSnapshot, type UsageTotals } from "./types.ts";
+import {
+	totalTokens,
+	type ModelStats,
+	type ProjectStats,
+	type StatsRange,
+	type StatsSnapshot,
+	type ToolStats,
+	type UsageTotals,
+} from "./types.ts";
 
 export type WidgetState =
 	| { kind: "loading"; completed: number; total: number }
@@ -29,6 +37,10 @@ const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "
 const RANGES: StatsRange[] = ["all", "7d", "30d"];
 const RANGE_LABELS: Record<StatsRange, string> = { all: "All time", "7d": "Last 7 days", "30d": "Last 30 days" };
 
+export type StatsTab = "overview" | "models" | "tools" | "projects";
+const TABS: StatsTab[] = ["overview", "models", "tools", "projects"];
+const TAB_LABELS: Record<StatsTab, string> = { overview: "Overview", models: "Models", tools: "Tools", projects: "Projects" };
+
 export function formatTokens(value: number, exact = false): string {
 	const safe = Math.max(0, Math.round(value));
 	if (exact) return safe.toLocaleString("en-US");
@@ -147,7 +159,7 @@ function layoutTable(columns: readonly TableColumn[], rowCount: number, width: n
 
 export class StatsWidget implements Component {
 	private state: WidgetState = { kind: "loading", completed: 0, total: 0 };
-	private tab: "overview" | "models" = "overview";
+	private tab: StatsTab = "overview";
 	private range: StatsRange = "all";
 	private exact = false;
 	private modelOffset = 0;
@@ -175,10 +187,18 @@ export class StatsWidget implements Component {
 
 	setReady(snapshot: StatsSnapshot): void {
 		this.state = { kind: "ready", snapshot };
-		this.modelOffset = Math.max(0, Math.min(this.modelOffset, snapshot.models.length - this.pageSize));
+		this.modelOffset = Math.max(0, Math.min(this.modelOffset, this.listLength(snapshot) - this.pageSize));
 		this.options.requestRender();
 	}
 
+	/** Row count of the scrollable list on the active tab; the Overview tab does not scroll. */
+	private listLength(snapshot: StatsSnapshot): number {
+		if (this.tab === "models") return snapshot.models.length;
+		if (this.tab === "tools") return snapshot.tools.length;
+		if (this.tab === "projects") return snapshot.projects.length;
+		return 0;
+	}
+
 	setError(message: string): void {
 		this.state = { kind: "error", message };
 		this.options.requestRender();
@@ -190,13 +210,11 @@ export class StatsWidget implements Component {
 			return;
 		}
 		if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) {
-			this.tab = this.tab === "overview" ? "models" : "overview";
-			this.options.requestRender();
+			this.switchTab(1);
 			return;
 		}
 		if (matchesKey(data, Key.left)) {
-			this.tab = this.tab === "models" ? "overview" : "models";
-			this.options.requestRender();
+			this.switchTab(-1);
 			return;
 		}
 		if (data === "r" || data === "R") {
@@ -215,9 +233,9 @@ export class StatsWidget implements Component {
 			this.options.onRefresh();
 			return;
 		}
-		if (this.state.kind === "ready" && this.tab === "models") {
+		if (this.state.kind === "ready" && this.tab !== "overview") {
 			if (matchesKey(data, Key.down)) {
-				this.modelOffset = Math.min(Math.max(0, this.state.snapshot.models.length - this.pageSize), this.modelOffset + 1);
+				this.modelOffset = Math.min(Math.max(0, this.listLength(this.state.snapshot) - this.pageSize), this.modelOffset + 1);
 				this.options.requestRender();
 			} else if (matchesKey(data, Key.up)) {
 				this.modelOffset = Math.max(0, this.modelOffset - 1);
@@ -226,6 +244,14 @@ export class StatsWidget implements Component {
 		}
 	}
 
+	/** Tabs wrap in both directions; the scroll offset is per-tab and resets on every switch. */
+	private switchTab(step: number): void {
+		const index = TABS.indexOf(this.tab);
+		this.tab = TABS[(index + step + TABS.length) % TABS.length]!;
+		this.modelOffset = 0;
+		this.options.requestRender();
+	}
+
 	dispose(): void {
 		this.options.onDispose?.();
 	}
@@ -252,10 +278,10 @@ export class StatsWidget implements Component {
 		const title = " PI STATS ";
 		lines.push(theme.fg("borderAccent", "─".repeat(Math.max(1, width))));
 		const rangeChip = RANGE_LABELS[this.range];
-		const spacer = " ".repeat(Math.max(1, width - visibleWidth(`${title}   Overview   Models `) - visibleWidth(rangeChip) - 1));
-		lines.push(
-			`${theme.fg("accent", theme.bold(title))}  ${this.tab === "overview" ? selected("Overview") : normal("Overview")} ${this.tab === "models" ? selected("Models") : normal("Models")}${spacer}${theme.fg("dim", rangeChip)}`,
-		);
+		const chips = TABS.map((tab) => (tab === this.tab ? selected(TAB_LABELS[tab]) : normal(TAB_LABELS[tab]))).join(" ");
+		const chipsWidth = TABS.reduce((sum, tab) => sum + TAB_LABELS[tab].length + 2, 0) + (TABS.length - 1);
+		const spacer = " ".repeat(Math.max(1, width - visibleWidth(title) - 2 - chipsWidth - visibleWidth(rangeChip) - 1));
+		lines.push(`${theme.fg("accent", theme.bold(title))}  ${chips}${spacer}${theme.fg("dim", rangeChip)}`);
 
 		if (this.state.kind === "loading") {
 			const progress = this.state.total > 0 ? ` ${this.state.completed}/${this.state.total}` : "";
@@ -275,13 +301,14 @@ export class StatsWidget implements Component {
 		lines.push(
 			` ${theme.fg("accent", theme.bold(this.tokens(totalTokens(snapshot.allTime))))} ${theme.fg("muted", "tokens all time")} ${theme.fg("dim", `· ${formatCost(snapshot.allTime.cost)} · ${cacheHit(snapshot.allTime)} cache hit`)}`,
 		);
-		lines.push(...(this.tab === "overview" ? this.renderOverview(snapshot, width) : this.renderModels(snapshot, width)));
+		lines.push(...this.renderTab(snapshot, width));
 		const scanWarnings: string[] = [];
 		if (snapshot.diagnostics.unreadableFiles > 0) scanWarnings.push(`${snapshot.diagnostics.unreadableFiles} unreadable file(s)`);
 		if (snapshot.diagnostics.malformedLines > 0) scanWarnings.push(`${snapshot.diagnostics.malformedLines} malformed line(s)`);
 		const warning = scanWarnings.length > 0 ? theme.fg("warning", ` · ⚠ ${scanWarnings.join(" · ")}`) : "";
 		const exactHint = this.exact ? "e compact" : "e exact";
-		lines.push(theme.fg("dim", ` Tab/←→ switch · r range · ${exactHint} · u refresh · Esc close`) + warning);
+		const scrollHint = this.tab === "overview" ? "" : " · ↑↓ scroll";
+		lines.push(theme.fg("dim", ` Tab/←→ switch${scrollHint} · r range · ${exactHint} · u refresh · Esc close`) + warning);
 		lines.push(theme.fg("borderMuted", "─".repeat(Math.max(1, width))));
 		return lines;
 	}
@@ -427,6 +454,113 @@ export class StatsWidget implements Component {
 		return lines;
 	}
 
+	private renderTab(snapshot: StatsSnapshot, width: number): string[] {
+		if (this.tab === "models") return this.renderModels(snapshot, width);
+		if (this.tab === "tools") return this.renderTools(snapshot, width);
+		if (this.tab === "projects") return this.renderProjects(snapshot, width);
+		return this.renderOverview(snapshot, width);
+	}
+
+	/**
+	 * Shared body for the ranked tabs: one layout across data rows plus a trailing summary row,
+	 * so column widths stay stable while scrolling and the summary aligns exactly.
+	 */
+	private renderRanked(columns: TableColumn[], dataRows: number, width: number, noun: string): string[] {
+		const { theme } = this.options;
+		const entries = dataRows + 1;
+		const summaryIndex = entries - 1;
+		const table = layoutTable(columns, entries, width);
+
+		const rowsPerEntry = 1 + Math.max(0, ...table.extras.slice(0, summaryIndex).map((extra) => extra.length));
+		const summaryRows = 2 + (table.extras[summaryIndex]?.length ?? 0);
+		const budget = MAX_ROWS - CHROME_ROWS - 1 - summaryRows - 1;
+		this.pageSize = Math.max(MIN_MODEL_PAGE, Math.min(MAX_MODEL_PAGE, Math.floor(budget / rowsPerEntry)));
+		const start = Math.min(this.modelOffset, Math.max(0, dataRows - this.pageSize));
+		this.modelOffset = start;
+		const end = Math.min(dataRows, start + this.pageSize);
+
+		const lines = [theme.fg("dim", table.header)];
+		for (let index = start; index < end; index++) {
+			lines.push(theme.fg("text", table.rows[index] ?? ""));
+			for (const extra of table.extras[index] ?? []) lines.push(theme.fg("dim", extra));
+		}
+		lines.push(theme.fg("borderMuted", ` ${"─".repeat(Math.max(1, Math.min(width - 1, table.width)))}`));
+		lines.push(theme.fg("muted", table.rows[summaryIndex] ?? ""));
+		for (const extra of table.extras[summaryIndex] ?? []) lines.push(theme.fg("dim", extra));
+		if (dataRows > this.pageSize) {
+			lines.push(theme.fg("dim", ` ↑↓ ${noun} ${start + 1}-${end} of ${dataRows}`));
+		}
+		return lines;
+	}
+
+	/** Proportional bar shared by the ranked tabs, scaled to the largest share in the list. */
+	private shareBar(share: number, maximum: number): string {
+		if (maximum <= 0) return "";
+		const filled = Math.max(0, Math.min(6, (share / maximum) * 6));
+		const whole = Math.floor(filled);
+		const eighths = Math.round((filled - whole) * 8);
+		const partial = eighths > 0 ? "▏▎▍▌▋▊▉█"[eighths - 1]! : "";
+		return padRight("█".repeat(whole) + partial, 6);
+	}
+
+	private renderTools(snapshot: StatsSnapshot, width: number): string[] {
+		const { theme } = this.options;
+		if (snapshot.tools.length === 0) return [theme.fg("muted", ` No tool calls in ${RANGE_LABELS[snapshot.range].toLowerCase()}.`)];
+
+		const calls = snapshot.tools.reduce((sum, tool) => sum + tool.calls, 0);
+		const errors = snapshot.tools.reduce((sum, tool) => sum + tool.errors, 0);
+		const summaryRow: ToolStats = {
+			toolName: `${snapshot.tools.length} tool${snapshot.tools.length === 1 ? "" : "s"}`,
+			calls,
+			errors,
+			share: 1,
+		};
+		const rows = [...snapshot.tools, summaryRow];
+		const maximum = Math.max(0, ...snapshot.tools.map((tool) => tool.share));
+		const isSummary = (index: number) => index >= snapshot.tools.length;
+		const errorRate = (tool: ToolStats) => (tool.calls > 0 ? `${((tool.errors / tool.calls) * 100).toFixed(1)}%` : "—");
+		const columns: TableColumn[] = [
+			{ header: "Tool", cells: rows.map((tool) => tool.toolName), align: "left", drop: 0 },
+			{ header: "Source", cells: rows.map((tool, index) => (isSummary(index) ? "" : (tool.source ?? "—"))), align: "left", drop: 2, label: "from" },
+			{ header: "Calls", cells: rows.map((tool) => tool.calls.toLocaleString("en-US")), align: "right", drop: 0 },
+			{ header: "Share", cells: rows.map((tool) => `${(tool.share * 100).toFixed(1)}%`), align: "right", drop: 3, label: "share" },
+			{ header: "", cells: rows.map((tool, index) => (isSummary(index) ? "" : this.shareBar(tool.share, maximum))), align: "left", drop: 4, decorative: true },
+			{ header: "Errors", cells: rows.map((tool) => tool.errors.toLocaleString("en-US")), align: "right", drop: 1, label: "errors" },
+			{ header: "Err %", cells: rows.map((tool) => errorRate(tool)), align: "right", drop: 1, label: "err rate" },
+		];
+		return this.renderRanked(columns, snapshot.tools.length, width, "tools");
+	}
+
+	private renderProjects(snapshot: StatsSnapshot, width: number): string[] {
+		const { theme } = this.options;
+		if (snapshot.projects.length === 0) return [theme.fg("muted", ` No project activity in ${RANGE_LABELS[snapshot.range].toLowerCase()}.`)];
+
+		const sessions = snapshot.projects.reduce((sum, project) => sum + project.sessions, 0);
+		const total = snapshot.projects.reduce((sum, project) => sum + project.total, 0);
+		const cost = snapshot.projects.reduce((sum, project) => sum + project.cost, 0);
+		const summaryRow: ProjectStats = {
+			cwd: "",
+			label: `${snapshot.projects.length} project${snapshot.projects.length === 1 ? "" : "s"}`,
+			sessions,
+			total,
+			cost,
+			share: 1,
+		};
+		const rows = [...snapshot.projects, summaryRow];
+		const maximum = Math.max(0, ...snapshot.projects.map((project) => project.share));
+		const isSummary = (index: number) => index >= snapshot.projects.length;
+		const columns: TableColumn[] = [
+			{ header: "Project", cells: rows.map((project) => project.label), align: "left", drop: 0 },
+			{ header: "Sessions", cells: rows.map((project) => project.sessions.toLocaleString("en-US")), align: "right", drop: 1, label: "sessions" },
+			{ header: "Share", cells: rows.map((project) => `${(project.share * 100).toFixed(1)}%`), align: "right", drop: 3, label: "share" },
+			{ header: "", cells: rows.map((project, index) => (isSummary(index) ? "" : this.shareBar(project.share, maximum))), align: "left", drop: 4, decorative: true },
+			{ header: "Total", cells: rows.map((project) => this.tokens(project.total)), align: "right", drop: 0 },
+			{ header: "Cost", cells: rows.map((project) => formatCost(project.cost)), align: "right", drop: 1, label: "cost" },
+			{ header: "Path", cells: rows.map((project, index) => (isSummary(index) ? "" : project.cwd)), align: "left", drop: 5, label: "path" },
+		];
+		return this.renderRanked(columns, snapshot.projects.length, width, "projects");
+	}
+
 	private renderModels(snapshot: StatsSnapshot, width: number): string[] {
 		const { theme } = this.options;
 		if (snapshot.models.length === 0) return [theme.fg("muted", ` No model usage in ${RANGE_LABELS[snapshot.range].toLowerCase()}.`)];
@@ -445,44 +579,14 @@ export class StatsWidget implements Component {
 			{ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, cost: 0, calls: 0, total: 0 },
 		);
 		const summaryRow: ModelStats = { ...totals, model: `${snapshot.models.length} model${snapshot.models.length === 1 ? "" : "s"}`, share: 1 };
-		// One layout over every row keeps column widths stable while scrolling and lets the totals row align exactly.
 		const entries = [...snapshot.models, summaryRow];
-		const summaryIndex = entries.length - 1;
-		const table = layoutTable(this.modelColumns(entries, snapshot.models), entries.length, width);
-
-		const rowsPerModel = 1 + Math.max(0, ...table.extras.slice(0, summaryIndex).map((extra) => extra.length));
-		const summaryRows = 2 + (table.extras[summaryIndex]?.length ?? 0);
-		const budget = MAX_ROWS - CHROME_ROWS - 1 - summaryRows - 1;
-		this.pageSize = Math.max(MIN_MODEL_PAGE, Math.min(MAX_MODEL_PAGE, Math.floor(budget / rowsPerModel)));
-		const start = Math.min(this.modelOffset, Math.max(0, snapshot.models.length - this.pageSize));
-		this.modelOffset = start;
-		const end = Math.min(snapshot.models.length, start + this.pageSize);
-
-		const lines = [theme.fg("dim", table.header)];
-		for (let index = start; index < end; index++) {
-			lines.push(theme.fg("text", table.rows[index] ?? ""));
-			for (const extra of table.extras[index] ?? []) lines.push(theme.fg("dim", extra));
-		}
-		lines.push(theme.fg("borderMuted", ` ${"─".repeat(Math.max(1, Math.min(width - 1, table.width)))}`));
-		lines.push(theme.fg("muted", table.rows[summaryIndex] ?? ""));
-		for (const extra of table.extras[summaryIndex] ?? []) lines.push(theme.fg("dim", extra));
-		if (snapshot.models.length > this.pageSize) {
-			lines.push(theme.fg("dim", ` ↑↓ models ${start + 1}-${end} of ${snapshot.models.length}`));
-		}
-		return lines;
+		return this.renderRanked(this.modelColumns(entries, snapshot.models), snapshot.models.length, width, "models");
 	}
 
 	private modelColumns(rows: readonly ModelStats[], ranked: readonly ModelStats[]): TableColumn[] {
 		const maximum = Math.max(0, ...ranked.map((model) => model.share));
 		const isSummary = (index: number) => index >= ranked.length;
-		const bar = (share: number): string => {
-			if (maximum <= 0) return "";
-			const filled = Math.max(0, Math.min(6, (share / maximum) * 6));
-			const whole = Math.floor(filled);
-			const eighths = Math.round((filled - whole) * 8);
-			const partial = eighths > 0 ? "▏▎▍▌▋▊▉█"[eighths - 1]! : "";
-			return padRight("█".repeat(whole) + partial, 6);
-		};
+		const bar = (share: number): string => this.shareBar(share, maximum);
 		return [
 			{ header: "Model", cells: rows.map((model) => model.model), align: "left", drop: 0 },
 			{ header: "Calls", cells: rows.map((model) => model.calls.toLocaleString("en-US")), align: "right", drop: 1, label: "calls" },