@brimveyn/aimux 1.22.10 → 1.22.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.22.10",
+  "version": "1.22.11",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode, Kimi side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",

package/src/index.tsx

@@ -51,6 +51,13 @@ if (command === 'update') {
   process.exit(await runUpdate())
 }
 
+// Spawned detached by `maybeSpawnUsageRollup` below. Walks hundreds of MB of
+// assistant JSONL, so it gets its own process and never shares one with the UI.
+if (command === 'usage-rollup') {
+  const { runUsageRollup } = await import('./services/usage-history/rollup')
+  process.exit(await runUsageRollup())
+}
+
 const { logDebug } = await import('./debug/input-log')
 const { getRuntimeProfile } = await import('./daemon/runtime-paths')
 const runtimeProfile = getRuntimeProfile()
@@ -87,6 +94,7 @@ const [
   { setHostPalette },
   { createSessionBackend },
   { maybeAutoInstallCompletion },
+  { maybeSpawnUsageRollup },
 ] = await Promise.all([
   import('@opentui/react'),
   import('./app'),
@@ -95,6 +103,7 @@ const [
   import('./ui/host-palette'),
   import('./session-backend/bootstrap'),
   import('./cli/completion/install'),
+  import('./services/usage-history/store'),
 ])
 const { resolved: resolvedConfig, user: userConfig } = await loadUserConfig()
 
@@ -104,6 +113,12 @@ const { resolved: resolvedConfig, user: userConfig } = await loadUserConfig()
 // AIMUX_NO_COMPLETION_INSTALL=1; `aimux doctor` reports what landed where.
 maybeAutoInstallCompletion()
 
+// Snapshot today's AI usage before Claude Code prunes the transcripts it came
+// from — roughly a month survives on disk, so the aggregates aimux keeps are
+// the only long-term record. Detached subprocess, at most once per ~day, never
+// blocking. Opt out with AIMUX_NO_USAGE_ROLLUP=1.
+maybeSpawnUsageRollup()
+
 const renderer = await createCliRenderer({
   autoFocus: true,
   // Transparent clear color so cells untouched by BoxRenderable paints (e.g.

package/src/integrations/claude-hooks-install.ts

@@ -6,11 +6,11 @@
 // Hooks reference: https://code.claude.com/docs/en/hooks.md
 
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
-import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import { logDebug } from '../debug/input-log'
+import { claudeHome } from '../platform/assistant-home'
 
 const HOOK_EVENTS = [
   'UserPromptSubmit',
@@ -34,12 +34,8 @@ interface HookGroupEntry {
   hooks: HookCommandEntry[]
 }
 
-function claudeDir(): string {
-  return join(homedir(), '.claude')
-}
-
 function settingsFilePath(): string {
-  return join(claudeDir(), 'settings.json')
+  return join(claudeHome(), 'settings.json')
 }
 
 function writeAtomic(target: string, contents: string): void {
@@ -180,7 +176,7 @@ export function ensureClaudeSettingsHooks(): boolean {
   parsed.hooks = nextHooks
 
   try {
-    mkdirSync(claudeDir(), { recursive: true })
+    mkdirSync(claudeHome(), { recursive: true })
     writeAtomic(target, `${JSON.stringify(parsed, null, 2)}\n`)
     logDebug('claude-hooks-install:wrote', { events: HOOK_EVENTS, path: target, scriptPath })
     return true

package/src/integrations/claude-theme-sync.ts

@@ -12,24 +12,20 @@ import {
   type ThemeMode,
 } from '@brimveyn/aimux-config'
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
-import { homedir } from 'node:os'
 import { join } from 'node:path'
 
 import { logDebug } from '../debug/input-log'
+import { claudeHome } from '../platform/assistant-home'
 
 const THEME_SLUG = 'aimux'
 const THEME_PREF_VALUE = `custom:${THEME_SLUG}`
 
-function claudeDir(): string {
-  return join(homedir(), '.claude')
-}
-
 function themeFilePath(): string {
-  return join(claudeDir(), 'themes', `${THEME_SLUG}.json`)
+  return join(claudeHome(), 'themes', `${THEME_SLUG}.json`)
 }
 
 function settingsFilePath(): string {
-  return join(claudeDir(), 'settings.json')
+  return join(claudeHome(), 'settings.json')
 }
 
 function writeAtomic(target: string, contents: string): void {
@@ -67,7 +63,7 @@ export function syncClaudeTheme(resolved: ResolvedTuiTheme, mode: ThemeMode): vo
 
   const target = themeFilePath()
   try {
-    mkdirSync(join(claudeDir(), 'themes'), { recursive: true })
+    mkdirSync(join(claudeHome(), 'themes'), { recursive: true })
     writeAtomic(target, `${JSON.stringify(theme, null, 2)}\n`)
   } catch (error) {
     logSyncWarn('write-failed', { err: String(error), path: target })
@@ -110,7 +106,7 @@ export function ensureClaudeSettingsThemePref(): void {
   parsed.theme = THEME_PREF_VALUE
 
   try {
-    mkdirSync(claudeDir(), { recursive: true })
+    mkdirSync(claudeHome(), { recursive: true })
     writeAtomic(target, `${JSON.stringify(parsed, null, 2)}\n`)
   } catch (error) {
     logSyncWarn('settings-write-failed', { err: String(error), path: target })

package/src/platform/assistant-home.ts

@@ -0,0 +1,25 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/**
+ * Where each assistant CLI keeps its state.
+ *
+ * Both relocate wholesale through an environment variable, so anything reading
+ * or writing inside those directories has to go through here — three hand-rolled
+ * copies of `join(homedir(), '.claude')` used to disagree about whether
+ * `CLAUDE_CONFIG_DIR` existed, which sent the hook installer and the theme sync
+ * to a directory Claude Code was not reading.
+ */
+function envHome(variable: string, fallback: string): string {
+  const value = process.env[variable]?.trim()
+  if (value != null && value !== '') return value
+  return join(homedir(), fallback)
+}
+
+export function claudeHome(): string {
+  return envHome('CLAUDE_CONFIG_DIR', '.claude')
+}
+
+export function codexHome(): string {
+  return envHome('CODEX_HOME', '.codex')
+}

package/src/platform/daemon-control.ts

@@ -61,14 +61,23 @@ async function waitForSocket(socketPath: string): Promise<boolean> {
   return false
 }
 
-async function spawnDetachedProcess(command: 'daemon' | 'terminal-manager', socketPath: string) {
+/**
+ * Re-run this same aimux with another subcommand, detached and unwatched.
+ *
+ * The entrypoint is resolved from this module rather than `process.argv`, which
+ * points at whatever wrapper or shim launched us.
+ */
+export function spawnDetachedCommand(command: string): void {
   Bun.spawn([process.execPath, 'run', ENTRY_POINT, command], {
     detached: true,
     stderr: 'ignore',
     stdin: 'ignore',
     stdout: 'ignore',
   }).unref()
+}
 
+async function spawnDetachedProcess(command: 'daemon' | 'terminal-manager', socketPath: string) {
+  spawnDetachedCommand(command)
   return waitForSocket(socketPath)
 }
 

package/src/services/ai-usage/adapters/claude.ts

@@ -1,11 +1,11 @@
 import type { AIUsageToolConfig } from '@brimveyn/aimux-config'
 
 import { readFile } from 'node:fs/promises'
-import { homedir } from 'node:os'
 import { join } from 'node:path'
 
 import type { UsageSnapshot, UsageWindow, UsageWindowKind } from '../types'
 
+import { claudeHome } from '../../../platform/assistant-home'
 import { computePace, formatTimeRemaining } from '../pace'
 import { runCli } from '../spawn'
 
@@ -81,15 +81,9 @@ function planTierFromPayload(payload: ClaudeCredentialsPayload): string | null {
   return null
 }
 
-function claudeConfigDir(): string {
-  const env = process.env.CLAUDE_CONFIG_DIR?.trim()
-  if (env != null && env !== '') return env
-  return join(homedir(), '.claude')
-}
-
 async function readCredsFromFile(): Promise<string | null> {
   try {
-    const raw = await readFile(join(claudeConfigDir(), '.credentials.json'), 'utf8')
+    const raw = await readFile(join(claudeHome(), '.credentials.json'), 'utf8')
     return raw.trim() || null
   } catch {
     return null

package/src/services/ai-usage/adapters/codex.ts

@@ -1,11 +1,11 @@
 import type { AIUsageToolConfig } from '@brimveyn/aimux-config'
 
 import { readFile } from 'node:fs/promises'
-import { homedir } from 'node:os'
 import { join } from 'node:path'
 
 import type { UsageSnapshot, UsageWindow, UsageWindowKind } from '../types'
 
+import { codexHome } from '../../../platform/assistant-home'
 import { computePace, formatTimeRemaining } from '../pace'
 
 interface CodexAuthFile {
@@ -38,12 +38,6 @@ const DEFAULT_CHATGPT_BASE = 'https://chatgpt.com/backend-api'
 const USAGE_PATH = '/wham/usage'
 const AUTH_TIMEOUT_MS = 15_000
 
-function codexHome(): string {
-  const env = process.env.CODEX_HOME?.trim()
-  if (env != null && env !== '') return env
-  return join(homedir(), '.codex')
-}
-
 function parseChatGPTBaseFromConfig(contents: string): string | null {
   for (const rawLine of contents.split(/\r?\n/)) {
     const line = rawLine.split('#', 1)[0]?.trim() ?? ''

package/src/services/usage-history/rollup.ts

@@ -0,0 +1,278 @@
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { logDebug } from '../../debug/input-log'
+import { claudeHome, codexHome } from '../../platform/assistant-home'
+import {
+  emptyDay,
+  localDay,
+  saveUsageHistory,
+  type UsageDay,
+  type UsageDays,
+  type UsageTools,
+} from './store'
+
+/**
+ * Rebuilds the usage aggregates from what the assistants still have on disk.
+ *
+ * Its own process (`aimux usage-rollup`). Nothing here may be imported from the
+ * startup path: it walks hundreds of megabytes of JSONL.
+ */
+
+const FILE_CONCURRENCY = 8
+
+function dayAt(days: UsageDays, date: string): UsageDay {
+  const existing = days[date]
+  if (existing !== undefined) return existing
+  const created = emptyDay()
+  days[date] = created
+  return created
+}
+
+function bump(counts: Record<string, number>, key: string, amount: number): void {
+  counts[key] = (counts[key] ?? 0) + amount
+}
+
+/** Streamed: the largest transcript here is ~90 MB, which `Bun.file().text()` would materialize whole. */
+export async function readJsonlLines(path: string, onLine: (line: string) => void): Promise<void> {
+  const decoder = new TextDecoder()
+  let carry = ''
+
+  for await (const chunk of Bun.file(path).stream()) {
+    // `stream: true` holds back a partial UTF-8 sequence at the chunk edge
+    // instead of replacing it with U+FFFD and corrupting the line.
+    const parts = (carry + decoder.decode(chunk, { stream: true })).split('\n')
+    carry = parts.pop() ?? ''
+    for (const line of parts) onLine(line)
+  }
+
+  carry += decoder.decode()
+  // No trailing newline, or a file being appended to right now — the half-written
+  // last line just fails JSON.parse downstream.
+  if (carry !== '') onLine(carry)
+}
+
+function findJsonl(root: string): string[] {
+  try {
+    // Recursive: transcripts nest at varying depths and a flat readdir misses half.
+    return readdirSync(root, { recursive: true })
+      .filter((entry): entry is string => typeof entry === 'string' && entry.endsWith('.jsonl'))
+      .map((entry) => join(root, entry))
+  } catch {
+    return [] // assistant not installed on this machine
+  }
+}
+
+async function forEachFile(paths: string[], run: (path: string) => Promise<void>): Promise<void> {
+  let cursor = 0
+  // `cursor++` needs no lock: no await between read and increment, single thread.
+  const workers = Array.from({ length: Math.min(FILE_CONCURRENCY, paths.length) }, async () => {
+    while (cursor < paths.length) {
+      const path = paths[cursor++]
+      if (path === undefined) return
+      try {
+        await run(path)
+      } catch {
+        // One unreadable transcript must never sink the whole rollup.
+      }
+    }
+  })
+  await Promise.all(workers)
+}
+
+interface TranscriptUsage {
+  cache_creation_input_tokens?: number
+  cache_read_input_tokens?: number
+  input_tokens?: number
+  output_tokens?: number
+}
+
+interface TranscriptLine {
+  gitBranch?: string
+  message?: { id?: string; model?: string; usage?: TranscriptUsage }
+  requestId?: string
+  timestamp?: string
+}
+
+/** `seen` spans the whole run: resume, fork and compaction re-emit the same billed request across files. */
+export function consumeTranscriptLine(line: string, seen: Set<string>, days: UsageDays): void {
+  // ~23k of ~126k lines carry usage; the rest hold base64 thinking blobs. A
+  // substring test beats parsing them.
+  if (!line.includes('"output_tokens"')) return
+
+  let entry: TranscriptLine
+  try {
+    entry = JSON.parse(line) as TranscriptLine
+  } catch {
+    return
+  }
+
+  const usage = entry.message?.usage
+  if (usage === undefined || entry.timestamp == null) return
+
+  // Placeholder messages (API errors, interrupted turns) carry junk usage.
+  const model = entry.message?.model
+  if (model === '<synthetic>') return
+
+  const id = entry.message?.id
+  const { requestId } = entry
+  // Both halves or nothing: without an id a duplicate cannot be proven, and
+  // undercounting a stats page is worse than a rare double.
+  if (id != null && id !== '' && requestId != null && requestId !== '') {
+    const key = `${id}:${requestId}`
+    if (seen.has(key)) return
+    seen.add(key)
+  }
+
+  const ms = Date.parse(entry.timestamp)
+  if (!Number.isFinite(ms)) return
+
+  const cacheRead = usage.cache_read_input_tokens ?? 0
+  const cacheWrite = usage.cache_creation_input_tokens ?? 0
+  const input = usage.input_tokens ?? 0
+  const output = usage.output_tokens ?? 0
+  const total = input + output + cacheRead + cacheWrite
+  if (total <= 0) return
+
+  const day = dayAt(days, localDay(new Date(ms)))
+  day.tokens.cacheRead += cacheRead
+  day.tokens.cacheWrite += cacheWrite
+  day.tokens.input += input
+  day.tokens.output += output
+  day.tokens.total += total
+
+  if (model != null && model !== '') bump(day.models, model, total)
+  const branch = entry.gitBranch
+  if (branch != null && branch !== '') bump(day.branches, branch, total)
+}
+
+/** `history.jsonl`, the prompt log — the only source that survives transcript pruning. */
+export function consumeHistoryLine(line: string, days: UsageDays): void {
+  if (!line.includes('"timestamp"')) return
+
+  let entry: { timestamp?: number | string }
+  try {
+    entry = JSON.parse(line) as { timestamp?: number | string }
+  } catch {
+    return
+  }
+
+  // A number today, quoted in past releases. `Number()` covers both, where
+  // `new Date(quoted)` returns Invalid Date and drops the entry.
+  const ms = Number(entry.timestamp)
+  if (!Number.isFinite(ms) || ms <= 0) return
+
+  dayAt(days, localDay(new Date(ms))).prompts += 1
+}
+
+interface CodexLine {
+  payload?: {
+    info?: {
+      last_token_usage?: {
+        cached_input_tokens?: number
+        input_tokens?: number
+        output_tokens?: number
+        total_tokens?: number
+      }
+    }
+    model?: string
+  }
+  timestamp?: string
+}
+
+export interface CodexFileState {
+  model: string | null
+}
+
+/** `last_token_usage` is the per-turn delta; the sibling `total_token_usage` is cumulative — summing it overcounts by n²/2. */
+export function consumeCodexLine(line: string, state: CodexFileState, days: UsageDays): void {
+  if (!line.includes('"model"') && !line.includes('"last_token_usage"')) return
+
+  let entry: CodexLine
+  try {
+    entry = JSON.parse(line) as CodexLine
+  } catch {
+    return
+  }
+
+  const model = entry.payload?.model
+  if (model != null && model !== '') state.model = model
+
+  const usage = entry.payload?.info?.last_token_usage
+  if (usage === undefined || entry.timestamp == null) return
+
+  const ms = Date.parse(entry.timestamp)
+  if (!Number.isFinite(ms)) return
+
+  const cacheRead = usage.cached_input_tokens ?? 0
+  const total = usage.total_tokens ?? 0
+  if (total <= 0) return
+
+  const day = dayAt(days, localDay(new Date(ms)))
+  day.tokens.cacheRead += cacheRead
+  // cached_input_tokens ⊂ input_tokens, so the cached share is subtracted not added.
+  day.tokens.input += Math.max(0, (usage.input_tokens ?? 0) - cacheRead)
+  day.tokens.output += usage.output_tokens ?? 0
+  day.tokens.total += total
+
+  if (state.model != null && state.model !== '') bump(day.models, state.model, total)
+}
+
+async function collectClaude(): Promise<UsageDays> {
+  const days: UsageDays = {}
+  const seen = new Set<string>()
+  const root = claudeHome()
+
+  await forEachFile(findJsonl(join(root, 'projects')), async (path) => {
+    await readJsonlLines(path, (line) => {
+      consumeTranscriptLine(line, seen, days)
+    })
+  })
+
+  try {
+    await readJsonlLines(join(root, 'history.jsonl'), (line) => {
+      consumeHistoryLine(line, days)
+    })
+  } catch {
+    // No prompt log: the heatmap falls back to whatever the transcripts cover.
+  }
+
+  return days
+}
+
+async function collectCodex(): Promise<UsageDays> {
+  const days: UsageDays = {}
+
+  await forEachFile(findJsonl(join(codexHome(), 'sessions')), async (path) => {
+    const state: CodexFileState = { model: null }
+    await readJsonlLines(path, (line) => {
+      consumeCodexLine(line, state, days)
+    })
+  })
+
+  return days
+}
+
+export async function runUsageRollup(): Promise<number> {
+  try {
+    const [claude, codex] = await Promise.all([collectClaude(), collectCodex()])
+
+    const fresh: UsageTools = {}
+    if (Object.keys(claude).length > 0) fresh.claude = claude
+    if (Object.keys(codex).length > 0) fresh.codex = codex
+
+    // Nothing parsed means every source was missing. Writing would bump the
+    // mtime, which schedules the next run, and buy a day of not retrying.
+    if (Object.keys(fresh).length === 0) {
+      logDebug('usageHistory.rollupEmpty', {})
+      return 1
+    }
+
+    return saveUsageHistory(fresh) ? 0 : 1
+  } catch (error) {
+    logDebug('usageHistory.rollupError', {
+      error: error instanceof Error ? error.message : String(error),
+    })
+    return 1
+  }
+}

package/src/services/usage-history/stats.ts

@@ -0,0 +1,193 @@
+import { parseColor, RGBA } from '@opentui/core'
+
+import { emptyTokens, localDay, type UsageDays, type UsageTokens } from './store'
+
+/** Pure shaping of stored usage days into what the History page renders. */
+
+export interface HeatmapCell {
+  /** 'YYYY-MM-DD', or '' for a cell outside the covered range. */
+  day: string
+  level: number
+  value: number
+}
+
+function parseDay(key: string): Date {
+  const [year, month, day] = key.split('-').map(Number)
+  return new Date(year ?? 0, (month ?? 1) - 1, day ?? 1)
+}
+
+/** Whole days apart. Via `Date.UTC` on the calendar parts: a DST span is not a whole number of 24h periods. */
+function daysBetween(from: Date, to: Date): number {
+  const utcOf = (date: Date): number =>
+    Date.UTC(date.getFullYear(), date.getMonth(), date.getDate())
+  return Math.round((utcOf(to) - utcOf(from)) / 86_400_000)
+}
+
+/** Quartiles of the non-empty days: a linear `value / max` ramp lets one outlier flatten the year to level 1. */
+export function cutPoints(values: number[]): [number, number, number] {
+  const sorted = values.filter((value) => value > 0).sort((left, right) => left - right)
+  const at = (quantile: number): number =>
+    sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * quantile))] ?? 0
+  return [at(0.25), at(0.5), at(0.75)]
+}
+
+function levelOf(value: number, cuts: [number, number, number]): number {
+  if (value <= 0) return 0
+  if (value <= cuts[0]) return 1
+  if (value <= cuts[1]) return 2
+  if (value <= cuts[2]) return 3
+  return 4
+}
+
+/** Week columns needed to cover what is recorded, so the grid does not open on empty months. */
+export function coveredWeeks(days: UsageDays, today: Date, maxWeeks: number): number {
+  const dates = Object.keys(days).sort()
+  const first = dates[0]
+  if (first === undefined) return Math.min(maxWeeks, 12)
+  const elapsed = daysBetween(parseDay(first), today)
+  return Math.max(4, Math.min(maxWeeks, Math.ceil((elapsed + 1) / 7) + 1))
+}
+
+/** 7 rows (Monday first) by `weeks` columns, oldest left. Cells after today come back empty. */
+export function buildHeatmap(
+  counts: Record<string, number>,
+  weeks: number,
+  today: Date
+): HeatmapCell[][] {
+  const cuts = cutPoints(Object.values(counts))
+
+  // Anchored on the Sunday closing this week, so the last column is the week in progress.
+  const mondayIndex = (today.getDay() + 6) % 7
+  const end = new Date(today.getFullYear(), today.getMonth(), today.getDate() + (6 - mondayIndex))
+  // Calendar arithmetic, never `getTime() - n * DAY_MS`: across a DST change the
+  // millisecond form lands on 23:00 the day before and rotates every row by one.
+  const start = new Date(end.getFullYear(), end.getMonth(), end.getDate() - (weeks * 7 - 1))
+  const todayKey = localDay(today)
+
+  const rows: HeatmapCell[][] = []
+  for (let row = 0; row < 7; row++) {
+    const cells: HeatmapCell[] = []
+    for (let column = 0; column < weeks; column++) {
+      const date = new Date(
+        start.getFullYear(),
+        start.getMonth(),
+        start.getDate() + column * 7 + row
+      )
+      const key = localDay(date)
+      if (key > todayKey) {
+        cells.push({ day: '', level: 0, value: 0 })
+        continue
+      }
+      const value = counts[key] ?? 0
+      cells.push({ day: key, level: levelOf(value, cuts), value })
+    }
+    rows.push(cells)
+  }
+  return rows
+}
+
+/** Month initial over each column that opens a month. `cellWidth` mirrors the grid's own. */
+export function monthRuler(grid: HeatmapCell[][], weeks: number, cellWidth: number): string {
+  const initials = 'JFMAMJJASOND'
+  const chars: string[] = Array.from({ length: weeks * cellWidth }, () => ' ')
+  let previous = ''
+  for (let column = 0; column < weeks; column++) {
+    const day = grid[0]?.[column]?.day
+    if (day == null || day === '') continue
+    const month = day.slice(5, 7)
+    if (month !== previous) {
+      chars[column * cellWidth] = initials[Number(month) - 1] ?? ' '
+      previous = month
+    }
+  }
+  return chars.join('')
+}
+
+export function promptCounts(days: UsageDays): Record<string, number> {
+  const counts: Record<string, number> = {}
+  for (const [date, day] of Object.entries(days)) counts[date] = day.prompts
+  return counts
+}
+
+export interface UsageSummary {
+  branches: [string, number][]
+  /** Denominator for branch shares — branch-less entries are excluded. */
+  branchTotal: number
+  models: [string, number][]
+  modelTotal: number
+  peakPrompts: number
+  promptDays: number
+  /** Days carrying token data — a shorter span than `promptDays` once pruning starts. */
+  tokenDays: number
+  tokens: UsageTokens
+  totalPrompts: number
+}
+
+function rank(totals: Record<string, number>): { entries: [string, number][]; total: number } {
+  const entries = Object.entries(totals)
+  entries.sort((left, right) => right[1] - left[1])
+  let total = 0
+  for (const [, value] of entries) total += value
+  return { entries, total }
+}
+
+export function summarizeDays(days: UsageDays, limit = 6): UsageSummary {
+  const tokens = emptyTokens()
+  const models: Record<string, number> = {}
+  const branches: Record<string, number> = {}
+  let peakPrompts = 0
+  let promptDays = 0
+  let tokenDays = 0
+  let totalPrompts = 0
+
+  for (const day of Object.values(days)) {
+    tokens.cacheRead += day.tokens.cacheRead
+    tokens.cacheWrite += day.tokens.cacheWrite
+    tokens.input += day.tokens.input
+    tokens.output += day.tokens.output
+    tokens.total += day.tokens.total
+
+    if (day.tokens.total > 0) tokenDays += 1
+    if (day.prompts > 0) {
+      promptDays += 1
+      totalPrompts += day.prompts
+      if (day.prompts > peakPrompts) peakPrompts = day.prompts
+    }
+
+    for (const [model, count] of Object.entries(day.models)) {
+      models[model] = (models[model] ?? 0) + count
+    }
+    for (const [branch, count] of Object.entries(day.branches)) {
+      branches[branch] = (branches[branch] ?? 0) + count
+    }
+  }
+
+  const rankedModels = rank(models)
+  const rankedBranches = rank(branches)
+
+  return {
+    branches: rankedBranches.entries.slice(0, limit),
+    branchTotal: rankedBranches.total,
+    models: rankedModels.entries.slice(0, limit),
+    modelTotal: rankedModels.total,
+    peakPrompts,
+    promptDays,
+    tokenDays,
+    tokens,
+    totalPrompts,
+  }
+}
+
+/** Blends two theme colours: the palette is flat, so the five-step ramp has to be derived per theme. */
+export function mixColor(from: string, to: string, ratio: number): RGBA {
+  const start = parseColor(from)
+  const end = parseColor(to)
+  // A transparent anchor would fade the whole ramp out; keep the target instead.
+  if (start.a === 0) return end
+  return RGBA.fromValues(
+    start.r + (end.r - start.r) * ratio,
+    start.g + (end.g - start.g) * ratio,
+    start.b + (end.b - start.b) * ratio,
+    1
+  )
+}

package/src/services/usage-history/store.ts

@@ -0,0 +1,174 @@
+import type { AIUsageTool } from '@brimveyn/aimux-config'
+
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { logDebug } from '../../debug/input-log'
+import { spawnDetachedCommand } from '../../platform/daemon-control'
+
+/**
+ * Long-term AI usage, per local calendar day.
+ *
+ * Claude Code prunes its transcripts after about a month, so this is not a cache
+ * of something re-derivable: once a day is pruned, this file is the only place
+ * its numbers still exist. Hence the refusal to overwrite anything it cannot
+ * fully round-trip.
+ */
+
+export const HISTORY_VERSION = 1
+/** A file that exists but did not parse. Never equal to HISTORY_VERSION, so the save guard refuses it. */
+const UNREADABLE_VERSION = -1
+const ROLLUP_INTERVAL_MS = 20 * 60 * 60 * 1000
+
+export interface UsageTokens {
+  cacheRead: number
+  cacheWrite: number
+  input: number
+  output: number
+  total: number
+}
+
+export interface UsageDay {
+  /** git branch -> tokens. Recent window only; Codex carries no branch. */
+  branches: Record<string, number>
+  /** model id -> tokens. Recent window only. */
+  models: Record<string, number>
+  /** The only field with full-year coverage, and claude-only. */
+  prompts: number
+  tokens: UsageTokens
+}
+
+/** 'YYYY-MM-DD' in the machine's local calendar -> that day's usage. */
+export type UsageDays = Record<string, UsageDay>
+
+/** The key format above — `toISOString()` would shift every evening east of Greenwich by one. */
+export function localDay(date: Date): string {
+  const month = String(date.getMonth() + 1).padStart(2, '0')
+  const day = String(date.getDate()).padStart(2, '0')
+  return `${date.getFullYear()}-${month}-${day}`
+}
+
+export type UsageTools = Partial<Record<AIUsageTool, UsageDays>>
+
+export interface UsageHistoryFile {
+  tools: UsageTools
+  version: number
+}
+
+export function emptyTokens(): UsageTokens {
+  return { cacheRead: 0, cacheWrite: 0, input: 0, output: 0, total: 0 }
+}
+
+export function emptyDay(): UsageDay {
+  return { branches: {}, models: {}, prompts: 0, tokens: emptyTokens() }
+}
+
+/** Resolved per call, not at module scope, so a `HOME` override in tests reaches it. */
+export function usageHistoryPath(): string {
+  const home = process.env.HOME ?? homedir()
+  return join(home, '.config', 'aimux', 'usage-history.json')
+}
+
+export function readUsageHistory(): UsageHistoryFile {
+  let raw: string
+  try {
+    raw = readFileSync(usageHistoryPath(), 'utf8')
+  } catch {
+    return { tools: {}, version: HISTORY_VERSION } // no file yet; safe to create
+  }
+
+  try {
+    const file = JSON.parse(raw) as Partial<UsageHistoryFile>
+    if (typeof file.version !== 'number') return { tools: {}, version: UNREADABLE_VERSION }
+    if (typeof file.tools !== 'object' || file.tools === null) {
+      return { tools: {}, version: UNREADABLE_VERSION }
+    }
+    return { tools: file.tools, version: file.version }
+  } catch {
+    return { tools: {}, version: UNREADABLE_VERSION }
+  }
+}
+
+function mergeDay(stored: UsageDay, fresh: UsageDay): UsageDay {
+  // Pruning only removes data, so a smaller fresh total means the stored copy is
+  // the richer one. `>=` rather than `>` is what makes re-running converge.
+  const keepFresh = fresh.tokens.total >= stored.tokens.total
+  // Prompts merge separately: they outlive the transcripts the tokens came from.
+  return {
+    branches: keepFresh ? fresh.branches : stored.branches,
+    models: keepFresh ? fresh.models : stored.models,
+    prompts: Math.max(fresh.prompts, stored.prompts),
+    tokens: keepFresh ? fresh.tokens : stored.tokens,
+  }
+}
+
+/** Replacement per day, never accumulation — adding would double every total per rollup. */
+export function mergeUsageHistory(stored: UsageTools, fresh: UsageTools): UsageTools {
+  const merged: UsageTools = { ...stored }
+
+  for (const [tool, freshDays] of Object.entries(fresh) as [AIUsageTool, UsageDays][]) {
+    const storedDays = stored[tool] ?? {}
+    const days: UsageDays = { ...storedDays }
+    for (const [date, freshDay] of Object.entries(freshDays)) {
+      const storedDay = storedDays[date]
+      days[date] = storedDay === undefined ? freshDay : mergeDay(storedDay, freshDay)
+    }
+    merged[tool] = days
+  }
+
+  return merged
+}
+
+/** False when nothing was written, which leaves the mtime alone so the next launch retries. */
+export function saveUsageHistory(fresh: UsageTools): boolean {
+  const stored = readUsageHistory()
+
+  // A newer aimux owns a shape this build cannot round-trip; an unreadable file
+  // may still hold years this rollup can no longer see. Neither gets written over.
+  if (stored.version !== HISTORY_VERSION) {
+    logDebug('usageHistory.refusedWrite', { version: stored.version })
+    return false
+  }
+
+  const path = usageHistoryPath()
+  const file: UsageHistoryFile = {
+    tools: mergeUsageHistory(stored.tools, fresh),
+    version: HISTORY_VERSION,
+  }
+
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    // pid-suffixed: two launches can roll up at once, and a shared tmp name would
+    // let one truncate the other's half-written file.
+    const tmpPath = `${path}.${process.pid}.tmp`
+    writeFileSync(tmpPath, `${JSON.stringify(file, null, 2)}\n`)
+    renameSync(tmpPath, path)
+    return true
+  } catch (error) {
+    logDebug('usageHistory.writeError', {
+      error: error instanceof Error ? error.message : String(error),
+    })
+    return false
+  }
+}
+
+/**
+ * Detached because the parse is a second of CPU over hundreds of MB of JSONL.
+ * 20h rather than 24h so opening aimux at the same time each morning does not
+ * land exactly on the boundary and skip every other day.
+ */
+export function maybeSpawnUsageRollup(): void {
+  try {
+    if (process.env.AIMUX_NO_USAGE_ROLLUP === '1') return
+    // mtime is the last successful rollup: the file is written on success and
+    // nothing else. Beats parsing an ever-growing JSON on the startup path.
+    const rolledUpAt = statSync(usageHistoryPath(), { throwIfNoEntry: false })?.mtimeMs ?? 0
+    if (Date.now() - rolledUpAt < ROLLUP_INTERVAL_MS) return
+    spawnDetachedCommand('usage-rollup')
+  } catch (error) {
+    logDebug('usageHistory.spawnError', {
+      error: error instanceof Error ? error.message : String(error),
+    })
+  }
+}

package/src/state/reducers/modal-state.ts

@@ -62,6 +62,9 @@ function getCreateWorkspaceBaseOptions(state: AppState, queryOverride?: string):
 function getModalOptionCount(state: AppState): number {
   const { modal } = state
   switch (modal.type) {
+    // Not a list: the two pages of the AI usage modal, Live and History.
+    case 'ai-usage':
+      return 2
     case 'create-project':
       return modal.directoryResults.length
     case 'help':
@@ -537,6 +540,7 @@ export function reduceModalState(state: AppState, action: AppAction): AppState |
         return { ...state, modal: { ...state.modal, selectedIndex: nextIndex } }
       }
       if (
+        state.modal.type !== 'ai-usage' &&
         state.modal.type !== 'new-tab' &&
         state.modal.type !== 'project-picker' &&
         state.modal.type !== 'snippet-picker' &&

package/src/ui/components/modals/app/ai-usage-modal.tsx

@@ -1,5 +1,8 @@
 import type { AIUsageTool } from '@brimveyn/aimux-config'
-import type { ReactNode } from 'react'
+import type { RGBA } from '@opentui/core'
+
+import { useTerminalDimensions } from '@opentui/react'
+import { type ReactNode, useEffect, useMemo, useState } from 'react'
 
 import type {
   UsagePaceStage,
@@ -7,8 +10,24 @@ import type {
   UsageWindow,
 } from '../../../../services/ai-usage/types'
 
+import {
+  buildHeatmap,
+  coveredWeeks,
+  type HeatmapCell,
+  mixColor,
+  monthRuler,
+  promptCounts,
+  summarizeDays,
+} from '../../../../services/usage-history/stats'
+import {
+  readUsageHistory,
+  type UsageDays,
+  type UsageHistoryFile,
+} from '../../../../services/usage-history/store'
 import { useAIUsageStore } from '../../../../state/ai-usage-store'
+import { formatCompact } from '../../../format-number'
 import { useTheme } from '../../../theme'
+import { truncate } from '../../../truncate'
 import { uiTokens } from '../../../ui-tokens'
 import { ModalShell } from '../shared/modal-shell'
 
@@ -55,34 +74,63 @@ function paceStageIsBehind(stage: UsagePaceStage): boolean {
   return stage === 'behind' || stage === 'farBehind' || stage === 'slightlyBehind'
 }
 
-export function AIUsageModal() {
+const TOOLS: AIUsageTool[] = ['claude', 'codex']
+const PAGE_LABELS = ['Live', 'History'] as const
+
+/** A year of weeks plus the gutter needs ~58 columns, so History takes the terminal where Live stays a popover. */
+const HISTORY_MAX_WIDTH = 104
+
+export function AIUsageModal({ page }: { page: number }) {
+  const dimensions = useTerminalDimensions()
+  const isHistory = page === 1
+
+  const width = isHistory
+    ? Math.max(uiTokens.modalWidth.md, Math.min(HISTORY_MAX_WIDTH, dimensions.width - 8))
+    : uiTokens.modalWidth.md
+
+  return (
+    <ModalShell title="AI usage" keybindsModeId="modal.ai-usage" width={width} listGap={1}>
+      <PageTabs active={page} />
+      {isHistory ? <HistoryPage width={width} /> : <LivePage />}
+    </ModalShell>
+  )
+}
+
+function PageTabs({ active }: { active: number }) {
+  const t = useTheme()
+  return (
+    <box flexDirection="row" gap={2}>
+      {PAGE_LABELS.map((label, index) => (
+        <text key={label} fg={index === active ? t.text : t.textMuted} selectable={false}>
+          {label}
+        </text>
+      ))}
+    </box>
+  )
+}
+
+function LivePage() {
   const t = useTheme()
   const snapshots = useAIUsageStore((s) => s.snapshots)
 
-  const tools: AIUsageTool[] = ['claude', 'codex']
-  const sections = tools
-    .map((tool) => ({ snap: snapshots[tool], tool }))
-    .filter((s): s is { snap: UsageSnapshot; tool: AIUsageTool } => s.snap !== undefined)
+  const sections = TOOLS.map((tool) => ({ snap: snapshots[tool], tool })).filter(
+    (s): s is { snap: UsageSnapshot; tool: AIUsageTool } => s.snap !== undefined
+  )
+
+  if (sections.length === 0) {
+    return (
+      <text fg={t.textMuted} selectable={false}>
+        no data yet — collecting…
+      </text>
+    )
+  }
 
   return (
-    <ModalShell
-      title="AI usage"
-      keybindsModeId="modal.ai-usage"
-      width={uiTokens.modalWidth.md}
-      listGap={1}
-    >
-      {sections.length === 0 ? (
-        <text fg={t.textMuted} selectable={false}>
-          no data yet — collecting…
-        </text>
-      ) : (
-        <box flexDirection="column" gap={1}>
-          {sections.map(({ snap, tool }) => (
-            <ToolSection key={tool} snap={snap} tool={tool} />
-          ))}
-        </box>
-      )}
-    </ModalShell>
+    <box flexDirection="column" gap={1}>
+      {sections.map(({ snap, tool }) => (
+        <ToolSection key={tool} snap={snap} tool={tool} />
+      ))}
+    </box>
   )
 }
 
@@ -191,3 +239,282 @@ function PaceLine({ pace }: { pace: NonNullable<UsageWindow['pace']> }) {
     </text>
   )
 }
+
+/** One block per day, shaded by colour. Varying the glyph (`░▒▓█`) instead produced an indistinct mass. */
+const CELL = '\u{2588}'
+const ROW_LABELS = ['Mon', '', 'Wed', '', 'Fri', '', ''] as const
+const ROW_KEYS = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'] as const
+const GUTTER = 5
+const COLUMN_GAP = 3
+
+/**
+ * Width on the box, never on the text: an empty <text> is not zero columns wide,
+ * so `Mon` and a padded blank did not start at the same column and the grid came
+ * out as a brick wall. Padding inside one string is fine; across siblings it is not.
+ */
+function Gutter({ label }: { label: string }) {
+  const t = useTheme()
+  return (
+    <box width={GUTTER} flexShrink={0}>
+      <text fg={t.textMuted} selectable={false}>
+        {label}
+      </text>
+    </box>
+  )
+}
+
+function SectionHeader({ label, note }: { label: string; note?: string }) {
+  const t = useTheme()
+  return (
+    <box flexDirection="row" justifyContent="space-between">
+      <text fg={t.textMuted} selectable={false}>
+        {label}
+      </text>
+      {note != null && note !== '' ? (
+        <text fg={t.textMuted} selectable={false}>
+          {note}
+        </text>
+      ) : null}
+    </box>
+  )
+}
+
+/** Width of the `input` / `output` / `cache` label column. */
+const LABEL_WIDTH = 11
+
+function LabelledRow({ label, value }: { label: string; value: string }) {
+  const t = useTheme()
+  return (
+    <box flexDirection="row">
+      <box width={LABEL_WIDTH} flexShrink={0}>
+        <text fg={t.textMuted} selectable={false}>
+          {label}
+        </text>
+      </box>
+      <text fg={t.text} selectable={false}>
+        {value}
+      </text>
+    </box>
+  )
+}
+
+function HeatRow({
+  cells,
+  cellWidth,
+  label,
+  ramp,
+}: {
+  cells: HeatmapCell[]
+  cellWidth: number
+  label: string
+  ramp: (string | RGBA)[]
+}) {
+  const t = useTheme()
+
+  // One <text> per colour run, not per cell: a full year is 371 cells.
+  const runs: { color: RGBA | string; start: number; text: string }[] = []
+  for (const [index, cell] of cells.entries()) {
+    const color = ramp[cell.level] ?? t.textMuted
+    const glyph = (cell.day === '' ? ' ' : CELL).repeat(cellWidth)
+    const last = runs.at(-1)
+    if (last !== undefined && last.color === color) last.text += glyph
+    else runs.push({ color, start: index, text: glyph })
+  }
+
+  return (
+    <box flexDirection="row">
+      <Gutter label={label} />
+      {runs.map((run) => (
+        <text key={run.start} fg={run.color} selectable={false}>
+          {run.text}
+        </text>
+      ))}
+    </box>
+  )
+}
+
+function Legend({ cellWidth, ramp }: { cellWidth: number; ramp: (string | RGBA)[] }) {
+  const t = useTheme()
+  return (
+    <box flexDirection="row">
+      <Gutter label="" />
+      <text fg={t.textMuted} selectable={false}>
+        less
+      </text>
+      <box width={1} flexShrink={0} />
+      {ramp.map((color, index) => (
+        <text key={color + String(index)} fg={color} selectable={false}>
+          {CELL.repeat(cellWidth)}
+        </text>
+      ))}
+      <box width={1} flexShrink={0} />
+      <text fg={t.textMuted} selectable={false}>
+        more
+      </text>
+    </box>
+  )
+}
+
+/** Right-hand `  2.8B  45%` block, fixed so values line up down the column. */
+const VALUE_WIDTH = 12
+
+/**
+ * One ranked table. Columns are boxes, not padded strings; two side by side line
+ * up because they share a width. Sizing each to its own longest name gave the
+ * tables unrelated geometries and stranded `main` 45 columns from its number.
+ */
+function TopColumn({
+  entries,
+  title,
+  total,
+  width,
+}: {
+  entries: [string, number][]
+  title: string
+  total: number
+  width: number
+}) {
+  const t = useTheme()
+  const nameWidth = Math.max(4, width - VALUE_WIDTH)
+
+  return (
+    <box flexDirection="column" width={width} flexShrink={0}>
+      <text fg={t.textMuted} selectable={false}>
+        {title}
+      </text>
+      {entries.map(([name, value]) => (
+        <box key={name} flexDirection="row">
+          <box width={nameWidth} flexShrink={0}>
+            <text fg={t.text} selectable={false}>
+              {truncate(name, nameWidth)}
+            </text>
+          </box>
+          {/* Padding inside one node, so nothing here is a trailing space. */}
+          <text fg={t.text} selectable={false}>
+            {formatCompact(value).padStart(7) +
+              (total > 0 ? `${Math.round((value / total) * 100)}%` : '').padStart(5)}
+          </text>
+        </box>
+      ))}
+    </box>
+  )
+}
+
+function HistoryPage({ width }: { width: number }) {
+  const t = useTheme()
+  const [history, setHistory] = useState<UsageHistoryFile | null>(null)
+
+  useEffect(() => {
+    // Synchronous, and ~100 KB even after a full year of rollups.
+    setHistory(readUsageHistory())
+  }, [])
+
+  // borderSubtle rather than a background token: backgrounds resolve to alpha 0
+  // in transparent mode. Above the early returns — hooks cannot be conditional.
+  const ramp = useMemo(
+    () => [
+      t.borderSubtle,
+      mixColor(t.borderSubtle, t.success, 0.35),
+      mixColor(t.borderSubtle, t.success, 0.6),
+      mixColor(t.borderSubtle, t.success, 0.82),
+      t.success,
+    ],
+    [t.borderSubtle, t.success]
+  )
+
+  if (history === null) {
+    return (
+      <text fg={t.textMuted} selectable={false}>
+        reading history…
+      </text>
+    )
+  }
+
+  const claude: UsageDays = history.tools.claude ?? {}
+  const codex: UsageDays = history.tools.codex ?? {}
+
+  if (Object.keys(claude).length === 0 && Object.keys(codex).length === 0) {
+    return (
+      <text fg={t.textMuted} selectable={false}>
+        no history yet — the first rollup runs in the background; reopen in a minute
+      </text>
+    )
+  }
+
+  const inner = width - 4
+  const today = new Date()
+  // Bounded by what is recorded: empty months predating the first rollup read as broken.
+  const weeks = coveredWeeks(claude, today, Math.max(4, Math.min(53, inner - GUTTER)))
+  // Terminal cells are ~2x taller than wide, so a two-column day is roughly square.
+  const cellWidth = weeks * 2 + GUTTER <= inner ? 2 : 1
+  const grid = buildHeatmap(promptCounts(claude), weeks, today)
+  const summary = summarizeDays(claude)
+  const codexSummary = summarizeDays(codex)
+
+  const average =
+    summary.promptDays === 0 ? 0 : Math.round(summary.totalPrompts / summary.promptDays)
+  const { tokens } = summary
+  // `2 * columnWidth + COLUMN_GAP <= inner` by construction.
+  const columnWidth = Math.max(16, Math.floor((inner - COLUMN_GAP) / 2))
+
+  return (
+    <box flexDirection="column" gap={1}>
+      <box flexDirection="column">
+        <SectionHeader
+          label="ACTIVITY"
+          note={`${summary.totalPrompts.toLocaleString('en-US').replaceAll(',', ' ')} prompts over ${summary.promptDays} days · ${average} avg · ${summary.peakPrompts} peak`}
+        />
+        <box flexDirection="row">
+          <Gutter label="" />
+          <text fg={t.textMuted} selectable={false}>
+            {monthRuler(grid, weeks, cellWidth)}
+          </text>
+        </box>
+        {grid.map((cells, index) => (
+          <HeatRow
+            key={ROW_KEYS[index]}
+            cells={cells}
+            cellWidth={cellWidth}
+            label={ROW_LABELS[index] ?? ''}
+            ramp={ramp}
+          />
+        ))}
+        <Legend cellWidth={cellWidth} ramp={ramp} />
+      </box>
+
+      <box flexDirection="column">
+        <SectionHeader
+          label="TOKENS"
+          note={`${summary.tokenDays} days retained · ${formatCompact(tokens.total)} total`}
+        />
+        <LabelledRow label="input" value={formatCompact(tokens.input)} />
+        <LabelledRow label="output" value={formatCompact(tokens.output)} />
+        <LabelledRow
+          label="cache"
+          value={`${formatCompact(tokens.cacheRead)} read · ${formatCompact(tokens.cacheWrite)} written`}
+        />
+        {codexSummary.tokens.total > 0 ? (
+          <LabelledRow
+            label="codex"
+            value={`${formatCompact(codexSummary.tokens.total)} over ${codexSummary.tokenDays} days`}
+          />
+        ) : null}
+      </box>
+
+      <box flexDirection="row" gap={COLUMN_GAP}>
+        <TopColumn
+          entries={summary.models}
+          title="MODELS"
+          total={summary.modelTotal}
+          width={columnWidth}
+        />
+        <TopColumn
+          entries={summary.branches}
+          title="BRANCHES"
+          total={summary.branchTotal}
+          width={columnWidth}
+        />
+      </box>
+    </box>
+  )
+}

package/src/ui/components/overlays/ai-usage/ai-usage-indicator.tsx

@@ -4,6 +4,7 @@ import { useCallback } from 'react'
 
 import { useAIUsageStore } from '../../../../state/ai-usage-store'
 import { dispatchGlobal } from '../../../../state/dispatch-ref'
+import { formatCompact } from '../../../format-number'
 import { useTheme } from '../../../theme'
 
 /** nf-cod-claude / nf-cod-openai. Needs a nerd font, like the status bar separators. */
@@ -12,12 +13,6 @@ const ICON: Record<AIUsageTool, string> = {
   codex: '\u{ec81}',
 }
 
-function formatTokens(total: number): string {
-  if (total >= 1_000_000) return `${(total / 1_000_000).toFixed(1)}M`
-  if (total >= 1_000) return `${(total / 1_000).toFixed(1)}k`
-  return String(total)
-}
-
 export function AIUsageIndicator() {
   const t = useTheme()
   const enabled = useAIUsageStore((s) => s.enabled)
@@ -65,7 +60,7 @@ export function AIUsageIndicator() {
         }
 
         const value =
-          snap.percent !== null ? `${Math.round(snap.percent)}%` : formatTokens(snap.tokens.total)
+          snap.percent !== null ? `${Math.round(snap.percent)}%` : formatCompact(snap.tokens.total)
 
         return (
           <box key={tool} flexDirection="row">

package/src/ui/format-number.ts

@@ -0,0 +1,12 @@
+/**
+ * Token counts, short enough for a status bar and a stats table alike.
+ *
+ * One function rather than one per surface: the indicator and the usage modal
+ * had drifted to `1.2k` and `1.2K` for the same number.
+ */
+export function formatCompact(value: number): string {
+  if (value >= 1e9) return `${(value / 1e9).toFixed(1)}B`
+  if (value >= 1e6) return `${(value / 1e6).toFixed(1)}M`
+  if (value >= 1e3) return `${(value / 1e3).toFixed(1)}k`
+  return String(value)
+}

package/src/ui/root.tsx

@@ -249,7 +249,7 @@ function renderModal(
         />
       )
     case 'ai-usage':
-      return <AIUsageModal />
+      return <AIUsageModal page={modal.selectedIndex} />
     case 'workspace-delete-confirm':
       return (
         <WorkspaceDeleteConfirm