@brimveyn/aimux 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",
@@ -60,7 +60,7 @@
     "bump": "bun run scripts/bump.ts"
   },
   "dependencies": {
-    "@brimveyn/aimux-config": "0.5.0",
+    "@brimveyn/aimux-config": "0.5.1",
     "@opentui/core": "^0.1.90",
     "@opentui/react": "^0.1.90",
     "@xterm/headless": "^6.0.0",

package/src/input/modes/bridge.ts

@@ -24,6 +24,7 @@ const COMMAND_EDIT_MODE_IDS: Partial<Record<SupportedModalType, ModeId>> = {
 }
 
 const MODAL_MODE_IDS: Partial<Record<SupportedModalType, ModeId>> = {
+  'ai-usage': 'modal.ai-usage',
   'update-available': 'modal.update-available',
 }
 

package/src/input/modes/transitions.ts

@@ -2,6 +2,7 @@ import type { ModeId } from './types'
 
 const TRANSITIONS: Record<ModeId, readonly ModeId[]> = {
   'git-mode': ['navigation', 'modal.git-commit'],
+  'modal.ai-usage': ['navigation', 'terminal-input'],
   'modal.create-session': ['navigation', 'modal.session-picker.filtering'],
   'modal.git-commit': ['git-mode', 'modal.git-commit.confirm', 'modal.git-commit.generating'],
   'modal.git-commit.confirm': ['modal.git-commit', 'git-mode'],
@@ -27,9 +28,10 @@ const TRANSITIONS: Record<ModeId, readonly ModeId[]> = {
     'modal.theme-picker.filtering',
     'modal.rename-tab',
     'modal.update-available',
+    'modal.ai-usage',
     'git-mode',
   ],
-  'terminal-input': ['navigation', 'modal.split-picker'],
+  'terminal-input': ['navigation', 'modal.split-picker', 'modal.ai-usage'],
 }
 
 export function isValidTransition(from: ModeId, to: ModeId): boolean {

package/src/input/modes/types.ts

@@ -21,6 +21,7 @@ export type ModeId =
   | 'modal.git-commit.confirm'
   | 'modal.git-commit.generating'
   | 'modal.update-available'
+  | 'modal.ai-usage'
 
 export type SideEffect =
   | { type: 'quit'; state: AppState }

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

@@ -1,12 +1,14 @@
 import type { AIUsageToolConfig } from '@brimveyn/aimux-config'
 
-import type { UsageSnapshot } from '../types'
+import type { UsageSnapshot, UsageWindow, UsageWindowKind } from '../types'
 
+import { computePace, formatTimeRemaining } from '../pace'
 import { runCli } from '../spawn'
 
 interface ClaudeOAuthCreds {
   accessToken: string
   expiresAt?: number
+  planTier: string | null
 }
 
 interface ClaudeKeychainPayload {
@@ -14,29 +16,67 @@ interface ClaudeKeychainPayload {
     accessToken?: string
     expiresAt?: number
     refreshToken?: string
+    rateLimitTier?: string
+    rate_limit_tier?: string
+    subscriptionType?: string
+    scopes?: string[]
   }
 }
 
-interface UsageWindow {
+interface UsageWindowPayload {
   utilization?: number
   resets_at?: string
 }
 
 interface ClaudeUsageResponse {
-  five_hour?: UsageWindow
-  seven_day?: UsageWindow
-  seven_day_sonnet?: UsageWindow
-  seven_day_opus?: UsageWindow
-  extra_usage?: UsageWindow & { spent_usd?: number; limit_usd?: number }
+  five_hour?: UsageWindowPayload
+  seven_day?: UsageWindowPayload
+  seven_day_sonnet?: UsageWindowPayload
+  seven_day_opus?: UsageWindowPayload
+  extra_usage?: UsageWindowPayload & { spent_usd?: number; limit_usd?: number }
 }
 
 const USAGE_URL = 'https://api.anthropic.com/api/oauth/usage'
 const OAUTH_BETA_HEADER = 'oauth-2025-04-20'
 const FETCH_TIMEOUT_MS = 15_000
 
+const FIVE_HOUR_SECONDS = 5 * 60 * 60
+const SEVEN_DAY_SECONDS = 7 * 24 * 60 * 60
+
 let cachedCreds: ClaudeOAuthCreds | null = null
 const CREDS_EXPIRY_BUFFER_MS = 60_000
 
+function normalizePlanTier(raw: string | undefined | null): string | null {
+  if (!raw) return null
+  const trimmed = raw.trim()
+  if (!trimmed) return null
+  const lower = trimmed.toLowerCase()
+  if (lower.includes('max')) return 'Max'
+  if (lower.includes('pro')) return 'Pro'
+  if (lower.includes('team')) return 'Team'
+  if (lower.includes('enterprise')) return 'Enterprise'
+  if (lower.includes('ultra')) return 'Ultra'
+  return trimmed.charAt(0).toUpperCase() + trimmed.slice(1)
+}
+
+function planTierFromPayload(payload: ClaudeKeychainPayload): string | null {
+  const o = payload.claudeAiOauth
+  if (!o) return null
+  const raw = o.rateLimitTier ?? o.rate_limit_tier ?? o.subscriptionType
+  const normalized = normalizePlanTier(raw)
+  if (normalized) return normalized
+  if (Array.isArray(o.scopes)) {
+    for (const scope of o.scopes) {
+      const s = scope.toLowerCase()
+      if (s.includes('max')) return 'Max'
+      if (s.includes('pro')) return 'Pro'
+      if (s.includes('team')) return 'Team'
+      if (s.includes('enterprise')) return 'Enterprise'
+    }
+  }
+  return null
+}
+
 async function readClaudeCreds(): Promise<ClaudeOAuthCreds> {
   const now = Date.now()
   if (
@@ -64,31 +104,51 @@ async function readClaudeCreds(): Promise<ClaudeOAuthCreds> {
   if (!access) {
     throw new Error('no accessToken in Claude Code keychain')
   }
-  cachedCreds = { accessToken: access, expiresAt: parsed.claudeAiOauth?.expiresAt }
+  cachedCreds = {
+    accessToken: access,
+    expiresAt: parsed.claudeAiOauth?.expiresAt,
+    planTier: planTierFromPayload(parsed),
+  }
   return cachedCreds
 }
 
-function formatRemainingFromIso(iso: string | undefined): string | null {
-  if (!iso) return null
-  const ms = new Date(iso).getTime() - Date.now()
-  if (ms <= 0) return null
-  const totalMin = Math.round(ms / 60_000)
-  const h = Math.floor(totalMin / 60)
-  const m = totalMin % 60
-  return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}h`
+function buildWindow(
+  kind: UsageWindowKind,
+  label: string,
+  payload: UsageWindowPayload | undefined,
+  windowSeconds: number,
+  now: number
+): UsageWindow | null {
+  if (!payload) return null
+  const util = typeof payload.utilization === 'number' ? payload.utilization : null
+  const percent = util === null ? null : Math.max(0, Math.min(100, util))
+  const resetAt = payload.resets_at ?? null
+  const resetAtMs = resetAt ? new Date(resetAt).getTime() : null
+  if (percent === null && !resetAt) return null
+  return {
+    kind,
+    label,
+    pace: kind === 'weekly' ? computePace({ now, percent, resetAtMs, windowSeconds }) : null,
+    percent,
+    resetAt,
+    timeRemaining: formatTimeRemaining(resetAtMs, now),
+    windowSeconds,
+  }
 }
 
 export async function fetchClaudeUsage(_config: AIUsageToolConfig): Promise<UsageSnapshot> {
-  const now = new Date().toISOString()
+  const nowIso = new Date().toISOString()
   const base: UsageSnapshot = {
     burnRatePerHour: null,
     costUSD: null,
-    lastUpdated: now,
+    lastUpdated: nowIso,
     percent: null,
+    planTier: null,
     resetAt: null,
     timeRemaining: null,
     tokens: { cache: 0, input: 0, output: 0, total: 0 },
     tool: 'claude',
+    windows: [],
   }
 
   try {
@@ -112,23 +172,39 @@ export async function fetchClaudeUsage(_config: AIUsageToolConfig): Promise<Usag
 
     if (response.status === 401 || response.status === 403) {
       cachedCreds = null
-      return { ...base, error: 'claude oauth expired — run `claude` to re-auth' }
+      return {
+        ...base,
+        error: 'claude oauth expired — run `claude` to re-auth',
+        planTier: creds.planTier,
+      }
     }
     if (!response.ok) {
-      return { ...base, error: `claude api ${response.status}` }
+      return { ...base, error: `claude api ${response.status}`, planTier: creds.planTier }
     }
 
     const parsed = (await response.json()) as ClaudeUsageResponse
-    const fiveHour = parsed.five_hour
-    const utilization = typeof fiveHour?.utilization === 'number' ? fiveHour.utilization : null
-    const percent = utilization === null ? null : Math.max(0, Math.min(100, utilization))
+    const now = Date.now()
+
+    const windows: UsageWindow[] = []
+    const session = buildWindow('session', 'Session', parsed.five_hour, FIVE_HOUR_SECONDS, now)
+    if (session) windows.push(session)
+    const weekly = buildWindow('weekly', 'Weekly', parsed.seven_day, SEVEN_DAY_SECONDS, now)
+    if (weekly) windows.push(weekly)
+    const opus = buildWindow('opus', 'Opus', parsed.seven_day_opus, SEVEN_DAY_SECONDS, now)
+    if (opus) windows.push(opus)
+    const sonnet = buildWindow('sonnet', 'Sonnet', parsed.seven_day_sonnet, SEVEN_DAY_SECONDS, now)
+    if (sonnet) windows.push(sonnet)
+
+    const summary = session ?? weekly
 
     return {
       ...base,
-      percent,
-      resetAt: fiveHour?.resets_at ?? null,
-      timeRemaining: formatRemainingFromIso(fiveHour?.resets_at),
+      percent: summary?.percent ?? null,
+      planTier: creds.planTier,
+      resetAt: summary?.resetAt ?? null,
+      timeRemaining: summary?.timeRemaining ?? null,
       tool: 'claude',
+      windows,
     }
   } catch (error) {
     return {

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

@@ -4,7 +4,9 @@ import { readFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 
-import type { UsageSnapshot } from '../types'
+import type { UsageSnapshot, UsageWindow, UsageWindowKind } from '../types'
+
+import { computePace, formatTimeRemaining } from '../pace'
 
 interface CodexAuthFile {
   tokens?: {
@@ -101,39 +103,78 @@ async function loadAuth(): Promise<{ accessToken: string; accountId: string | nu
   }
 }
 
-function formatRemainingFromReset(resetAtSeconds: number | undefined): string | null {
-  if (!resetAtSeconds) return null
-  const diffMs = resetAtSeconds * 1000 - Date.now()
-  if (diffMs <= 0) return null
-  const totalMin = Math.round(diffMs / 60_000)
-  const h = Math.floor(totalMin / 60)
-  const m = totalMin % 60
-  return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}h`
+function normalizePlanTier(raw: string | undefined | null): string | null {
+  if (!raw) return null
+  const trimmed = raw.trim()
+  if (!trimmed) return null
+  const lower = trimmed.toLowerCase()
+  if (lower === 'pro') return 'Pro'
+  if (lower === 'plus') return 'Plus'
+  if (lower === 'free') return 'Free'
+  if (lower === 'team') return 'Team'
+  if (lower === 'business') return 'Business'
+  if (lower === 'enterprise') return 'Enterprise'
+  if (lower === 'edu' || lower === 'education') return 'Edu'
+  if (lower === 'go') return 'Go'
+  return trimmed.charAt(0).toUpperCase() + trimmed.slice(1)
+}
+
+function buildCodexWindow(
+  kind: UsageWindowKind,
+  label: string,
+  window: WindowSnapshot | null | undefined,
+  now: number
+): UsageWindow | null {
+  if (!window) return null
+  const percent =
+    typeof window.used_percent === 'number' ? Math.max(0, Math.min(100, window.used_percent)) : null
+  const resetAtMs = window.reset_at ? window.reset_at * 1000 : null
+  const resetAt = resetAtMs ? new Date(resetAtMs).toISOString() : null
+  const windowSeconds =
+    typeof window.limit_window_seconds === 'number' ? window.limit_window_seconds : null
+  if (percent === null && !resetAt) return null
+  return {
+    kind,
+    label,
+    pace: computePace({ now, percent, resetAtMs, windowSeconds }),
+    percent,
+    resetAt,
+    timeRemaining: formatTimeRemaining(resetAtMs, now),
+    windowSeconds,
+  }
 }
 
-function pickPrimaryWindow(rate: CodexUsageResponse['rate_limit']): WindowSnapshot | null {
-  if (!rate) return null
-  // Primary = 5h session window. Pick the one closest to 300 minutes (18000s),
-  // falling back to whichever is defined.
-  const windows = [rate.primary_window, rate.secondary_window].filter(
-    (w): w is WindowSnapshot => !!w
-  )
-  if (windows.length === 0) return null
-  const sessionWindow = windows.find((w) => w.limit_window_seconds === 18_000)
-  return sessionWindow ?? windows[0] ?? null
+function orderWindows(
+  primary: WindowSnapshot | null | undefined,
+  secondary: WindowSnapshot | null | undefined
+): {
+  session: WindowSnapshot | null | undefined
+  weekly: WindowSnapshot | null | undefined
+} {
+  const SESSION_MIN_SECONDS = 3 * 3600
+  const SESSION_MAX_SECONDS = 8 * 3600
+  const isSession = (w: WindowSnapshot | null | undefined): boolean => {
+    const s = w?.limit_window_seconds
+    return typeof s === 'number' && s >= SESSION_MIN_SECONDS && s <= SESSION_MAX_SECONDS
+  }
+  if (isSession(primary)) return { session: primary, weekly: secondary }
+  if (isSession(secondary)) return { session: secondary, weekly: primary }
+  return { session: primary, weekly: secondary }
 }
 
 export async function fetchCodexUsage(_config: AIUsageToolConfig): Promise<UsageSnapshot> {
-  const now = new Date().toISOString()
+  const nowIso = new Date().toISOString()
   const base: UsageSnapshot = {
     burnRatePerHour: null,
     costUSD: null,
-    lastUpdated: now,
+    lastUpdated: nowIso,
     percent: null,
+    planTier: null,
     resetAt: null,
     timeRemaining: null,
     tokens: { cache: 0, input: 0, output: 0, total: 0 },
     tool: 'codex',
+    windows: [],
   }
 
   try {
@@ -164,23 +205,33 @@ export async function fetchCodexUsage(_config: AIUsageToolConfig): Promise<Usage
     }
 
     const parsed = (await response.json()) as CodexUsageResponse
-    const window = pickPrimaryWindow(parsed.rate_limit)
-    if (!window) {
-      return { ...base, error: 'no rate_limit data' }
+    const planTier = normalizePlanTier(parsed.plan_type)
+    const now = Date.now()
+    const { session, weekly } = orderWindows(
+      parsed.rate_limit?.primary_window,
+      parsed.rate_limit?.secondary_window
+    )
+
+    const windows: UsageWindow[] = []
+    const sessionWindow = buildCodexWindow('session', 'Session', session, now)
+    if (sessionWindow) windows.push(sessionWindow)
+    const weeklyWindow = buildCodexWindow('weekly', 'Weekly', weekly, now)
+    if (weeklyWindow) windows.push(weeklyWindow)
+
+    if (windows.length === 0) {
+      return { ...base, error: 'no rate_limit data', planTier }
     }
 
-    const percent =
-      typeof window.used_percent === 'number'
-        ? Math.max(0, Math.min(100, window.used_percent))
-        : null
-    const resetAt = window.reset_at ? new Date(window.reset_at * 1000).toISOString() : null
+    const summary = sessionWindow ?? weeklyWindow
 
     return {
       ...base,
-      percent,
-      resetAt,
-      timeRemaining: formatRemainingFromReset(window.reset_at),
+      percent: summary?.percent ?? null,
+      planTier,
+      resetAt: summary?.resetAt ?? null,
+      timeRemaining: summary?.timeRemaining ?? null,
       tool: 'codex',
+      windows,
     }
   } catch (error) {
     return {

package/src/services/ai-usage/cache.ts

@@ -0,0 +1,60 @@
+import type { AIUsageTool } from '@brimveyn/aimux-config'
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+import type { UsageSnapshot } from './types'
+
+const CACHE_DIR = join(homedir(), '.cache', 'aimux')
+const CACHE_PATH = join(CACHE_DIR, 'ai-usage.json')
+
+interface CacheEntry {
+  fetchedAt: number
+  snapshot: UsageSnapshot
+}
+
+type CacheFile = Partial<Record<AIUsageTool, CacheEntry>>
+
+function readCacheFile(): CacheFile {
+  try {
+    if (!existsSync(CACHE_PATH)) return {}
+    const raw = readFileSync(CACHE_PATH, 'utf8')
+    const parsed = JSON.parse(raw) as unknown
+    if (typeof parsed !== 'object' || parsed === null) return {}
+    return parsed as CacheFile
+  } catch {
+    return {}
+  }
+}
+
+export interface CachedSnapshot {
+  snapshot: UsageSnapshot
+  ageMs: number
+}
+
+export function loadCachedSnapshot(tool: AIUsageTool, maxAgeMs: number): CachedSnapshot | null {
+  const cache = readCacheFile()
+  const entry = cache[tool]
+  if (!entry) return null
+  if (typeof entry.fetchedAt !== 'number') return null
+  const ageMs = Date.now() - entry.fetchedAt
+  if (ageMs > maxAgeMs) return null
+  if (!entry.snapshot || entry.snapshot.tool !== tool) return null
+  return { ageMs, snapshot: entry.snapshot }
+}
+
+export function saveCachedSnapshot(snapshot: UsageSnapshot): void {
+  if (snapshot.error) return
+  if (snapshot.percent === null) return
+  try {
+    mkdirSync(CACHE_DIR, { recursive: true })
+    const cache = readCacheFile()
+    cache[snapshot.tool] = { fetchedAt: Date.now(), snapshot }
+    const tmpPath = `${CACHE_PATH}.${process.pid}.tmp`
+    writeFileSync(tmpPath, `${JSON.stringify(cache, null, 2)}\n`)
+    renameSync(tmpPath, CACHE_PATH)
+  } catch {
+    // swallow — cache is best-effort
+  }
+}

package/src/services/ai-usage/pace.ts

@@ -0,0 +1,79 @@
+import type { UsagePace, UsagePaceStage } from './types'
+
+function stageFor(delta: number): UsagePaceStage {
+  const abs = Math.abs(delta)
+  if (abs <= 2) return 'onTrack'
+  if (abs <= 6) return delta >= 0 ? 'slightlyBehind' : 'slightlyAhead'
+  if (abs <= 12) return delta >= 0 ? 'behind' : 'ahead'
+  return delta >= 0 ? 'farBehind' : 'farAhead'
+}
+
+function formatDuration(seconds: number): string {
+  const total = Math.max(0, Math.round(seconds))
+  const h = Math.floor(total / 3600)
+  const m = Math.floor((total % 3600) / 60)
+  if (h >= 24) {
+    const d = Math.floor(h / 24)
+    const hh = h % 24
+    return hh > 0 ? `${d}d ${hh}h` : `${d}d`
+  }
+  if (h > 0) return m > 0 ? `${h}h ${m}m` : `${h}h`
+  return `${m}m`
+}
+
+export function computePace(opts: {
+  percent: number | null
+  resetAtMs: number | null
+  windowSeconds: number | null
+  now?: number
+}): UsagePace | null {
+  const { percent, resetAtMs, windowSeconds } = opts
+  const now = opts.now ?? Date.now()
+  if (percent === null || resetAtMs === null || !windowSeconds || windowSeconds <= 0) {
+    return null
+  }
+
+  const timeUntilReset = (resetAtMs - now) / 1000
+  if (timeUntilReset <= 0 || timeUntilReset > windowSeconds) return null
+
+  const elapsed = Math.max(0, Math.min(windowSeconds, windowSeconds - timeUntilReset))
+  const expected = Math.max(0, Math.min(100, (elapsed / windowSeconds) * 100))
+  const actual = Math.max(0, Math.min(100, percent))
+  const delta = actual - expected
+  const rounded = Math.round(delta)
+  const stage = stageFor(rounded)
+
+  let rightText: string | null = null
+  if (elapsed > 0 && actual > 0) {
+    const rate = actual / elapsed
+    if (rate > 0) {
+      const remaining = Math.max(0, 100 - actual)
+      const candidate = remaining / rate
+      if (candidate >= timeUntilReset) {
+        rightText = 'Lasts to reset'
+      } else {
+        rightText = `Runs out in ${formatDuration(candidate)}`
+      }
+    }
+  } else if (elapsed > 0 && actual === 0) {
+    rightText = 'Lasts to reset'
+  }
+
+  let label: string
+  if (stage === 'onTrack') {
+    label = 'On pace'
+  } else if (rounded > 0) {
+    label = `Behind (+${rounded}%)`
+  } else {
+    label = `Ahead (${rounded}%)`
+  }
+
+  return { delta, label, rightText, stage }
+}
+
+export function formatTimeRemaining(resetAtMs: number | null, now?: number): string | null {
+  if (resetAtMs === null) return null
+  const diff = resetAtMs - (now ?? Date.now())
+  if (diff <= 0) return null
+  return formatDuration(diff / 1000)
+}

package/src/services/ai-usage/provider.ts

@@ -4,6 +4,7 @@ import type { UsageSnapshot } from './types'
 
 import { fetchClaudeUsage } from './adapters/claude'
 import { fetchCodexUsage } from './adapters/codex'
+import { loadCachedSnapshot, saveCachedSnapshot } from './cache'
 
 const DEFAULT_POLL_SECONDS = 60
 const DEFAULT_TOOLS: AIUsageTool[] = ['claude', 'codex']
@@ -34,32 +35,54 @@ export function startAIUsageService(
 
   const tick = async (): Promise<void> => {
     if (stopped) return
-    const results = await Promise.allSettled(tools.map((t) => fetchFor(t, config)))
-    if (stopped) return
-    for (let i = 0; i < results.length; i++) {
-      const result = results[i]
-      const tool = tools[i]
-      if (!result || !tool) continue
-      if (result.status === 'fulfilled') {
-        onUpdate(result.value)
+
+    const toFetch: AIUsageTool[] = []
+    let maxCachedAgeMs = 0
+    for (const tool of tools) {
+      const cached = loadCachedSnapshot(tool, pollMs)
+      if (cached) {
+        onUpdate(cached.snapshot)
+        if (cached.ageMs > maxCachedAgeMs) maxCachedAgeMs = cached.ageMs
       } else {
-        onUpdate({
-          burnRatePerHour: null,
-          costUSD: null,
-          error: result.reason instanceof Error ? result.reason.message : String(result.reason),
-          lastUpdated: new Date().toISOString(),
-          percent: null,
-          resetAt: null,
-          timeRemaining: null,
-          tokens: { cache: 0, input: 0, output: 0, total: 0 },
-          tool,
-        })
+        toFetch.push(tool)
+      }
+    }
+
+    if (toFetch.length > 0) {
+      const results = await Promise.allSettled(toFetch.map((t) => fetchFor(t, config)))
+      if (stopped) return
+      for (let i = 0; i < results.length; i++) {
+        const result = results[i]
+        const tool = toFetch[i]
+        if (!result || !tool) continue
+        if (result.status === 'fulfilled') {
+          saveCachedSnapshot(result.value)
+          onUpdate(result.value)
+        } else {
+          onUpdate({
+            burnRatePerHour: null,
+            costUSD: null,
+            error: result.reason instanceof Error ? result.reason.message : String(result.reason),
+            lastUpdated: new Date().toISOString(),
+            percent: null,
+            planTier: null,
+            resetAt: null,
+            timeRemaining: null,
+            tokens: { cache: 0, input: 0, output: 0, total: 0 },
+            tool,
+            windows: [],
+          })
+        }
       }
     }
+
     if (!stopped) {
+      const minDelayMs = 5_000
+      const nextDelayMs =
+        toFetch.length > 0 ? pollMs : Math.max(minDelayMs, pollMs - maxCachedAgeMs)
       timer = setTimeout(() => {
         void tick()
-      }, pollMs)
+      }, nextDelayMs)
     }
   }
 

package/src/services/ai-usage/types.ts

@@ -2,6 +2,34 @@ import type { AIUsageTool } from '@brimveyn/aimux-config'
 
 export type { AIUsageTool }
 
+export type UsageWindowKind = 'session' | 'weekly' | 'sonnet' | 'opus' | 'primary' | 'secondary'
+
+export type UsagePaceStage =
+  | 'farAhead'
+  | 'ahead'
+  | 'slightlyAhead'
+  | 'onTrack'
+  | 'slightlyBehind'
+  | 'behind'
+  | 'farBehind'
+
+export interface UsagePace {
+  delta: number
+  stage: UsagePaceStage
+  label: string
+  rightText: string | null
+}
+
+export interface UsageWindow {
+  kind: UsageWindowKind
+  label: string
+  percent: number | null
+  resetAt: string | null
+  timeRemaining: string | null
+  windowSeconds: number | null
+  pace: UsagePace | null
+}
+
 export interface UsageSnapshot {
   tool: AIUsageTool
   percent: number | null
@@ -16,5 +44,8 @@ export interface UsageSnapshot {
   timeRemaining: string | null
   burnRatePerHour: number | null
   lastUpdated: string
+  planTier: string | null
+  windows: UsageWindow[]
   error?: string
+  stale?: boolean
 }

package/src/state/ai-usage-store.ts

@@ -18,9 +18,16 @@ export const aiUsageStore = createStore<AIUsageState>((set) => ({
   enabled: false,
   setEnabled: (enabled: boolean) => set({ enabled }),
   setSnapshot: (snap: UsageSnapshot) =>
-    set((state) => ({
-      snapshots: { ...state.snapshots, [snap.tool]: snap },
-    })),
+    set((state) => {
+      const prev = state.snapshots[snap.tool]
+      const isFailure = Boolean(snap.error)
+      const hasPriorValue = prev && prev.percent !== null
+      const merged: UsageSnapshot =
+        isFailure && hasPriorValue && prev
+          ? { ...prev, error: snap.error, lastUpdated: snap.lastUpdated, stale: true }
+          : snap
+      return { snapshots: { ...state.snapshots, [snap.tool]: merged } }
+    }),
   snapshots: {},
 }))
 

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

@@ -54,6 +54,19 @@ export function reduceModalState(state: AppState, action: AppAction): AppState |
         },
       }
     }
+    case 'open-ai-usage-modal': {
+      return {
+        ...state,
+        focusMode: 'modal',
+        modal: {
+          cursorPos: 0,
+          editBuffer: '',
+          selectedIndex: 0,
+          sessionTargetId: null,
+          type: 'ai-usage',
+        },
+      }
+    }
     case 'open-help-modal': {
       const keymap = getActiveKeymap()
       const scope = action.scope ?? null

package/src/state/types.ts

@@ -44,6 +44,7 @@ export type ModalType =
   | 'split-picker'
   | 'git-commit'
   | 'update-available'
+  | 'ai-usage'
   | null
 
 export interface TerminalSpan {
@@ -348,6 +349,10 @@ export interface ModalUpdateAvailable extends ModalBase {
   latestVersion: string
 }
 
+export interface ModalAIUsage extends ModalBase {
+  type: 'ai-usage'
+}
+
 export type DirectoryResultType = 'git-repo' | 'worktree' | 'workspace'
 
 export interface DirectoryResult {
@@ -369,6 +374,7 @@ export type ModalState =
   | ModalSnippetEditor
   | ModalGitCommit
   | ModalUpdateAvailable
+  | ModalAIUsage
 
 export interface LayoutState {
   terminalCols: number
@@ -434,6 +440,7 @@ export type ModalAction =
   | { type: 'open-theme-picker' }
   | { type: 'open-update-available-modal'; currentVersion: string; latestVersion: string }
   | { type: 'set-modal-selection-index'; index: number }
+  | { type: 'open-ai-usage-modal' }
 
 // -- Session actions --
 export type SessionAction =

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

@@ -1,8 +1,8 @@
 import type { AIUsageTool } from '@brimveyn/aimux-config'
 
 import { useAIUsageStore } from '../../state/ai-usage-store'
-import { toggleAIUsagePopover } from '../ai-usage/controller'
-import { useTokens } from '../theme'
+import { dispatchGlobal } from '../../state/dispatch-ref'
+import { useBg, useTokens } from '../theme'
 
 const TOOL_ICON: Record<AIUsageTool, string> = {
   claude: 'CC',
@@ -19,7 +19,7 @@ function formatTokens(total: number): string {
   return String(total)
 }
 
-function buildBar(percent: number): { filled: string; empty: string } {
+function buildBar(percent: number): { empty: string; filled: string } {
   let filledCount = 0
   for (let i = 0; i < BAR_SEGMENTS; i++) {
     if (percent > i * (100 / BAR_SEGMENTS)) filledCount++
@@ -48,6 +48,7 @@ function formatResetIn(snap: {
 
 export function AIUsageIndicator() {
   const t = useTokens()
+  const bg = useBg('elevated')
   const enabled = useAIUsageStore((s) => s.enabled)
   const snapshots = useAIUsageStore((s) => s.snapshots)
 
@@ -58,35 +59,49 @@ export function AIUsageIndicator() {
     .map((tool) => ({ snap: snapshots[tool], tool }))
     .filter((entry) => entry.snap !== undefined)
 
+  const openModal = (e: { preventDefault: () => void; stopPropagation: () => void }) => {
+    e.preventDefault()
+    e.stopPropagation()
+    dispatchGlobal({ type: 'open-ai-usage-modal' })
+  }
+
   if (entries.length === 0) {
     return (
-      <box flexDirection="row" gap={1}>
+      <box
+        flexDirection="row"
+        paddingLeft={1}
+        paddingRight={1}
+        backgroundColor={bg}
+        onMouseDown={openModal}
+      >
         <text fg={t.muted}>…</text>
       </box>
     )
   }
 
   return (
-    <box
-      flexDirection="row"
-      gap={2}
-      onMouseDown={(e) => {
-        e.preventDefault()
-        e.stopPropagation()
-        if (e.button !== 0) return
-        toggleAIUsagePopover(e.x, e.y)
-      }}
-    >
+    <box flexDirection="row" gap={1}>
       {entries.map(({ snap, tool }) => {
         if (!snap) return null
         const icon = TOOL_ICON[tool]
-        if (snap.error) {
+
+        if (snap.error && !snap.stale) {
           return (
-            <text key={tool} fg={t.palette.error} selectable={false}>
-              {icon} —
-            </text>
+            <box
+              key={tool}
+              flexDirection="row"
+              paddingLeft={1}
+              paddingRight={1}
+              backgroundColor={bg}
+              onMouseDown={openModal}
+            >
+              <text fg={t.palette.error} selectable={false}>
+                {`${icon} —`}
+              </text>
+            </box>
           )
         }
+
         if (snap.percent !== null) {
           const p = Math.round(snap.percent)
           let color = t.palette.success
@@ -99,9 +114,16 @@ export function AIUsageIndicator() {
           const reset = formatResetIn(snap)
           const pctText = `${String(p).padStart(2, ' ')}%`
           return (
-            <box key={tool} flexDirection="row">
+            <box
+              key={tool}
+              flexDirection="row"
+              paddingLeft={1}
+              paddingRight={1}
+              backgroundColor={bg}
+              onMouseDown={openModal}
+            >
               <text fg={color} selectable={false}>
-                {icon}{' '}
+                {`${icon} `}
               </text>
               <text fg={color} selectable={false}>
                 {filled}
@@ -120,10 +142,20 @@ export function AIUsageIndicator() {
             </box>
           )
         }
+
         return (
-          <text key={tool} fg={t.muted} selectable={false}>
-            {icon} {formatTokens(snap.tokens.total)}
-          </text>
+          <box
+            key={tool}
+            flexDirection="row"
+            paddingLeft={1}
+            paddingRight={1}
+            backgroundColor={bg}
+            onMouseDown={openModal}
+          >
+            <text fg={t.muted} selectable={false}>
+              {`${icon} ${formatTokens(snap.tokens.total)}`}
+            </text>
+          </box>
         )
       })}
     </box>

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

@@ -0,0 +1,186 @@
+import type { AIUsageTool } from '@brimveyn/aimux-config'
+import type { ReactNode } from 'react'
+
+import type { UsagePaceStage, UsageSnapshot, UsageWindow } from '../../services/ai-usage/types'
+
+import { useAIUsageStore } from '../../state/ai-usage-store'
+import { useTokens } from '../theme'
+import { uiTokens } from '../ui-tokens'
+import { ModalShell } from './modal-shell'
+
+const TOOL_TITLE: Record<AIUsageTool, string> = {
+  claude: 'Claude',
+  codex: 'Codex',
+}
+
+const BAR_SEGMENTS = 32
+const BAR_FILLED_CHAR = '\u{2501}'
+const BAR_EMPTY_CHAR = '\u{2500}'
+
+function buildBar(percent: number | null): { empty: string; filled: string } {
+  const p = percent ?? 0
+  let filledCount = 0
+  for (let i = 0; i < BAR_SEGMENTS; i++) {
+    if (p > i * (100 / BAR_SEGMENTS)) filledCount++
+  }
+  return {
+    empty: BAR_EMPTY_CHAR.repeat(BAR_SEGMENTS - filledCount),
+    filled: BAR_FILLED_CHAR.repeat(filledCount),
+  }
+}
+
+function formatRelative(iso: string, now: number = Date.now()): string {
+  const diffMs = now - new Date(iso).getTime()
+  if (!Number.isFinite(diffMs) || diffMs < 0) return 'just now'
+  const s = Math.floor(diffMs / 1000)
+  if (s < 10) return 'just now'
+  if (s < 60) return `${s}s ago`
+  const m = Math.floor(s / 60)
+  if (m < 60) return `${m}m ago`
+  const h = Math.floor(m / 60)
+  if (h < 24) return `${h}h ago`
+  const d = Math.floor(h / 24)
+  return `${d}d ago`
+}
+
+function paceStageIsAhead(stage: UsagePaceStage): boolean {
+  return stage === 'ahead' || stage === 'farAhead' || stage === 'slightlyAhead'
+}
+
+function paceStageIsBehind(stage: UsagePaceStage): boolean {
+  return stage === 'behind' || stage === 'farBehind' || stage === 'slightlyBehind'
+}
+
+export function AIUsageModal() {
+  const t = useTokens()
+  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)
+
+  return (
+    <ModalShell
+      title="AI usage"
+      keybindsModeId="modal.ai-usage"
+      width={uiTokens.modalWidth.md}
+      listGap={1}
+    >
+      {sections.length === 0 ? (
+        <text fg={t.muted} 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>
+  )
+}
+
+interface ToolSectionProps {
+  snap: UsageSnapshot
+  tool: AIUsageTool
+}
+
+function ToolSection({ snap, tool }: ToolSectionProps) {
+  const t = useTokens()
+  const isHardError = Boolean(snap.error) && !snap.stale
+  const relative = formatRelative(snap.lastUpdated)
+
+  let body: ReactNode
+  if (isHardError) {
+    body = (
+      <text fg={t.palette.error} selectable={false}>
+        {`error: ${snap.error ?? ''}`}
+      </text>
+    )
+  } else if (snap.windows.length === 0) {
+    body = (
+      <text fg={t.muted} selectable={false}>
+        no window data
+      </text>
+    )
+  } else {
+    body = snap.windows.map((window) => <WindowRow key={window.kind} window={window} />)
+  }
+
+  return (
+    <box flexDirection="column">
+      <box flexDirection="row" justifyContent="space-between">
+        <text fg={t.accent} selectable={false}>
+          {TOOL_TITLE[tool]}
+        </text>
+        {snap.planTier ? (
+          <text fg={t.muted} selectable={false}>
+            {snap.planTier}
+          </text>
+        ) : null}
+      </box>
+      <text fg={t.muted} selectable={false}>
+        {`Updated ${relative}`}
+      </text>
+      {body}
+    </box>
+  )
+}
+
+function WindowRow({ window }: { window: UsageWindow }) {
+  const t = useTokens()
+  const percent = window.percent
+  const { empty, filled } = buildBar(percent)
+
+  let barColor = t.palette.success
+  if (percent !== null) {
+    if (percent >= 85) barColor = t.palette.error
+    else if (percent >= 60) barColor = t.palette.warning
+  }
+
+  const pctText = percent === null ? '—' : `${Math.round(percent)}% used`
+  const resetText = window.timeRemaining ? `Resets in ${window.timeRemaining}` : null
+
+  return (
+    <box flexDirection="column" paddingTop={1}>
+      <text fg={t.palette.ink} selectable={false}>
+        {window.label}
+      </text>
+      <box flexDirection="row">
+        <text fg={barColor} selectable={false}>
+          {filled}
+        </text>
+        <text fg={t.muted} selectable={false}>
+          {empty}
+        </text>
+      </box>
+      <box flexDirection="row" justifyContent="space-between">
+        <text fg={t.muted} selectable={false}>
+          {pctText}
+        </text>
+        {resetText ? (
+          <text fg={t.muted} selectable={false}>
+            {resetText}
+          </text>
+        ) : null}
+      </box>
+      {window.pace ? <PaceLine pace={window.pace} /> : null}
+    </box>
+  )
+}
+
+function PaceLine({ pace }: { pace: NonNullable<UsageWindow['pace']> }) {
+  const t = useTokens()
+  let color = t.muted
+  if (paceStageIsBehind(pace.stage)) color = t.palette.warning
+  else if (paceStageIsAhead(pace.stage)) color = t.palette.success
+
+  const suffix = pace.rightText ? ` · ${pace.rightText}` : ''
+  return (
+    <text fg={color} selectable={false}>
+      {`Pace: ${pace.label}${suffix}`}
+    </text>
+  )
+}

package/src/ui/root.tsx

@@ -8,7 +8,7 @@ import { useAppStore } from '../state/app-store'
 import { dispatchGlobal } from '../state/dispatch-ref'
 import { getGitPaneWidthFromRatio } from '../state/git-pane-sizing'
 import { getTreeForTab, PANE_BORDER, type SplitDirection } from '../state/layout-tree'
-import { AIUsagePopover } from './components/ai-usage-popover'
+import { AIUsageModal } from './components/ai-usage-modal'
 import { ContextMenuBox } from './components/context-menu-box'
 import { ContextMenuOverlay } from './components/context-menu-overlay'
 import { CreateSessionModal } from './components/create-session-modal'
@@ -172,6 +172,8 @@ function renderModal(
           cursorPos={modal.cursorPos}
         />
       )
+    case 'ai-usage':
+      return <AIUsageModal />
     case 'git-commit': {
       const titleText =
         modal.activeField === 'title' ? (modal.editBuffer ?? '') : modal.contentBuffer
@@ -279,7 +281,6 @@ export function RootView({
         <StatusBar />
         <PendingChordOverlay />
         <ContextMenuOverlay />
-        <AIUsagePopover />
         {renderModal(modal, {
           activeAssistant: activeTab?.assistant,
           createSessionFields,

package/src/ui/ai-usage/controller.ts

@@ -1,35 +0,0 @@
-export interface AIUsagePopoverState {
-  anchorX: number
-  anchorY: number
-}
-
-type Listener = (state: AIUsagePopoverState | null) => void
-
-let current: AIUsagePopoverState | null = null
-const listeners = new Set<Listener>()
-
-export function openAIUsagePopover(anchorX: number, anchorY: number): void {
-  current = { anchorX, anchorY }
-  for (const l of listeners) l(current)
-}
-
-export function closeAIUsagePopover(): void {
-  if (current === null) return
-  current = null
-  for (const l of listeners) l(null)
-}
-
-export function toggleAIUsagePopover(anchorX: number, anchorY: number): void {
-  if (current) {
-    closeAIUsagePopover()
-  } else {
-    openAIUsagePopover(anchorX, anchorY)
-  }
-}
-
-export function subscribeAIUsagePopover(listener: Listener): () => void {
-  listeners.add(listener)
-  return () => {
-    listeners.delete(listener)
-  }
-}

package/src/ui/components/ai-usage-popover.tsx

@@ -1,152 +0,0 @@
-import type { AIUsageTool } from '@brimveyn/aimux-config'
-
-import { useKeyboard } from '@opentui/react'
-import { useEffect, useState } from 'react'
-
-import type { UsageSnapshot } from '../../services/ai-usage/types'
-
-import { useAIUsageStore } from '../../state/ai-usage-store'
-import { useAppStore } from '../../state/app-store'
-import {
-  type AIUsagePopoverState,
-  closeAIUsagePopover,
-  subscribeAIUsagePopover,
-} from '../ai-usage/controller'
-import { useTokens } from '../theme'
-
-const TOOL_TITLE: Record<AIUsageTool, string> = {
-  claude: 'Claude Code',
-  codex: 'Codex',
-}
-
-const POPOVER_WIDTH = 38
-
-function fmt(n: number): string {
-  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(2)}M`
-  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`
-  return String(n)
-}
-
-function buildLines(snap: UsageSnapshot): string[] {
-  if (snap.error) {
-    return [`error: ${snap.error.slice(0, 30)}`]
-  }
-  const lines: string[] = []
-  if (snap.percent !== null) {
-    lines.push(`usage   ${snap.percent.toFixed(1)}%`)
-  }
-  lines.push(`tokens  in ${fmt(snap.tokens.input)} / out ${fmt(snap.tokens.output)}`)
-  if (snap.tokens.cache > 0) {
-    lines.push(`cache   ${fmt(snap.tokens.cache)}`)
-  }
-  lines.push(`total   ${fmt(snap.tokens.total)}`)
-  if (snap.costUSD !== null) {
-    lines.push(`cost    $${snap.costUSD.toFixed(2)}`)
-  }
-  if (snap.burnRatePerHour !== null) {
-    lines.push(`burn    ${fmt(Math.round(snap.burnRatePerHour))}/h`)
-  }
-  if (snap.timeRemaining) {
-    lines.push(`resets  ${snap.timeRemaining}`)
-  } else if (snap.resetAt) {
-    lines.push(`resets  ${new Date(snap.resetAt).toLocaleTimeString()}`)
-  }
-  return lines
-}
-
-export function AIUsagePopover() {
-  const [popover, setPopover] = useState<AIUsagePopoverState | null>(null)
-  const t = useTokens()
-  const enabled = useAIUsageStore((s) => s.enabled)
-  const snapshots = useAIUsageStore((s) => s.snapshots)
-  const terminalCols = useAppStore((s) => s.layout.terminalCols)
-  const terminalRows = useAppStore((s) => s.layout.terminalRows)
-
-  useEffect(() => subscribeAIUsagePopover(setPopover), [])
-
-  useKeyboard((key) => {
-    if (!popover) return
-    if (key.name === 'escape') {
-      key.preventDefault()
-      closeAIUsagePopover()
-    }
-  })
-
-  if (!enabled || !popover) return null
-
-  const tools: AIUsageTool[] = ['claude', 'codex']
-  const sections = tools
-    .map((tool) => ({ snap: snapshots[tool], tool }))
-    .filter((s) => s.snap !== undefined)
-
-  let bodyLines = 0
-  if (sections.length === 0) {
-    bodyLines = 1
-  } else {
-    for (const s of sections) {
-      if (!s.snap) continue
-      bodyLines += buildLines(s.snap).length + 2
-    }
-  }
-  const height = Math.min(terminalRows - 2, bodyLines + 2)
-  const width = Math.min(terminalCols - 2, POPOVER_WIDTH)
-
-  const left = Math.max(0, Math.min(popover.anchorX - width + 2, terminalCols - width))
-  const top = Math.max(0, popover.anchorY - height)
-
-  return (
-    <box position="absolute" top={0} left={0} width="100%" height="100%">
-      <box
-        position="absolute"
-        top={0}
-        left={0}
-        width="100%"
-        height="100%"
-        onMouseDown={(e) => {
-          e.preventDefault()
-          e.stopPropagation()
-          closeAIUsagePopover()
-        }}
-      />
-      <box
-        position="absolute"
-        top={top}
-        left={left}
-        width={width}
-        flexDirection="column"
-        border
-        borderColor={t.palette.primary}
-        backgroundColor={t.elevated}
-        onMouseDown={(e) => {
-          e.stopPropagation()
-        }}
-      >
-        {sections.length === 0 ? (
-          <box paddingLeft={1} paddingRight={1}>
-            <text fg={t.muted} selectable={false}>
-              no data yet — collecting…
-            </text>
-          </box>
-        ) : (
-          sections.map(({ snap, tool }, idx) => {
-            if (!snap) return null
-            const lines = buildLines(snap)
-            return (
-              <box key={tool} flexDirection="column" paddingLeft={1} paddingRight={1}>
-                {idx > 0 ? <text fg={t.muted}> </text> : null}
-                <text fg={t.accent} selectable={false}>
-                  {TOOL_TITLE[tool]}
-                </text>
-                {lines.map((line, i) => (
-                  <text key={`${tool}-${i}`} fg={t.palette.ink} selectable={false}>
-                    {line}
-                  </text>
-                ))}
-              </box>
-            )
-          })
-        )}
-      </box>
-    </box>
-  )
-}