@brimveyn/aimux 1.22.11 → 1.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.22.11",
+  "version": "1.23.0",
   "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",
@@ -66,7 +66,7 @@
     "bump:terminal_manager": "bun run scripts/bump-protocol.ts terminal-manager"
   },
   "dependencies": {
-    "@brimveyn/aimux-config": "0.10.0",
+    "@brimveyn/aimux-config": "0.10.2",
     "@opentui/core": "^0.1.90",
     "@opentui/react": "^0.1.90",
     "@resvg/resvg-wasm": "^2.6.2",

package/src/app-runtime/side-effects.ts

@@ -8,6 +8,7 @@ import { logInputDebug } from '../debug/input-log'
 import { enqueueGitOp } from '../git/command-queue'
 import { countDirtyFiles } from '../git/move-workspace'
 import { getCurrentBranch, getDefaultBranch, listLocalBranches } from '../git/worktree'
+import { countEffect } from '../services/aimux-counters/observe'
 import { allLeafIds, getGroupIdForTab } from '../state/layout-tree'
 import { saveCurrentProject } from '../state/project-save'
 import { getActiveWorkspace, getActiveWorkspacePath } from '../state/project-workspaces'
@@ -212,6 +213,10 @@ function hoistBranch(branches: string[], first: string | undefined): string[] {
 export function executeSideEffect(effect: SideEffect, ctx: SideEffectContext): void {
   const { backend, dispatch, state } = ctx
 
+  // Every effect path funnels through here, including the mouse and IPC ones,
+  // so this is the one place that sees them all.
+  countEffect(effect)
+
   switch (effect.type) {
     case 'quit': {
       saveCurrentProject(effect.state)

package/src/app-runtime/use-mouse-handlers.ts

@@ -12,6 +12,7 @@ import { logInputDebug } from '../debug/input-log'
 import { MultiClickDetector } from '../input/multi-click-detector'
 import { extractStreamText, getLineText } from '../input/terminal-text-extraction'
 import { copyToSystemClipboard } from '../platform/clipboard'
+import { bump } from '../services/aimux-counters'
 import {
   type ClickSelectionResult,
   computeRangeFromLineText,
@@ -306,6 +307,7 @@ export function useMouseHandlers({
       return
     }
 
+    bump('scrollLines', Math.abs(delta))
     backend.scrollViewport(targetTabId, delta)
   }
 

package/src/app.tsx

@@ -38,6 +38,7 @@ import { highlightSnapshot, warmClaudeSyntaxOverlay } from './integrations/claud
 import { ensureClaudeSettingsThemePref, syncClaudeTheme } from './integrations/claude-theme-sync'
 import { getProfileConfigDir, getProfileName } from './profile-paths'
 import { startAIUsageService } from './services/ai-usage/provider'
+import { bump } from './services/aimux-counters'
 import {
   useAIUsageConfig,
   useAutoCommitConfig,
@@ -553,6 +554,11 @@ export function App({
   }, [flashPendingJump])
 
   useKeyboard((key) => {
+    // Every key in every mode passes here, terminal-input included, which makes
+    // it the one honest place to count them. A count and nothing else — no key
+    // identity is recorded anywhere.
+    bump('keys')
+
     const currentState = stateRef.current
     // Global quit: Ctrl+C in any mode except terminal-input
     if (key.ctrl && key.name === 'c' && currentState.focusMode !== 'terminal-input') {

package/src/index.tsx

@@ -95,6 +95,7 @@ const [
   { createSessionBackend },
   { maybeAutoInstallCompletion },
   { maybeSpawnUsageRollup },
+  { startCounters },
 ] = await Promise.all([
   import('@opentui/react'),
   import('./app'),
@@ -104,6 +105,7 @@ const [
   import('./session-backend/bootstrap'),
   import('./cli/completion/install'),
   import('./services/usage-history/store'),
+  import('./services/aimux-counters'),
 ])
 const { resolved: resolvedConfig, user: userConfig } = await loadUserConfig()
 
@@ -119,6 +121,10 @@ maybeAutoInstallCompletion()
 // blocking. Opt out with AIMUX_NO_USAGE_ROLLUP=1.
 maybeSpawnUsageRollup()
 
+// Start counting what aimux knows about its own use — uptime, keystrokes,
+// workspaces, tabs. Local file, counts only, flushed on a timer and on exit.
+startCounters()
+
 const renderer = await createCliRenderer({
   autoFocus: true,
   // Transparent clear color so cells untouched by BoxRenderable paints (e.g.

package/src/input/keymap/help-entries.ts

@@ -12,6 +12,7 @@ export const HELP_MODE_LABELS: { modeId: ModeId; label: string }[] = [
   { label: 'Terminal input', modeId: 'terminal-input' },
   { label: 'Git mode', modeId: 'git-mode' },
   { label: 'Settings', modeId: 'settings' },
+  { label: 'Stats', modeId: 'stats' },
   { label: 'Git commit', modeId: 'modal.git-commit' },
   { label: 'New tab', modeId: 'modal.new-tab.command-edit' },
   { label: 'New tab — command', modeId: 'modal.new-tab.command-edit' },

package/src/input/modes/bridge.ts

@@ -7,6 +7,7 @@ const DIRECT_FOCUS_MODE_IDS: Partial<Record<FocusMode, ModeId>> = {
   'git': 'git-mode',
   'navigation': 'navigation',
   'settings': 'settings',
+  'stats': 'stats',
   'terminal-input': 'terminal-input',
 }
 
@@ -29,7 +30,7 @@ const COMMAND_EDIT_MODE_IDS: Partial<Record<SupportedModalType, ModeId>> = {
 }
 
 const MODAL_MODE_IDS: Partial<Record<SupportedModalType, ModeId>> = {
-  'ai-usage': 'modal.ai-usage',
+  'quotas': 'modal.quotas',
   'update-available': 'modal.update-available',
   'workspace-delete-confirm': 'modal.workspace-delete-confirm',
   'workspace-move': 'modal.workspace-move',

package/src/input/modes/transitions.ts

@@ -2,7 +2,6 @@ import type { ModeId } from './types'
 
 const TRANSITIONS: Record<ModeId, readonly ModeId[]> = {
   'git-mode': ['navigation', 'modal.git-commit', 'modal.workspace-move'],
-  'modal.ai-usage': ['navigation', 'terminal-input'],
   'modal.create-project': ['navigation', 'modal.project-picker.filtering'],
   'modal.create-workspace': ['navigation', 'terminal-input'],
   'modal.flash-jump': ['navigation'],
@@ -14,6 +13,7 @@ const TRANSITIONS: Record<ModeId, readonly ModeId[]> = {
   'modal.new-tab.editing-command': ['navigation', 'modal.new-tab.command-edit'],
   'modal.project-name': ['modal.project-picker.filtering', 'navigation'],
   'modal.project-picker.filtering': ['navigation', 'modal.project-name', 'modal.create-project'],
+  'modal.quotas': ['navigation', 'terminal-input'],
   'modal.rename-tab': ['navigation'],
   'modal.rename-workspace': ['navigation'],
   'modal.setting-text': ['settings'],
@@ -40,12 +40,13 @@ const TRANSITIONS: Record<ModeId, readonly ModeId[]> = {
     'modal.rename-tab',
     'modal.rename-workspace',
     'modal.update-available',
-    'modal.ai-usage',
+    'modal.quotas',
     'modal.workspace-delete-confirm',
     'modal.workspace-move-confirm',
     'modal.flash-jump',
     'git-mode',
     'settings',
+    'stats',
   ],
   // The help overlay opens over settings without a transition (it leaves
   // focusMode alone). The two pickers an action row hands over to are dispatched
@@ -58,7 +59,10 @@ const TRANSITIONS: Record<ModeId, readonly ModeId[]> = {
     'modal.theme-picker.filtering',
     'modal.snippet-picker.filtering',
   ],
-  'terminal-input': ['navigation', 'modal.split-picker', 'modal.ai-usage', 'settings'],
+  // Read-only screen: the only way out is back to the panes. The help overlay
+  // opens on top of it without a transition, the same way it does over settings.
+  'stats': ['navigation'],
+  'terminal-input': ['navigation', 'modal.split-picker', 'modal.quotas', 'settings', 'stats'],
 }
 
 export function isValidTransition(from: ModeId, to: ModeId): boolean {

package/src/input/modes/types.ts

@@ -30,9 +30,10 @@ export type ModeId =
   | 'modal.update-available'
   | 'modal.workspace-move'
   | 'modal.workspace-move-confirm'
-  | 'modal.ai-usage'
   | 'modal.flash-jump'
+  | 'modal.quotas'
   | 'settings'
+  | 'stats'
 
 export type SideEffect =
   | { type: 'quit'; state: AppState }

package/src/restart-daemon.ts

@@ -6,8 +6,13 @@ import {
   spawnDaemonReexec,
   spawnDetachedIpcDaemon,
 } from './platform/daemon-control'
+import { recordOnce } from './services/aimux-counters'
 
 export async function runRestartDaemon(): Promise<number> {
+  // Written immediately: this runs as its own short-lived process, so there is
+  // no flush loop to hand it to.
+  recordOnce('daemonRestarts')
+
   const socketPath = getDaemonSocketPath()
   const pid = await findIpcDaemonPid()
 

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

@@ -0,0 +1,44 @@
+import type { UsageWindow } from './types'
+
+/**
+ * Where a quota window lands if the current rate holds.
+ *
+ * Pure, and derived only from what the provider already reports: `percent`,
+ * `windowSeconds` and `resetAt` give the elapsed fraction, which is all a linear
+ * projection needs. Nothing here parses `timeRemaining` — that is a display
+ * string, and a projection built on parsing one breaks the day its wording does.
+ */
+
+export type ProjectionVerdict =
+  /** The window resets before the quota runs out at this rate. */
+  | { kind: 'lasts' }
+  /** Not enough of the window has elapsed to say anything honest. */
+  | { kind: 'unknown' }
+  | { kind: 'exhausted'; at: Date }
+
+/** Below this, one burst early in a window projects to nonsense. */
+const MIN_ELAPSED_FRACTION = 0.05
+
+export function projectWindow(window: UsageWindow, now: Date): ProjectionVerdict {
+  const { percent, resetAt, windowSeconds } = window
+  if (percent === null || resetAt === null || windowSeconds === null || windowSeconds <= 0) {
+    return { kind: 'unknown' }
+  }
+
+  const resetMs = Date.parse(resetAt)
+  if (!Number.isFinite(resetMs)) return { kind: 'unknown' }
+
+  const remainingSeconds = (resetMs - now.getTime()) / 1000
+  const elapsedSeconds = windowSeconds - remainingSeconds
+  if (remainingSeconds <= 0) return { kind: 'unknown' }
+  if (elapsedSeconds / windowSeconds < MIN_ELAPSED_FRACTION) return { kind: 'unknown' }
+
+  if (percent >= 100) return { at: now, kind: 'exhausted' }
+  const perSecond = percent / elapsedSeconds
+  if (perSecond <= 0) return { kind: 'lasts' }
+
+  const secondsToFull = (100 - percent) / perSecond
+  if (secondsToFull >= remainingSeconds) return { kind: 'lasts' }
+
+  return { at: new Date(now.getTime() + secondsToFull * 1000), kind: 'exhausted' }
+}

package/src/services/aimux-counters/index.ts

@@ -0,0 +1,87 @@
+import {
+  type CounterDeltas,
+  type CounterKey,
+  type MaxCounters,
+  saveCounters,
+  todayKey,
+} from './store'
+
+/**
+ * The write side of the aimux counters: accumulate in memory, fold into the file
+ * on a timer.
+ *
+ * `bump` is on the keystroke path, so it does nothing but add to a plain object —
+ * no date formatting, no I/O, no allocation.
+ */
+
+const FLUSH_INTERVAL_MS = 30_000
+
+let pending: CounterDeltas = {}
+let flushTimer: ReturnType<typeof setInterval> | null = null
+let runStartMs = 0
+let lastAccrualMs = 0
+
+export function bump(key: CounterKey, amount = 1): void {
+  if (amount === 0) return
+  pending[key] = (pending[key] ?? 0) + amount
+}
+
+/**
+ * Folds everything pending into the file.
+ *
+ * On failure the pending deltas are kept rather than dropped, so a transient
+ * write error costs a flush interval instead of the counts.
+ *
+ * ponytail: the whole batch is attributed to the day it is flushed on, so up to
+ * one interval of activity can land on the wrong side of midnight. Per-bump day
+ * resolution would fix it and would put a date format on the keystroke path;
+ * tighten it only if a day boundary ever matters more than that.
+ */
+export function flushCounters(now = Date.now()): void {
+  if (runStartMs === 0) return
+
+  const elapsed = Math.max(0, now - lastAccrualMs)
+  const deltas: CounterDeltas = { ...pending }
+  if (elapsed > 0) deltas.uptimeMs = (deltas.uptimeMs ?? 0) + elapsed
+  const maxima: MaxCounters = { longestRunMs: now - runStartMs }
+
+  // `elapsed` is already folded into `deltas` above, so this covers the idle
+  // case too: nothing pending and no time accrued means nothing to write.
+  if (!Object.values(deltas).some((value) => value !== 0)) return
+
+  if (saveCounters(todayKey(new Date(now)), deltas, maxima)) {
+    pending = {}
+    lastAccrualMs = now
+  }
+}
+
+/** Starts the flush loop and arranges a final flush on exit. Safe to call twice. */
+export function startCounters(now = Date.now()): void {
+  if (flushTimer !== null) return
+  runStartMs = now
+  lastAccrualMs = now
+  bump('runsStarted')
+
+  flushTimer = setInterval(() => {
+    flushCounters()
+  }, FLUSH_INTERVAL_MS)
+  // Never hold the process open for a counter.
+  flushTimer.unref?.()
+
+  // Synchronous write, which is the only kind `exit` can run. A SIGKILL still
+  // costs at most one interval.
+  process.on('exit', () => {
+    flushCounters()
+  })
+}
+
+/**
+ * Records one increment and writes it straight away.
+ *
+ * For the short-lived CLI subcommands (`aimux restart-daemon`), which have no
+ * flush loop and exit before any timer would fire. The write is additive like
+ * every other, so it composes with a TUI running at the same time.
+ */
+export function recordOnce(key: CounterKey, amount = 1, now = Date.now()): void {
+  saveCounters(todayKey(new Date(now)), { [key]: amount }, {})
+}

package/src/services/aimux-counters/observe.ts

@@ -0,0 +1,39 @@
+import type { SideEffect } from '../../input/modes/types'
+import type { AppAction } from '../../state/actions'
+
+import { bump } from './index'
+
+/**
+ * Translates dispatched actions and side effects into counters.
+ *
+ * One place rather than a `bump()` sprinkled through the reducers: reducers stay
+ * pure, and what aimux counts about itself is readable in a single switch
+ * instead of being spread across the state layer.
+ */
+
+export function countAction(action: AppAction): void {
+  switch (action.type) {
+    case 'add-tab':
+      bump('tabsOpened')
+      break
+    case 'add-workspace-record':
+      bump('workspacesCreated')
+      break
+    case 'split-pane':
+      bump(action.direction === 'vertical' ? 'splitsVertical' : 'splitsHorizontal')
+      break
+    default:
+      break
+  }
+}
+
+export function countEffect(effect: SideEffect): void {
+  switch (effect.type) {
+    case 'paste-selected-snippet':
+    case 'paste-snippet-to-group':
+      bump('snippetsFired')
+      break
+    default:
+      break
+  }
+}

package/src/services/aimux-counters/store.ts

@@ -0,0 +1,150 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { logDebug } from '../../debug/input-log'
+import { localDay } from '../usage-history/store'
+
+/**
+ * What aimux knows about its own use, per local calendar day.
+ *
+ * Deliberately counts and nothing else. `keys` is a number of key presses with
+ * no key identity and no content attached — which is also why there is no
+ * per-keybind breakdown: that would mean recording *which* key, a different
+ * privacy posture for a stat nobody asked for.
+ *
+ * Nothing here leaves the machine.
+ */
+
+export const COUNTERS_VERSION = 1
+const UNREADABLE_VERSION = -1
+
+export type CounterKey =
+  | 'daemonRestarts'
+  | 'keys'
+  /** aimux launches. Distinct from `tabsOpened`: a tab is a session inside one run. */
+  | 'runsStarted'
+  | 'scrollLines'
+  | 'snippetsFired'
+  | 'splitsHorizontal'
+  | 'splitsVertical'
+  | 'tabsOpened'
+  | 'uptimeMs'
+  | 'workspacesCreated'
+
+/**
+ * Counters that take the larger of the two values instead of the sum.
+ *
+ * `longestRunMs` is the length of a single uninterrupted aimux run, so adding
+ * two instances' values would invent a run neither of them had.
+ */
+export type MaxCounterKey = 'longestRunMs'
+
+export type CounterDeltas = Partial<Record<CounterKey, number>>
+export type MaxCounters = Partial<Record<MaxCounterKey, number>>
+
+export type CounterDay = Partial<Record<CounterKey | MaxCounterKey, number>>
+/** 'YYYY-MM-DD' in the machine's local calendar -> that day's counters. */
+export type CounterDays = Record<string, CounterDay>
+
+export interface CountersFile {
+  days: CounterDays
+  version: number
+}
+
+const MAX_KEYS: readonly MaxCounterKey[] = ['longestRunMs']
+
+function isMaxKey(key: string): key is MaxCounterKey {
+  return (MAX_KEYS as readonly string[]).includes(key)
+}
+
+/** Resolved per call, not at module scope, so a `HOME` override in tests reaches it. */
+export function countersPath(): string {
+  const home = process.env.HOME ?? homedir()
+  return join(home, '.config', 'aimux', 'usage-counters.json')
+}
+
+export function readCounters(): CountersFile {
+  let raw: string
+  try {
+    raw = readFileSync(countersPath(), 'utf8')
+  } catch {
+    return { days: {}, version: COUNTERS_VERSION } // no file yet; safe to create
+  }
+
+  try {
+    const file = JSON.parse(raw) as Partial<CountersFile>
+    if (typeof file.version !== 'number') return { days: {}, version: UNREADABLE_VERSION }
+    if (typeof file.days !== 'object' || file.days === null) {
+      return { days: {}, version: UNREADABLE_VERSION }
+    }
+    return { days: file.days, version: file.version }
+  } catch {
+    return { days: {}, version: UNREADABLE_VERSION }
+  }
+}
+
+/**
+ * Folds one day's pending changes into what is already on disk.
+ *
+ * Additive for every ordinary counter, which is what makes two aimux instances
+ * safe to run at once: each flush contributes its own delta rather than
+ * overwriting a total it computed from a stale read.
+ */
+export function mergeCounterDay(
+  stored: CounterDay | undefined,
+  deltas: CounterDeltas,
+  maxima: MaxCounters
+): CounterDay {
+  const merged: CounterDay = { ...stored }
+  for (const [key, value] of Object.entries(deltas)) {
+    if (value === 0) continue
+    merged[key as CounterKey] = (merged[key as CounterKey] ?? 0) + value
+  }
+  for (const [key, value] of Object.entries(maxima)) {
+    if (!isMaxKey(key)) continue
+    merged[key] = Math.max(merged[key] ?? 0, value)
+  }
+  return merged
+}
+
+/**
+ * False when nothing was written. The caller keeps its pending deltas in that
+ * case, so a transient failure costs a flush interval rather than the counts.
+ */
+export function saveCounters(day: string, deltas: CounterDeltas, maxima: MaxCounters): boolean {
+  const stored = readCounters()
+
+  // Same posture as the usage history: a newer aimux owns a shape this build
+  // cannot round-trip, and an unreadable file may hold counts nothing can
+  // regenerate. Neither gets written over.
+  if (stored.version > COUNTERS_VERSION || stored.version < 1) {
+    logDebug('counters.refusedWrite', { version: stored.version })
+    return false
+  }
+
+  const path = countersPath()
+  const file: CountersFile = {
+    days: { ...stored.days, [day]: mergeCounterDay(stored.days[day], deltas, maxima) },
+    version: COUNTERS_VERSION,
+  }
+
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    // pid-suffixed: two instances can flush 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('counters.writeError', {
+      error: error instanceof Error ? error.message : String(error),
+    })
+    return false
+  }
+}
+
+export function todayKey(now: Date = new Date()): string {
+  return localDay(now)
+}

package/src/services/aimux-counters/summary.ts

@@ -0,0 +1,78 @@
+import type { CounterDays, CounterKey, MaxCounterKey } from './store'
+
+import { localDay } from '../usage-history/store'
+
+/** Pure shaping of the stored counter days into what the aimux page renders. */
+
+export interface CounterPeak {
+  day: string
+  value: number
+}
+
+export interface CounterSummary {
+  best: CounterPeak
+  today: number
+  total: number
+  /** Days carrying a non-zero value — the denominator for a daily average. */
+  days: number
+}
+
+export function summarizeCounter(
+  days: CounterDays,
+  key: CounterKey,
+  today: string
+): CounterSummary {
+  let best: CounterPeak = { day: '', value: 0 }
+  let dayCount = 0
+  let total = 0
+
+  for (const [date, day] of Object.entries(days)) {
+    const value = day[key] ?? 0
+    if (value <= 0) continue
+    dayCount += 1
+    total += value
+    if (value > best.value) best = { day: date, value }
+  }
+
+  return { best, days: dayCount, today: days[today]?.[key] ?? 0, total }
+}
+
+/**
+ * The largest value ever recorded for a max-merged counter.
+ *
+ * Not a sum: `longestRunMs` is the length of one uninterrupted aimux run, so the
+ * answer across days is the biggest of them, never their total.
+ */
+export function peakOf(days: CounterDays, key: MaxCounterKey): CounterPeak {
+  let best: CounterPeak = { day: '', value: 0 }
+  for (const [date, day] of Object.entries(days)) {
+    const value = day[key] ?? 0
+    if (value > best.value) best = { day: date, value }
+  }
+  return best
+}
+
+/**
+ * One value per calendar day for the `count` days ending today, oldest first.
+ *
+ * The counters' twin of `lastDays` over the usage history, and unrecorded days
+ * are zero for the same reason: a day aimux never ran is a real zero, not a hole.
+ */
+export function lastCounterDays(
+  days: CounterDays,
+  count: number,
+  today: Date,
+  key: CounterKey | MaxCounterKey
+): number[] {
+  return Array.from({ length: count }, (_, index) => {
+    const date = new Date(today)
+    date.setDate(date.getDate() - (count - 1 - index))
+    return days[localDay(date)]?.[key] ?? 0
+  })
+}
+
+export function sumOf(days: CounterDays, key: CounterKey): number {
+  let total = 0
+  for (const day of Object.values(days)) total += day[key] ?? 0
+  return total
+}