pi-extensions 0.1.27 → 0.1.29

package/files-widget/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this extension will be documented in this file.
 
+## [0.1.16] - 2026-04-19
+
+### Fixed
+- Let `/readfiles` browser search accept `j` and `k` as search text instead of hijacking them for navigation.
+- Fix viewer scrolling so the last lines of a file remain reachable.
+- Restore `G` / `Shift+G` navigation to jump to the bottom of the viewer.
+- Refresh an open viewer when the file changes on disk while `/readfiles` is open.
+- Accept pasted, multi-character, and chunked bracketed-paste input in browser search and the inline comment prompt.
+- Keep viewer search results in sync after live refreshes.
+- Pause live refresh while a line selection or inline comment is active so comments stay anchored to what the user selected.
+
 ## [0.1.14] - 2026-02-03
 
 ### Added

package/files-widget/browser.ts

@@ -22,7 +22,7 @@ import { buildFileTreeFromPaths, flattenTree, getIgnoredNames, sortChildren, upd
 import type { DiffStats, FileNode, FlatNode } from "./types";
 import { isIgnoredStatus, isUntrackedStatus } from "./utils";
 import { createViewer, type CommentPayload, type ViewerAction } from "./viewer";
-import { isPrintableChar } from "./input-utils";
+import { createTextInputBuffer } from "./input-utils";
 
 export interface BrowserController {
   render(width: number): string[];
@@ -219,6 +219,7 @@ export function createFileBrowser(
   const gitBranch = repo ? getGitBranch(cwd) : "";
 
   const viewer = createViewer(cwd, theme, requestComment);
+  const textInput = createTextInputBuffer();
 
   const root = repo
     ? buildFileTreeFromPaths(cwd, getGitFileList(cwd), gitStatus, diffStats, ignored, agentModifiedFiles)
@@ -794,8 +795,10 @@ export function createFileBrowser(
 
   function handleBrowserInput(data: string): void {
     const displayList = getDisplayList();
+    const maxIndex = Math.max(0, displayList.length - 1);
 
     if (matchesKey(data, "q") && !browser.searchMode) {
+      textInput.reset();
       stopBackgroundTasks();
       onClose();
       return;
@@ -804,7 +807,9 @@ export function createFileBrowser(
       if (browser.searchMode) {
         browser.searchMode = false;
         browser.searchQuery = "";
+        textInput.reset();
       } else {
+        textInput.reset();
         stopBackgroundTasks();
         onClose();
       }
@@ -813,29 +818,38 @@ export function createFileBrowser(
     if (matchesKey(data, "/") && !browser.searchMode) {
       browser.searchMode = true;
       browser.searchQuery = "";
-      return;
-    }
-    if (matchesKey(data, "j") || matchesKey(data, Key.down)) {
-      browser.selectedIndex = Math.min(displayList.length - 1, browser.selectedIndex + 1);
-      return;
-    }
-    if (matchesKey(data, "k") || matchesKey(data, Key.up)) {
-      browser.selectedIndex = Math.max(0, browser.selectedIndex - 1);
+      textInput.reset();
       return;
     }
     if (browser.searchMode) {
       if (matchesKey(data, Key.enter)) {
         browser.searchMode = false;
         browser.selectedIndex = 0;
+        textInput.reset();
       } else if (matchesKey(data, Key.backspace)) {
         browser.searchQuery = browser.searchQuery.slice(0, -1);
         browser.selectedIndex = 0;
-      } else if (isPrintableChar(data)) {
-        browser.searchQuery += data;
-        browser.selectedIndex = 0;
+      } else if (matchesKey(data, Key.down)) {
+        browser.selectedIndex = Math.min(maxIndex, browser.selectedIndex + 1);
+      } else if (matchesKey(data, Key.up)) {
+        browser.selectedIndex = Math.max(0, browser.selectedIndex - 1);
+      } else {
+        const text = textInput.push(data);
+        if (text) {
+          browser.searchQuery += text;
+          browser.selectedIndex = 0;
+        }
       }
       return;
     }
+    if (matchesKey(data, "j") || matchesKey(data, Key.down)) {
+      browser.selectedIndex = Math.min(maxIndex, browser.selectedIndex + 1);
+      return;
+    }
+    if (matchesKey(data, "k") || matchesKey(data, Key.up)) {
+      browser.selectedIndex = Math.max(0, browser.selectedIndex - 1);
+      return;
+    }
     if (matchesKey(data, Key.enter)) {
       const item = displayList[browser.selectedIndex];
       if (item) {
@@ -864,7 +878,7 @@ export function createFileBrowser(
       return;
     }
     if (matchesKey(data, Key.pageDown)) {
-      browser.selectedIndex = Math.min(displayList.length - 1, browser.selectedIndex + browser.browserHeight);
+      browser.selectedIndex = Math.min(maxIndex, browser.selectedIndex + browser.browserHeight);
       return;
     }
     if (matchesKey(data, Key.pageUp)) {

package/files-widget/constants.ts

@@ -14,5 +14,4 @@ export const MIN_PANEL_HEIGHT = 5;
 export const MAX_VIEWER_HEIGHT = 50;
 export const MAX_BROWSER_HEIGHT = 40;
 
-export const VIEWER_SCROLL_MARGIN = 10;
 export const SEARCH_SCROLL_OFFSET = 3;

package/files-widget/index.ts

@@ -66,7 +66,7 @@ export default function editorExtension(pi: ExtensionAPI): void {
     },
   });
 
-  pi.registerCommand("readfiles-review", {
+  pi.registerCommand("review", {
     description: "Open tuicr to review changes and send feedback to agent",
     handler: async (_args, ctx) => {
       if (!hasCommand("tuicr")) {
@@ -101,7 +101,7 @@ export default function editorExtension(pi: ExtensionAPI): void {
     },
   });
 
-  pi.registerCommand("readfiles-diff", {
+  pi.registerCommand("diff", {
     description: "Open critique to view diffs",
     handler: async (args, ctx) => {
       if (!hasCommand("bun")) {

package/files-widget/input-utils.ts

@@ -1,3 +1,87 @@
-export function isPrintableChar(data: string): boolean {
-  return data.length === 1 && data.charCodeAt(0) >= 32 && data.charCodeAt(0) < 127;
+import { decodeKittyPrintable } from "@mariozechner/pi-tui";
+
+const CONTROL_CHARS = /[\u0000-\u0008\u000B-\u001F\u007F]/g;
+const BRACKETED_PASTE_START = "\u001b[200~";
+const BRACKETED_PASTE_END = "\u001b[201~";
+
+function sanitizeTextInput(data: string): string {
+  const normalized = decodeKittyPrintable(data) ?? data;
+  if (!normalized || normalized.includes("\u001b")) {
+    return "";
+  }
+
+  return normalized
+    .replace(/\r\n?/g, "\n")
+    .replace(/\n/g, " ")
+    .replace(/\t/g, " ")
+    .replace(CONTROL_CHARS, "");
+}
+
+function getPendingStartSuffix(data: string): string {
+  const maxLength = BRACKETED_PASTE_START.length - 1;
+  for (let length = Math.min(data.length, maxLength); length > 0; length--) {
+    const suffix = data.slice(-length);
+    if (BRACKETED_PASTE_START.startsWith(suffix)) {
+      return suffix;
+    }
+  }
+  return "";
+}
+
+export interface TextInputBuffer {
+  push(data: string): string;
+  reset(): void;
+}
+
+export function createTextInputBuffer(): TextInputBuffer {
+  let isInPaste = false;
+  let pasteBuffer = "";
+  let pendingStart = "";
+
+  const push = (data: string): string => {
+    if (!data) {
+      return "";
+    }
+
+    const combined = pendingStart + data;
+    pendingStart = "";
+
+    if (!isInPaste) {
+      const startIndex = combined.indexOf(BRACKETED_PASTE_START);
+      if (startIndex === -1) {
+        const pendingSuffix = getPendingStartSuffix(combined);
+        const completeText = pendingSuffix ? combined.slice(0, combined.length - pendingSuffix.length) : combined;
+        pendingStart = pendingSuffix;
+        return sanitizeTextInput(completeText);
+      }
+
+      const beforePaste = combined.slice(0, startIndex);
+      const afterStart = combined.slice(startIndex + BRACKETED_PASTE_START.length);
+      isInPaste = true;
+      pasteBuffer = "";
+      return sanitizeTextInput(beforePaste) + push(afterStart);
+    }
+
+    pasteBuffer += combined;
+    const endIndex = pasteBuffer.indexOf(BRACKETED_PASTE_END);
+    if (endIndex === -1) {
+      return "";
+    }
+
+    const pastedText = pasteBuffer.slice(0, endIndex);
+    const remaining = pasteBuffer.slice(endIndex + BRACKETED_PASTE_END.length);
+    isInPaste = false;
+    pasteBuffer = "";
+
+    return sanitizeTextInput(pastedText) + push(remaining);
+  };
+
+  return {
+    push,
+    reset(): void {
+      isInPaste = false;
+      pasteBuffer = "";
+      pendingStart = "";
+    },
+  };
 }

package/files-widget/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmustier/pi-files-widget",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "In-terminal file browser and viewer for Pi.",
   "license": "MIT",
   "author": "Thomas Mustier",

package/files-widget/viewer.ts

@@ -1,6 +1,6 @@
 import type { Theme } from "@mariozechner/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { relative } from "node:path";
 
 import {
@@ -8,12 +8,11 @@ import {
   MAX_VIEWER_HEIGHT,
   MIN_PANEL_HEIGHT,
   SEARCH_SCROLL_OFFSET,
-  VIEWER_SCROLL_MARGIN,
 } from "./constants";
 import { loadFileContent } from "./file-viewer";
 import type { FileNode } from "./types";
 import { isUntrackedStatus } from "./utils";
-import { isPrintableChar } from "./input-utils";
+import { createTextInputBuffer } from "./input-utils";
 
 export interface CommentPayload {
   relPath: string;
@@ -43,6 +42,7 @@ interface ViewerState {
   searchMatches: number[];
   searchIndex: number;
   lastRenderWidth: number;
+  lastLoadedMtimeMs: number | null;
   height: number;
 }
 
@@ -61,6 +61,8 @@ export function createViewer(
   theme: Theme,
   requestComment: (payload: CommentPayload, comment: string) => void
 ): ViewerController {
+  const textInput = createTextInputBuffer();
+
   const state: ViewerState = {
     file: null,
     content: [],
@@ -75,6 +77,7 @@ export function createViewer(
     searchMatches: [],
     searchIndex: 0,
     lastRenderWidth: 0,
+    lastLoadedMtimeMs: null,
     height: DEFAULT_VIEWER_HEIGHT,
   };
 
@@ -94,6 +97,10 @@ export function createViewer(
   }
 
   function setMode(mode: ViewerMode): void {
+    if (mode !== state.mode) {
+      textInput.reset();
+    }
+
     state.mode = mode;
     if (mode !== "search") resetSearch();
     if (mode !== "comment") resetComment();
@@ -102,16 +109,59 @@ export function createViewer(
     }
   }
 
+  function getMaxScroll(): number {
+    return Math.max(0, state.content.length - state.height);
+  }
+
+  function refreshRawContent(): void {
+    if (!state.file) return;
+
+    try {
+      const fileStat = statSync(state.file.path);
+      state.rawContent = readFileSync(state.file.path, "utf-8");
+      state.file.lineCount = state.rawContent.split("\n").length;
+      state.lastLoadedMtimeMs = fileStat.mtimeMs;
+    } catch {
+      state.rawContent = "";
+      state.file.lineCount = undefined;
+      state.lastLoadedMtimeMs = null;
+    }
+  }
+
+  function hasFileChangedOnDisk(): boolean {
+    if (!state.file) return false;
+
+    try {
+      return state.lastLoadedMtimeMs === null || statSync(state.file.path).mtimeMs !== state.lastLoadedMtimeMs;
+    } catch {
+      return state.lastLoadedMtimeMs !== null;
+    }
+  }
+
+  function clampScroll(): void {
+    state.scroll = Math.min(getMaxScroll(), Math.max(0, state.scroll));
+  }
+
   function reloadContent(width: number): void {
     if (!state.file) return;
+    refreshRawContent();
     const hasChanges = !!state.file.gitStatus;
     state.content = loadFileContent(state.file.path, cwd, state.diffMode, hasChanges, width);
     state.lastRenderWidth = width;
+    clampScroll();
+    if (state.searchQuery) {
+      updateSearchMatches({ preserveActiveMatch: true });
+    }
   }
 
-  function updateSearchMatches(): void {
+  function updateSearchMatches(options: { preserveActiveMatch?: boolean } = {}): void {
+    const activeMatch = options.preserveActiveMatch ? state.searchMatches[state.searchIndex] : undefined;
+
     state.searchMatches = [];
-    if (!state.searchQuery) return;
+    if (!state.searchQuery) {
+      state.searchIndex = 0;
+      return;
+    }
 
     const q = state.searchQuery.toLowerCase();
     const rawLines = state.rawContent.split("\n");
@@ -120,11 +170,29 @@ export function createViewer(
         state.searchMatches.push(i);
       }
     }
-    state.searchIndex = 0;
 
-    if (state.searchMatches.length > 0) {
-      state.scroll = Math.max(0, state.searchMatches[0] - SEARCH_SCROLL_OFFSET);
+    if (state.searchMatches.length === 0) {
+      state.searchIndex = 0;
+      return;
     }
+
+    if (activeMatch === undefined) {
+      state.searchIndex = 0;
+    } else {
+      let nearestIndex = 0;
+      let nearestDistance = Number.POSITIVE_INFINITY;
+      for (let i = 0; i < state.searchMatches.length; i++) {
+        const distance = Math.abs(state.searchMatches[i] - activeMatch);
+        if (distance < nearestDistance) {
+          nearestDistance = distance;
+          nearestIndex = i;
+        }
+      }
+      state.searchIndex = nearestIndex;
+    }
+
+    state.scroll = Math.max(0, state.searchMatches[state.searchIndex] - SEARCH_SCROLL_OFFSET);
+    clampScroll();
   }
 
   function jumpToNextMatch(direction: 1 | -1): void {
@@ -133,6 +201,7 @@ export function createViewer(
     if (state.searchIndex < 0) state.searchIndex = state.searchMatches.length - 1;
     if (state.searchIndex >= state.searchMatches.length) state.searchIndex = 0;
     state.scroll = Math.max(0, state.searchMatches[state.searchIndex] - SEARCH_SCROLL_OFFSET);
+    clampScroll();
   }
 
   function buildCommentPayload(): CommentPayload | null {
@@ -242,14 +311,8 @@ export function createViewer(
       setMode("normal");
       state.content = [];
       state.lastRenderWidth = 0;
-
-      try {
-        state.rawContent = readFileSync(file.path, "utf-8");
-        file.lineCount = state.rawContent.split("\n").length;
-      } catch {
-        state.rawContent = "";
-        file.lineCount = undefined;
-      }
+      state.lastLoadedMtimeMs = null;
+      refreshRawContent();
     },
 
     updateFileRef(file: FileNode | null): void {
@@ -259,13 +322,16 @@ export function createViewer(
     close(): void {
       state.file = null;
       state.content = [];
+      state.rawContent = "";
+      state.lastLoadedMtimeMs = null;
       setMode("normal");
     },
 
     render(width: number): string[] {
       if (!state.file) return [];
 
-      if (state.lastRenderWidth !== width || state.content.length === 0) {
+      const shouldAutoRefresh = state.mode !== "select" && state.mode !== "comment";
+      if (state.lastRenderWidth !== width || state.content.length === 0 || (shouldAutoRefresh && hasFileChangedOnDisk())) {
         reloadContent(width);
       }
 
@@ -308,8 +374,11 @@ export function createViewer(
           setMode("normal");
         } else if (matchesKey(data, Key.backspace)) {
           state.commentText = state.commentText.slice(0, -1);
-        } else if (isPrintableChar(data)) {
-          state.commentText += data;
+        } else {
+          const text = textInput.push(data);
+          if (text) {
+            state.commentText += text;
+          }
         }
         return { type: "none" };
       }
@@ -322,9 +391,12 @@ export function createViewer(
         } else if (matchesKey(data, Key.backspace)) {
           state.searchQuery = state.searchQuery.slice(0, -1);
           updateSearchMatches();
-        } else if (isPrintableChar(data)) {
-          state.searchQuery += data;
-          updateSearchMatches();
+        } else {
+          const text = textInput.push(data);
+          if (text) {
+            state.searchQuery += text;
+            updateSearchMatches();
+          }
         }
         return { type: "none" };
       }
@@ -358,7 +430,7 @@ export function createViewer(
         if (state.mode === "select") {
           state.selectEnd = Math.min(state.content.length - 1, state.selectEnd + 1);
         } else {
-          state.scroll = Math.min(Math.max(0, state.content.length - VIEWER_SCROLL_MARGIN), state.scroll + 1);
+          state.scroll = Math.min(getMaxScroll(), state.scroll + 1);
         }
         return { type: "none" };
       }
@@ -371,7 +443,7 @@ export function createViewer(
         return { type: "none" };
       }
       if (matchesKey(data, Key.pageDown)) {
-        state.scroll = Math.min(Math.max(0, state.content.length - state.height), state.scroll + state.height);
+        state.scroll = Math.min(getMaxScroll(), state.scroll + state.height);
         return { type: "none" };
       }
       if (matchesKey(data, Key.pageUp)) {
@@ -382,16 +454,18 @@ export function createViewer(
         state.scroll = 0;
         return { type: "none" };
       }
-      if (matchesKey(data, "G")) {
-        state.scroll = Math.max(0, state.content.length - state.height);
+      if (matchesKey(data, "shift+g")) {
+        state.scroll = getMaxScroll();
         return { type: "none" };
       }
       if (matchesKey(data, "+") || matchesKey(data, "=")) {
         state.height = Math.min(MAX_VIEWER_HEIGHT, state.height + 5);
+        clampScroll();
         return { type: "none" };
       }
       if (matchesKey(data, "-") || matchesKey(data, "_")) {
         state.height = Math.max(MIN_PANEL_HEIGHT, state.height - 5);
+        clampScroll();
         return { type: "none" };
       }
       if (matchesKey(data, "d") && state.mode !== "select" && state.file.gitStatus && !isUntrackedStatus(state.file.gitStatus)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensions",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "license": "MIT",
   "private": false,
   "keywords": [

package/usage-extension/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.3.1 - 2026-04-19
+- **Cost-only insights.** The Insights view now weights every insight by recorded USD cost, with no tokens fallback. The headline question is now "What's contributing to your cost?" and every bullet reads "X% of your cost …". Periods with no recorded cost show an explicit empty state instead of silently switching unit.
+- **Long-running sessions use true lifetime.** The 8h+ insight now looks at each session's global lifetime across all session files, not just the span visible inside the selected period slice.
+- **Exact ±2 min parallel window.** The "4+ sessions in parallel" insight now uses a precise ±120000 ms two-pointer sweep instead of rounded minute buckets. A message at second 1 of minute M and another at second 59 of minute M+2 are correctly treated as ~178 s apart (outside the window).
+- **Empty states.** Insights view now distinguishes three cases: no usage recorded in the period, usage but no cost data, and usage with cost but no insights clearing the 1% threshold.
+- **Narrow-terminal compact hint is hidden in Insights mode** (it only applied to the table layout).
+- **"Cache miss" bullet relabelled** to "of your cost came from >100k-token uncached prompts" — same math, more accurate wording.
+- **Messages with missing/invalid timestamps are excluded** from the parallel-sessions sweep so that older/incomplete logs don't inflate the insight by collapsing into a single synthetic instant.
+
+## 0.3.0 - 2026-04-19
+- Add an **Insights** view to `/usage` (press `v` to toggle). Surfaces Claude-style narrative characteristics of your usage for the active time period:
+  - `X% of your usage was while 4+ sessions ran in parallel`
+  - `X% of your usage was at >150k context`
+  - `X% of your usage hit a >100k-token cache miss`
+  - `X% of your usage came from sessions active for 8+ hours`
+  - `X% of your usage came from your top 5 sessions`
+- Insights are weighted by cost when cost data is recorded, otherwise by tokens, with a small footer noting which basis is in use.
+- Insights are independent characteristics of usage (they overlap), not a breakdown — the view makes this explicit.
+
+## 0.2.1 - 2026-04-17
+- Add a one-line formula footer to the `/usage` dashboard (`Tokens = Input + Output + CacheWrite  ·  ↑In = Input + CacheWrite`)
+- README now calls out the 0.2.0 formula change explicitly under the columns table
+
 ## 0.2.0 - 2026-04-17
 - Include `cacheWrite` in the main `Tokens` total and in the `↑In` column so providers like Anthropic that report fresh prompt work under `cacheWrite` are no longer undercounted
 - Keep `cacheRead` out of `Tokens` so repeated cache hits do not swamp the dashboard

package/usage-extension/README.md

@@ -2,12 +2,12 @@
 
 A Pi extension that displays aggregated usage statistics across all sessions.
 
-![Usage Statistics Screenshot](screenshot.png)
+![Default table view of /usage](screenshot.png)
 
 ## Compatibility
 
 - **Pi version:** 0.42.4+
-- **Last updated:** 2026-04-17
+- **Last updated:** 2026-04-19 (0.3.1)
 
 ## Installation
 
@@ -55,6 +55,27 @@ In Pi, run:
 
 ## Features
 
+### Views
+
+`/usage` has two view modes, toggled 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%.
+
+![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.
+
+The insights currently shown:
+
+| Insight | Threshold |
+|---|---|
+| Parallel sessions | ≥ 4 sessions active within an exact ±2 min window |
+| Large context | `input + cacheRead + cacheWrite > 150k` |
+| Large uncached prompt | `input + cacheWrite > 100k` |
+| Long-running sessions | session lifetime ≥ 8 hours (global, not per-period slice) |
+| Top-session concentration | top 5 sessions by cost |
+
 ### Time Periods
 
 | Period | Definition |
@@ -83,6 +104,8 @@ Time periods are calculated in the local timezone where Pi runs. If you want to
 | **↓Out** | Output tokens *(dimmed)* |
 | **Cache** | Cache read + write tokens *(dimmed; informational)* |
 
+> **As of 0.2.0:** `Tokens = Input + Output + CacheWrite` and `↑In = Input + CacheWrite`. `CacheRead` stays out of `Tokens` so repeated cache hits don't swamp the dashboard. The dashboard itself shows a one-line footer reminder.
+
 On narrow terminals, `/usage` automatically switches to a compact table instead of overflowing the terminal. Hidden columns reappear as soon as you widen the terminal.
 
 ### Navigation
@@ -90,8 +113,9 @@ On narrow terminals, `/usage` automatically switches to a compact table instead
 | Key | Action |
 |-----|--------|
 | `Tab` / `←` `→` | Switch time period |
-| `↑` `↓` | Select provider |
-| `Enter` / `Space` | Expand/collapse provider to show models |
+| `↑` `↓` | Select provider *(table view)* |
+| `Enter` / `Space` | Expand/collapse provider to show models *(table view)* |
+| `v` | Toggle between Table and Insights view |
 | `q` / `Esc` | Close |
 
 ## Provider Notes

package/usage-extension/index.ts

@@ -45,9 +45,39 @@ interface TotalStats extends BaseStats {
 	sessions: number;
 }
 
+interface Insight {
+	percent: number; // 0-100
+	headline: string;
+	advice: string;
+}
+
+interface PeriodInsights {
+	insights: Insight[];
+}
+
+interface RawMessage {
+	sessionId: string;
+	timestamp: number;
+	cost: number;
+	input: number;
+	cacheRead: number;
+	cacheWrite: number;
+}
+
+interface PeriodRawData {
+	messages: RawMessage[];
+	sessionCosts: Map<string, number>;
+}
+
+interface GlobalSessionSpan {
+	startMs: number;
+	endMs: number;
+}
+
 interface TimeFilteredStats {
 	providers: Map<string, ProviderStats>;
 	totals: TotalStats;
+	insights: PeriodInsights;
 }
 
 interface UsageData {
@@ -58,6 +88,7 @@ interface UsageData {
 }
 
 type TabName = "today" | "thisWeek" | "lastWeek" | "allTime";
+type ViewMode = "table" | "insights";
 
 // =============================================================================
 // Column Configuration
@@ -296,9 +327,14 @@ function emptyTimeFilteredStats(): TimeFilteredStats {
 	return {
 		providers: new Map(),
 		totals: { sessions: 0, messages: 0, cost: 0, tokens: emptyTokens() },
+		insights: { insights: [] },
 	};
 }
 
+function emptyPeriodRawData(): PeriodRawData {
+	return { messages: [], sessionCosts: new Map() };
+}
+
 function emptyUsageData(): UsageData {
 	return {
 		today: emptyTimeFilteredStats(),
@@ -325,11 +361,25 @@ function addMessagesToUsageData(
 	messages: SessionMessage[],
 	todayMs: number,
 	weekStartMs: number,
-	lastWeekStartMs: number
+	lastWeekStartMs: number,
+	rawByPeriod: Record<TabName, PeriodRawData>,
+	globalSessionSpans: Map<string, GlobalSessionSpan>
 ): void {
 	const sessionContributed = { today: false, thisWeek: false, lastWeek: false, allTime: false };
 
 	for (const msg of messages) {
+		// Track real per-session lifetime across every message we see, regardless of
+		// which period the message falls into. Used later for the "8h+ session" insight.
+		if (msg.timestamp > 0) {
+			const span = globalSessionSpans.get(sessionId);
+			if (!span) {
+				globalSessionSpans.set(sessionId, { startMs: msg.timestamp, endMs: msg.timestamp });
+			} else {
+				if (msg.timestamp < span.startMs) span.startMs = msg.timestamp;
+				if (msg.timestamp > span.endMs) span.endMs = msg.timestamp;
+			}
+		}
+
 		const periods = getPeriodsForTimestamp(msg.timestamp, todayMs, weekStartMs, lastWeekStartMs);
 		const tokens = {
 			// Count fresh tokens processed this turn.
@@ -365,6 +415,17 @@ function addMessagesToUsageData(
 
 			accumulateStats(stats.totals, msg.cost, tokens);
 			sessionContributed[period] = true;
+
+			const raw = rawByPeriod[period];
+			raw.messages.push({
+				sessionId,
+				timestamp: msg.timestamp,
+				cost: msg.cost,
+				input: msg.input,
+				cacheRead: msg.cacheRead,
+				cacheWrite: msg.cacheWrite,
+			});
+			raw.sessionCosts.set(sessionId, (raw.sessionCosts.get(sessionId) ?? 0) + msg.cost);
 		}
 	}
 
@@ -393,6 +454,13 @@ async function collectUsageData(signal?: AbortSignal): Promise<UsageData | null>
 	const lastWeekStartMs = startOfLastWeek.getTime();
 
 	const data = emptyUsageData();
+	const rawByPeriod: Record<TabName, PeriodRawData> = {
+		today: emptyPeriodRawData(),
+		thisWeek: emptyPeriodRawData(),
+		lastWeek: emptyPeriodRawData(),
+		allTime: emptyPeriodRawData(),
+	};
+	const globalSessionSpans = new Map<string, GlobalSessionSpan>();
 
 	const sessionFiles = await getAllSessionFiles(signal);
 	if (signal?.aborted) return null;
@@ -404,14 +472,192 @@ async function collectUsageData(signal?: AbortSignal): Promise<UsageData | null>
 		if (signal?.aborted) return null;
 		if (!parsed) continue;
 
-		addMessagesToUsageData(data, parsed.sessionId, parsed.messages, todayMs, weekStartMs, lastWeekStartMs);
+		addMessagesToUsageData(
+			data,
+			parsed.sessionId,
+			parsed.messages,
+			todayMs,
+			weekStartMs,
+			lastWeekStartMs,
+			rawByPeriod,
+			globalSessionSpans
+		);
 
 		await new Promise<void>((resolve) => setImmediate(resolve));
 	}
 
+	// Classify sessions that are globally long-running once, then reuse across periods.
+	const longSessionIds = new Set<string>();
+	for (const [id, span] of globalSessionSpans) {
+		if (span.endMs - span.startMs >= LONG_SESSION_MS) longSessionIds.add(id);
+	}
+
+	for (const period of TAB_ORDER) {
+		data[period].insights = computeInsights(rawByPeriod[period], longSessionIds);
+	}
+
 	return data;
 }
 
+// =============================================================================
+// Insights
+// =============================================================================
+
+const PARALLEL_WINDOW_MS = 2 * 60_000; // exact ±N milliseconds around each message
+const PARALLEL_SESSION_THRESHOLD = 4;
+const LARGE_CONTEXT_THRESHOLD = 150_000;
+const LARGE_CACHE_MISS_THRESHOLD = 100_000;
+const LONG_SESSION_MS = 8 * 60 * 60 * 1000;
+const TOP_SESSION_COUNT = 5;
+const MIN_MESSAGES_FOR_PARALLEL_INSIGHT = 10;
+const MIN_PERCENT_TO_SHOW = 1;
+
+/**
+ * Insights are weighted by recorded API cost. Periods with zero total cost produce
+ * an empty `insights` list — the UI renders a distinct empty-state for that case.
+ * Long-running-session classification is passed in from a global pass so that a
+ * session's real lifetime is used rather than the slice visible inside this period.
+ */
+function computeInsights(raw: PeriodRawData, longSessionIds: Set<string>): PeriodInsights {
+	if (raw.messages.length === 0) {
+		return { insights: [] };
+	}
+
+	const total = raw.messages.reduce((sum, m) => sum + m.cost, 0);
+	if (total <= 0) {
+		return { insights: [] };
+	}
+
+	const candidates: Insight[] = [];
+
+	// 1. Parallel sessions — ≥ N unique sessions active within an exact ±W ms window.
+	const parallelWeight = computeParallelCostWeight(raw.messages);
+	if (parallelWeight !== null) {
+		candidates.push({
+			percent: (parallelWeight / total) * 100,
+			headline: `of your cost was while ${PARALLEL_SESSION_THRESHOLD}+ sessions ran in parallel`,
+			advice:
+				"All sessions share one rate limit. If you don't need them all at once, queueing uses capacity more evenly.",
+		});
+	}
+
+	// 2. Large context — input + cacheRead + cacheWrite > threshold.
+	const largeContextWeight = raw.messages
+		.filter((m) => m.input + m.cacheRead + m.cacheWrite > LARGE_CONTEXT_THRESHOLD)
+		.reduce((sum, m) => sum + m.cost, 0);
+	candidates.push({
+		percent: (largeContextWeight / total) * 100,
+		headline: `of your cost was at >${formatThresholdTokens(LARGE_CONTEXT_THRESHOLD)} context`,
+		advice:
+			"Longer sessions are more expensive even when cached. /compact mid-task, /clear when switching to new tasks.",
+	});
+
+	// 3. Large uncached prompt — fresh (non-cached) input > threshold, per the v0.2.0 formula.
+	const uncachedWeight = raw.messages
+		.filter((m) => m.input + m.cacheWrite > LARGE_CACHE_MISS_THRESHOLD)
+		.reduce((sum, m) => sum + m.cost, 0);
+	candidates.push({
+		percent: (uncachedWeight / total) * 100,
+		headline: `of your cost came from >${formatThresholdTokens(LARGE_CACHE_MISS_THRESHOLD)}-token uncached prompts`,
+		advice:
+			"Uncached input is expensive, and often happens when sending a message to a session that has gone idle. /compact before stepping away keeps the cold-start small.",
+	});
+
+	// 4. Long-running sessions — classification comes from the global pass so we use
+	//    true session lifetime, not just the span visible inside this period slice.
+	const longWeight = raw.messages
+		.filter((m) => longSessionIds.has(m.sessionId))
+		.reduce((sum, m) => sum + m.cost, 0);
+	if (longWeight > 0) {
+		candidates.push({
+			percent: (longWeight / total) * 100,
+			headline: `of your cost came from sessions active for ${LONG_SESSION_MS / 3_600_000}+ hours`,
+			advice:
+				"These are often background/loop sessions. Continuous usage can add up quickly so make sure it is intentional.",
+		});
+	}
+
+	// 5. Top-N session concentration.
+	if (raw.sessionCosts.size > TOP_SESSION_COUNT) {
+		const sortedSessions = Array.from(raw.sessionCosts.values()).sort((a, b) => b - a);
+		const topN = Math.min(TOP_SESSION_COUNT, sortedSessions.length);
+		const topWeight = sortedSessions.slice(0, topN).reduce((sum, c) => sum + c, 0);
+		candidates.push({
+			percent: (topWeight / total) * 100,
+			headline: `of your cost came from your top ${topN} session${topN === 1 ? "" : "s"}`,
+			advice:
+				"A small number of sessions drives most of your spend. The table view can help pinpoint which ones.",
+		});
+	}
+
+	const insights = candidates.filter((i) => i.percent >= MIN_PERCENT_TO_SHOW).sort((a, b) => b.percent - a.percent);
+	return { insights };
+}
+
+/**
+ * Two-pointer sweep of messages sorted by timestamp. For each message, count the
+ * number of distinct session IDs whose messages fall within an exact ± window.
+ * Returns the total cost attributable to moments when ≥ threshold sessions were
+ * active, or null if the period has too few sessions/messages to call it.
+ *
+ * Messages with missing/invalid timestamps (parsed as 0) are filtered out first —
+ * otherwise they would collapse into a single synthetic instant and inflate the
+ * parallel count on older or incomplete logs.
+ */
+function computeParallelCostWeight(messages: RawMessage[]): number | null {
+	const timed = messages.filter((m) => m.timestamp > 0);
+	if (timed.length < MIN_MESSAGES_FOR_PARALLEL_INSIGHT) return null;
+	const distinctSessions = new Set(timed.map((m) => m.sessionId));
+	if (distinctSessions.size < PARALLEL_SESSION_THRESHOLD) return null;
+
+	const sorted = timed.slice().sort((a, b) => a.timestamp - b.timestamp);
+	const sidCount = new Map<string, number>();
+	let uniqueCount = 0;
+	let left = 0;
+	let right = 0;
+	let parallelCost = 0;
+
+	for (let i = 0; i < sorted.length; i++) {
+		const current = sorted[i]!;
+		const high = current.timestamp + PARALLEL_WINDOW_MS;
+		const low = current.timestamp - PARALLEL_WINDOW_MS;
+
+		while (right < sorted.length && sorted[right]!.timestamp <= high) {
+			const sid = sorted[right]!.sessionId;
+			const next = (sidCount.get(sid) ?? 0) + 1;
+			sidCount.set(sid, next);
+			if (next === 1) uniqueCount++;
+			right++;
+		}
+		while (left < right && sorted[left]!.timestamp < low) {
+			const sid = sorted[left]!.sessionId;
+			const next = (sidCount.get(sid) ?? 0) - 1;
+			if (next === 0) {
+				sidCount.delete(sid);
+				uniqueCount--;
+			} else {
+				sidCount.set(sid, next);
+			}
+			left++;
+		}
+
+		if (uniqueCount >= PARALLEL_SESSION_THRESHOLD) parallelCost += current.cost;
+	}
+
+	return parallelCost;
+}
+
+function formatThresholdTokens(n: number): string {
+	if (n >= 1_000_000) return `${n / 1_000_000}M`;
+	if (n >= 1_000) return `${n / 1_000}k`;
+	return String(n);
+}
+
+function formatInsightPercent(p: number): string {
+	if (p >= 10) return `${Math.round(p)}%`;
+	return `${Math.round(p * 10) / 10}%`;
+}
+
 // =============================================================================
 // Formatting Helpers
 // =============================================================================
@@ -514,6 +760,7 @@ const TAB_ORDER: TabName[] = ["today", "thisWeek", "lastWeek", "allTime"];
 
 class UsageComponent {
 	private activeTab: TabName = "allTime";
+	private viewMode: ViewMode = "table";
 	private data: UsageData;
 	private selectedIndex = 0;
 	private expanded = new Set<string>();
@@ -544,6 +791,12 @@ class UsageComponent {
 			return;
 		}
 
+		if (matchesKey(data, "v")) {
+			this.viewMode = this.viewMode === "table" ? "insights" : "table";
+			this.requestRender();
+			return;
+		}
+
 		if (matchesKey(data, "tab") || matchesKey(data, "right")) {
 			const idx = TAB_ORDER.indexOf(this.activeTab);
 			this.activeTab = TAB_ORDER[(idx + 1) % TAB_ORDER.length]!;
@@ -554,17 +807,17 @@ class UsageComponent {
 			this.activeTab = TAB_ORDER[(idx - 1 + TAB_ORDER.length) % TAB_ORDER.length]!;
 			this.updateProviderOrder();
 			this.requestRender();
-		} else if (matchesKey(data, "up")) {
+		} else if (this.viewMode === "table" && matchesKey(data, "up")) {
 			if (this.selectedIndex > 0) {
 				this.selectedIndex--;
 				this.requestRender();
 			}
-		} else if (matchesKey(data, "down")) {
+		} else if (this.viewMode === "table" && matchesKey(data, "down")) {
 			if (this.selectedIndex < this.providerOrder.length - 1) {
 				this.selectedIndex++;
 				this.requestRender();
 			}
-		} else if (matchesKey(data, "enter") || matchesKey(data, "space")) {
+		} else if (this.viewMode === "table" && (matchesKey(data, "enter") || matchesKey(data, "space"))) {
 			const provider = this.providerOrder[this.selectedIndex];
 			if (provider) {
 				if (this.expanded.has(provider)) {
@@ -582,6 +835,18 @@ class UsageComponent {
 	// -------------------------------------------------------------------------
 
 	render(width: number): string[] {
+		if (this.viewMode === "insights") {
+			return clampLines(
+				[
+					...this.renderTitle(),
+					...this.renderTabs(width, getTableLayout(width)),
+					...this.renderInsights(width),
+					...this.renderHelp(width),
+				],
+				width
+			);
+		}
+
 		const layout = getTableLayout(width);
 		return clampLines(
 			[
@@ -590,6 +855,7 @@ class UsageComponent {
 				...this.renderHeader(layout),
 				...this.renderRows(layout),
 				...this.renderTotals(layout),
+				...this.renderFormulaNote(width),
 				...this.renderHelp(width),
 			],
 			width
@@ -598,7 +864,54 @@ class UsageComponent {
 
 	private renderTitle(): string[] {
 		const th = this.theme;
-		return [th.fg("accent", th.bold("Usage Statistics")), ""];
+		const label = this.viewMode === "insights" ? "Usage Insights" : "Usage Statistics";
+		return [th.fg("accent", th.bold(label)), ""];
+	}
+
+	private renderInsights(width: number): string[] {
+		const th = this.theme;
+		const stats = this.data[this.activeTab];
+		const { insights } = stats.insights;
+		const hasMessages = stats.totals.messages > 0;
+		const hasCost = stats.totals.cost > 0;
+		const lines: string[] = [];
+
+		lines.push("What's contributing to your cost?");
+		lines.push(th.fg("dim", "Approximate, based on local sessions on this machine."));
+		lines.push("");
+		const note = `${TAB_LABELS[this.activeTab]} · weighted by cost (USD) · these overlap and can sum to >100%`;
+		lines.push(th.fg("dim", note));
+		lines.push("");
+
+		if (!hasMessages) {
+			lines.push(th.fg("dim", "  No usage recorded for this period."));
+			lines.push("");
+			return lines;
+		}
+		if (!hasCost) {
+			lines.push(th.fg("dim", "  No cost data recorded for this period."));
+			lines.push("");
+			return lines;
+		}
+		if (insights.length === 0) {
+			lines.push(th.fg("dim", "  No insights above 1% for this period."));
+			lines.push("");
+			return lines;
+		}
+
+		const indent = "     ";
+		const adviceWidth = Math.max(width - indent.length, 30);
+
+		for (const insight of insights) {
+			const pct = th.fg("accent", th.bold(formatInsightPercent(insight.percent)));
+			lines.push(`${pct} ${insight.headline}`);
+			for (const wrapped of wrapTextWithAnsi(insight.advice, adviceWidth)) {
+				lines.push(`${indent}${th.fg("dim", wrapped)}`);
+			}
+			lines.push("");
+		}
+
+		return lines;
 	}
 
 	private renderTabs(width: number, layout: TableLayout): string[] {
@@ -615,9 +928,11 @@ class UsageComponent {
 			activeTabOnly,
 		]);
 
-		const infoLines = layout.compact
-			? wrapTextWithAnsi(th.fg("dim", "Compact view. Widen the terminal for more columns."), Math.max(width, 1))
-			: [];
+		// Compact-note only applies to the table view — it's meaningless for insights.
+		const infoLines =
+			this.viewMode === "table" && layout.compact
+				? wrapTextWithAnsi(th.fg("dim", "Compact view. Widen the terminal for more columns."), Math.max(width, 1))
+				: [];
 
 		return [tabLine, ...infoLines, ""];
 	}
@@ -711,14 +1026,34 @@ class UsageComponent {
 		return [th.fg("border", "─".repeat(layout.tableWidth)), totalRow, ""];
 	}
 
-	private renderHelp(width: number): string[] {
+	private renderFormulaNote(width: number): string[] {
 		const line = pickFittingText(width, [
-			"[Tab/←→] period  [↑↓] select  [Enter] expand  [q] close",
-			"[Tab] period  [↑↓] select  [Enter] expand  [q] close",
-			"[↑↓] select  [Enter] expand  [q] close",
-			"[↑↓] select  [q] close",
-			"[q] close",
+			"Tokens = Input + Output + CacheWrite  ·  ↑In = Input + CacheWrite  (as of 0.2.0)",
+			"Tokens = In + Out + CacheWrite  ·  ↑In = In + CacheWrite  (v0.2.0+)",
+			"Tokens & ↑In include CacheWrite (v0.2.0+)",
+			"Incl. CacheWrite (v0.2.0+)",
 		]);
+		return [this.theme.fg("dim", line), ""];
+	}
+
+	private renderHelp(width: number): string[] {
+		const variants =
+			this.viewMode === "insights"
+				? [
+						"[Tab/←→] period  [v] table view  [q] close",
+						"[Tab] period  [v] table  [q] close",
+						"[v] table  [q] close",
+						"[q] close",
+				  ]
+				: [
+						"[Tab/←→] period  [↑↓] select  [Enter] expand  [v] insights  [q] close",
+						"[Tab] period  [↑↓] select  [Enter] expand  [v] insights  [q] close",
+						"[↑↓] select  [Enter] expand  [v] insights  [q] close",
+						"[↑↓] select  [v] insights  [q] close",
+						"[↑↓] select  [q] close",
+						"[q] close",
+				  ];
+		const line = pickFittingText(width, variants);
 		return [this.theme.fg("dim", line)];
 	}
 

package/usage-extension/package.json

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