diff --git a/frontend/src/components/ProjectSessionList.tsx b/frontend/src/components/ProjectSessionList.tsx
index 79624d17..081f96c4 100644
--- a/frontend/src/components/ProjectSessionList.tsx
+++ b/frontend/src/components/ProjectSessionList.tsx
@@ -1,5 +1,5 @@
 import { useState, useEffect, useMemo, useCallback, useRef, useId } from 'react';
-import { ChevronDown, ChevronRight, Plus, FolderPlus, GitBranch, MoreHorizontal, Home, Archive, ArchiveRestore, Trash2, GitPullRequest, Pin, Monitor, MessageSquare } from 'lucide-react';
+import { ChevronDown, ChevronRight, Plus, FolderPlus, GitBranch, MoreHorizontal, Home, Archive, ArchiveRestore, Trash2, GitPullRequest, Pin, Monitor, MessageSquare, BarChart3 } from 'lucide-react';
 import { SessionDetailTooltip } from './SessionDetailTooltip';
 import { useSessionStore } from '../stores/sessionStore';
 import { useNavigationStore } from '../stores/navigationStore';
@@ -81,6 +81,7 @@ export function ProjectSessionList({
   const navigateToPaneChat = useNavigationStore(s => s.navigateToPaneChat);
   const paneChatStatus = useSessionAgentDisplayStatus(PANE_CHAT_SESSION_ID);
   const navigateToProject = useNavigationStore(s => s.navigateToProject);
+  const navigateToUsage = useNavigationStore(s => s.navigateToUsage);
   const setSidebarNavigationScope = useNavigationStore(s => s.setSidebarNavigationScope);
   // Expansion state lives in the navigation store so the always-mounted
   // session hotkeys (useSessionNavigationHotkeys) see the same visible ordering
@@ -314,6 +315,27 @@ export function ProjectSessionList({
           <AgentStatusDot status={paneChatStatus} size="sm" className="ml-auto" />
         </button>
 
+        <button
+          type="button"
+          data-testid="usage-nav"
+          onClick={() => {
+            setSidebarNavigationScope('repositories');
+            navigateToUsage();
+          }}
+          className={cn(
+            SIDEBAR_ROW_BASE,
+            SIDEBAR_ROW_GAP,
+            SIDEBAR_ROW_PADDING,
+            'py-2 text-sm hover:bg-surface-hover hover:text-text-primary',
+            activeView === 'usage'
+              ? 'bg-surface-hover text-text-primary'
+              : 'text-text-secondary',
+          )}
+        >
+          <BarChart3 className="w-4 h-4" />
+          <span>Usage &amp; Limits</span>
+        </button>
+
         {showRemoteDesktopLink && onRemoteDesktopClick && (
           <Tooltip content={remoteDesktopTooltip} side="right" className="block w-full">
             <button
diff --git a/frontend/src/components/SessionView.tsx b/frontend/src/components/SessionView.tsx
index fcc03f07..6fd6a378 100644
--- a/frontend/src/components/SessionView.tsx
+++ b/frontend/src/components/SessionView.tsx
@@ -15,6 +15,7 @@ import { CommitMessageDialog } from './session/CommitMessageDialog';
 import { FolderArchiveDialog } from './session/FolderArchiveDialog';
 import { ConfirmDialog } from './ConfirmDialog';
 import { ProjectView } from './ProjectView';
+import { UsageView } from './usage/UsageView';
 import { API } from '../utils/api';
 import { useResizable } from '../hooks/useResizable';
 import { useResizableHeight } from '../hooks/useResizableHeight';
@@ -1651,6 +1652,11 @@ export const SessionView = memo(() => {
   
   // Removed unused variables - now handled by panels
 
+  // Token usage, cost and rate limits — reported per host.
+  if (activeView === 'usage') {
+    return <UsageView />;
+  }
+
   // Show project view if navigation is set to project
   if (activeView === 'project' && activeProjectId) {
     if (isProjectLoading || !projectData) {
diff --git a/frontend/src/components/Sidebar.tsx b/frontend/src/components/Sidebar.tsx
index ef285cc1..85edc30e 100644
--- a/frontend/src/components/Sidebar.tsx
+++ b/frontend/src/components/Sidebar.tsx
@@ -3,7 +3,7 @@ import { createPortal } from 'react-dom';
 import { CreateSessionDialog } from './CreateSessionDialog';
 import { ProjectSessionList, ArchivedSessions } from './ProjectSessionList';
 import { ArchiveProgress } from './ArchiveProgress';
-import { ArrowUpDown, ChevronDown, ChevronRight, Cpu, FolderGit2, Home, Monitor, MoreHorizontal, PanelLeftClose, PanelLeftOpen, Pin, Settings as SettingsIcon, Plus, RefreshCw, MessageSquare } from 'lucide-react';
+import { ArrowUpDown, ChevronDown, ChevronRight, Cpu, FolderGit2, Home, Monitor, MoreHorizontal, PanelLeftClose, PanelLeftOpen, Pin, Settings as SettingsIcon, Plus, RefreshCw, MessageSquare, BarChart3 } from 'lucide-react';
 import { SessionDetailTooltip } from './SessionDetailTooltip';
 import { usePaneLogo } from '../hooks/usePaneLogo';
 import { isMac } from '../utils/platformUtils';
@@ -380,6 +380,7 @@ export function Sidebar({ onAboutClick, onSettingsClick, onRemoteSettingsClick,
   const navigateToProject = useNavigationStore((state) => state.navigateToProject);
   const navigateToSessions = useNavigationStore((state) => state.navigateToSessions);
   const navigateToPaneChat = useNavigationStore((state) => state.navigateToPaneChat);
+  const navigateToUsage = useNavigationStore((state) => state.navigateToUsage);
   const paneChatStatus = useSessionAgentDisplayStatus(PANE_CHAT_SESSION_ID);
   const setSidebarNavigationScope = useNavigationStore((state) => state.setSidebarNavigationScope);
   const agentStatusByPanel = usePanelStore((state) => state.agentStatus);
@@ -493,6 +494,22 @@ export function Sidebar({ onAboutClick, onSettingsClick, onRemoteSettingsClick,
               </button>
             </Tooltip>
 
+            <Tooltip content="Usage & Limits" side="right">
+              <button
+                type="button"
+                data-testid="compact-usage"
+                data-compact-rail-item
+                onClick={() => {
+                  setSidebarNavigationScope('repositories');
+                  navigateToUsage();
+                }}
+                aria-label="Usage and Limits"
+                className={`${COMPACT_RAIL_BUTTON} ${activeView === 'usage' ? COMPACT_RAIL_ACTIVE : COMPACT_RAIL_IDLE}`}
+              >
+                <BarChart3 className="h-4 w-4" />
+              </button>
+            </Tooltip>
+
             {showRemoteDesktopLink && (
               <Tooltip content={REMOTE_DESKTOP_TOOLTIP} side="right">
                 <button
diff --git a/frontend/src/components/ui/charts/AreaChart.tsx b/frontend/src/components/ui/charts/AreaChart.tsx
new file mode 100644
index 00000000..f72b8dcb
--- /dev/null
+++ b/frontend/src/components/ui/charts/AreaChart.tsx
@@ -0,0 +1,273 @@
+import { useCallback, useId, useMemo, useRef, useState } from 'react';
+import { linearScale, niceMax, niceTicks } from './chartScales';
+
+export interface AreaSeries {
+  label: string;
+  color: string;
+  /** One value per point, aligned with `labels`. */
+  values: number[];
+}
+
+export interface AreaChartProps {
+  labels: string[];
+  series: AreaSeries[];
+  /** Formats y-axis ticks, tooltip values and the accessible summary. */
+  formatValue: (value: number) => string;
+  height?: number;
+  /** Sentence describing the data for screen readers. */
+  ariaLabel: string;
+  /** Stack series on top of each other instead of overlaying them. */
+  stacked?: boolean;
+}
+
+const PADDING = { top: 8, right: 8, bottom: 20, left: 44 };
+const VIEW_WIDTH = 640;
+
+/**
+ * Stacked or overlaid area chart drawn as plain SVG, with a hover readout.
+ *
+ * Accessibility: the `<svg>` is a single `role="img"` with a summarising
+ * label rather than a grid of focusable points — there is nothing to activate,
+ * so exposing hundreds of tab stops would only get in the way. The hover
+ * readout is a pointer convenience on top of that, not the only route to the
+ * numbers; the page states its totals in text as well.
+ */
+export function AreaChart({
+  labels,
+  series,
+  formatValue,
+  height = 200,
+  ariaLabel,
+  stacked = true,
+}: AreaChartProps) {
+  const gradientId = useId();
+  const containerRef = useRef<HTMLDivElement>(null);
+  /** Index of the point under the pointer, or null when the pointer is away. */
+  const [hoverIndex, setHoverIndex] = useState<number | null>(null);
+  const innerWidth = VIEW_WIDTH - PADDING.left - PADDING.right;
+  const innerHeight = height - PADDING.top - PADDING.bottom;
+
+  const { paths, ticks, max, stackedTops } = useMemo(() => {
+    const pointCount = labels.length;
+    if (pointCount === 0 || series.length === 0) {
+      return {
+        paths: [] as Array<{ area: string; line: string; color: string }>,
+        ticks: [0, 1],
+        max: 1,
+        stackedTops: [] as number[][],
+      };
+    }
+
+    // Running baseline per x position; stays at zero when not stacking.
+    const baseline = new Array<number>(pointCount).fill(0);
+    const tops: number[][] = [];
+
+    for (const entry of series) {
+      const seriesTops = entry.values.map((value, index) => (stacked ? baseline[index] + value : value));
+      if (stacked) seriesTops.forEach((top, index) => { baseline[index] = top; });
+      tops.push(seriesTops);
+    }
+
+    const peak = Math.max(1, ...tops.flat());
+    const axisMax = niceMax(peak);
+
+    const x = (index: number) =>
+      pointCount === 1
+        ? PADDING.left + innerWidth / 2
+        : linearScale(index, 0, pointCount - 1, PADDING.left, PADDING.left + innerWidth);
+    const y = (value: number) =>
+      linearScale(value, 0, axisMax, PADDING.top + innerHeight, PADDING.top);
+
+    const built = series.map((entry, seriesIndex) => {
+      const seriesTops = tops[seriesIndex];
+      const bottoms = stacked
+        ? (seriesIndex === 0 ? new Array<number>(pointCount).fill(0) : tops[seriesIndex - 1])
+        : new Array<number>(pointCount).fill(0);
+
+      const line = seriesTops
+        .map((value, index) => `${index === 0 ? 'M' : 'L'} ${x(index)} ${y(value)}`)
+        .join(' ');
+      const back = bottoms
+        .map((value, index) => ({ value, index }))
+        .reverse()
+        .map(({ value, index }) => `L ${x(index)} ${y(value)}`)
+        .join(' ');
+
+      return { area: `${line} ${back} Z`, line, color: entry.color };
+    });
+
+    return { paths: built, ticks: niceTicks(peak), max: axisMax, stackedTops: tops };
+  }, [labels, series, stacked, innerHeight, innerWidth]);
+
+  /**
+   * Snap the pointer to the nearest data point.
+   *
+   * The SVG is stretched to its box, so the maths goes through the rendered
+   * rect rather than the viewBox: fraction across the element, back into
+   * viewBox units, then invert the x scale. Bound on the wrapping element so
+   * the whole card responds — chasing a 1.5px line with the mouse is not a
+   * reading experience.
+   */
+  const handlePointer = useCallback((clientX: number) => {
+    const rect = containerRef.current?.getBoundingClientRect();
+    if (!rect || rect.width === 0 || labels.length === 0) return;
+
+    const viewX = ((clientX - rect.left) / rect.width) * VIEW_WIDTH;
+    const ratio = labels.length === 1 ? 0 : (viewX - PADDING.left) / innerWidth;
+    const index = Math.round(ratio * (labels.length - 1));
+    setHoverIndex(Math.min(Math.max(index, 0), labels.length - 1));
+  }, [labels.length, innerWidth]);
+
+  if (labels.length === 0) {
+    return (
+      <p className="py-8 text-center text-xs text-text-muted">No data in this range.</p>
+    );
+  }
+
+  const hoverX = hoverIndex === null
+    ? 0
+    : labels.length === 1
+      ? PADDING.left + innerWidth / 2
+      : linearScale(hoverIndex, 0, labels.length - 1, PADDING.left, PADDING.left + innerWidth);
+  /** Keep the tooltip inside the box when hovering near the right edge. */
+  const tooltipOnLeft = hoverX > PADDING.left + innerWidth * 0.6;
+
+  return (
+    <div
+      ref={containerRef}
+      className="relative"
+      onPointerMove={event => handlePointer(event.clientX)}
+      onPointerLeave={() => setHoverIndex(null)}
+    >
+      <svg
+        viewBox={`0 0 ${VIEW_WIDTH} ${height}`}
+        className="h-auto w-full"
+        role="img"
+        aria-label={ariaLabel}
+        preserveAspectRatio="none"
+      >
+        <defs>
+          {paths.map((path, index) => (
+            <linearGradient key={index} id={`${gradientId}-${index}`} x1="0" y1="0" x2="0" y2="1">
+              <stop offset="0%" stopColor={path.color} stopOpacity={0.45} />
+              <stop offset="100%" stopColor={path.color} stopOpacity={0.05} />
+            </linearGradient>
+          ))}
+        </defs>
+
+        {/* Gridlines and y-axis labels */}
+        {ticks.map(tick => {
+          const y = linearScale(tick, 0, max, PADDING.top + innerHeight, PADDING.top);
+          return (
+            <g key={tick}>
+              <line
+                x1={PADDING.left}
+                y1={y}
+                x2={PADDING.left + innerWidth}
+                y2={y}
+                stroke="currentColor"
+                strokeWidth={0.5}
+                className="text-border-secondary"
+                opacity={0.5}
+              />
+              <text
+                x={PADDING.left - 6}
+                y={y + 3}
+                textAnchor="end"
+                className="fill-current text-text-muted"
+                style={{ fontSize: 9 }}
+              >
+                {formatValue(tick)}
+              </text>
+            </g>
+          );
+        })}
+
+        {paths.map((path, index) => (
+          <g key={index}>
+            <path d={path.area} fill={`url(#${gradientId}-${index})`} />
+            <path d={path.line} fill="none" stroke={path.color} strokeWidth={1.5} />
+          </g>
+        ))}
+
+        {/* Crosshair on the hovered point, with a dot where each line runs */}
+        {hoverIndex !== null && (
+          <g pointerEvents="none">
+            <line
+              x1={hoverX}
+              y1={PADDING.top}
+              x2={hoverX}
+              y2={PADDING.top + innerHeight}
+              stroke="currentColor"
+              strokeWidth={0.75}
+              className="text-text-muted"
+            />
+            {series.map((entry, index) => (
+              <circle
+                key={entry.label}
+                cx={hoverX}
+                cy={linearScale(
+                  stackedTops[index]?.[hoverIndex] ?? 0,
+                  0,
+                  max,
+                  PADDING.top + innerHeight,
+                  PADDING.top
+                )}
+                r={2}
+                fill={entry.color}
+              />
+            ))}
+          </g>
+        )}
+
+        {/* First and last x labels only — a dense axis is unreadable at this size */}
+        <text x={PADDING.left} y={height - 6} className="fill-current text-text-muted" style={{ fontSize: 9 }}>
+          {labels[0]}
+        </text>
+        {labels.length > 1 && (
+          <text
+            x={PADDING.left + innerWidth}
+            y={height - 6}
+            textAnchor="end"
+            className="fill-current text-text-muted"
+            style={{ fontSize: 9 }}
+          >
+            {labels[labels.length - 1]}
+          </text>
+        )}
+      </svg>
+
+      {/*
+        Tooltip as HTML rather than SVG text: the chart stretches to fit its box
+        and anything inside the viewBox stretches with it, type included.
+      */}
+      {hoverIndex !== null && (
+        <div
+          className="pointer-events-none absolute top-1 z-10 min-w-[9rem] rounded border border-border-primary bg-surface-primary/95 px-2 py-1.5 shadow-lg"
+          style={tooltipOnLeft
+            ? { right: `${(1 - hoverX / VIEW_WIDTH) * 100 + 2}%` }
+            : { left: `${(hoverX / VIEW_WIDTH) * 100 + 2}%` }}
+        >
+          <p className="mb-1 text-[10px] font-medium text-text-primary">{labels[hoverIndex]}</p>
+          <ul className="space-y-0.5">
+            {series.map(entry => (
+              <li key={entry.label} className="flex items-center gap-1.5 text-[10px] text-text-secondary">
+                <span
+                  className="h-1.5 w-1.5 flex-shrink-0 rounded-sm"
+                  style={{ backgroundColor: entry.color }}
+                  aria-hidden="true"
+                />
+                <span className="flex-1 truncate">{entry.label}</span>
+                <span className="tabular-nums text-text-primary">
+                  {formatValue(entry.values[hoverIndex] ?? 0)}
+                </span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default AreaChart;
diff --git a/frontend/src/components/ui/charts/BarChart.tsx b/frontend/src/components/ui/charts/BarChart.tsx
new file mode 100644
index 00000000..243f841d
--- /dev/null
+++ b/frontend/src/components/ui/charts/BarChart.tsx
@@ -0,0 +1,111 @@
+import { linearScale, niceMax } from './chartScales';
+
+export interface BarDatum {
+  label: string;
+  value: number;
+  color: string;
+  /** Optional secondary text shown at the right of the row. */
+  detail?: string;
+  /** Small chip before the label, e.g. the provider. */
+  tag?: string;
+  /** Share of the total, 0-1, rendered next to the value. */
+  share?: number;
+  /** Hover text for the label — full path, or why a detail reads "n/a". */
+  title?: string;
+  /** Hover text for the detail column. */
+  detailTitle?: string;
+  /** Extra chip after the label, e.g. "no price". */
+  note?: string;
+}
+
+/**
+ * Percentages, without lying by rounding.
+ *
+ * A model with 13 million tokens next to one with 5.6 billion is a real 0.2%,
+ * and printing "0%" makes it look like a bug rather than a ratio.
+ */
+function formatShare(share: number): string {
+  const percent = share * 100;
+  if (percent > 0 && percent < 1) return '<1%';
+  return `${Math.round(percent)}%`;
+}
+
+/**
+ * Smallest rendered bar width, in percent.
+ *
+ * Usage is wildly skewed — one model can be four orders of magnitude larger
+ * than the next — and a purely proportional bar renders the rest as invisible
+ * slivers. A floor keeps every row readable as a row.
+ */
+const MIN_BAR_PERCENT = 1.5;
+
+export interface BarChartProps {
+  data: BarDatum[];
+  formatValue: (value: number) => string;
+  ariaLabel: string;
+}
+
+/**
+ * Horizontal bar chart rendered with plain divs rather than SVG.
+ *
+ * Horizontal bars need to carry long, wrapping labels (model ids), which HTML
+ * handles far better than SVG text. Each row is also a `<tr>`-shaped list item
+ * so the numbers stay readable to a screen reader without a parallel table.
+ */
+export function BarChart({ data, formatValue, ariaLabel }: BarChartProps) {
+  if (data.length === 0) {
+    return <p className="py-6 text-center text-xs text-text-muted">No data in this range.</p>;
+  }
+
+  const max = niceMax(Math.max(...data.map(datum => datum.value), 1));
+
+  return (
+    <ul className="space-y-1.5" aria-label={ariaLabel}>
+      {data.map(datum => {
+        const widthPercent = datum.value > 0
+          ? Math.max(linearScale(datum.value, 0, max, 0, 100), MIN_BAR_PERCENT)
+          : 0;
+        return (
+          <li key={datum.label} className="min-w-0">
+            <div className="flex items-baseline justify-between gap-2 text-[11px]">
+              <span className="flex min-w-0 items-baseline gap-1.5">
+                {datum.tag && (
+                  <span className="flex-shrink-0 rounded-sm bg-surface-tertiary px-1 text-[9px] uppercase tracking-wide text-text-muted">
+                    {datum.tag}
+                  </span>
+                )}
+                <span className="truncate font-mono text-text-secondary" title={datum.title ?? datum.label}>
+                  {datum.label}
+                </span>
+                {datum.note && (
+                  <span className="flex-shrink-0 rounded-sm border border-border-secondary px-1 text-[9px] text-text-muted">
+                    {datum.note}
+                  </span>
+                )}
+              </span>
+              <span className="flex flex-shrink-0 items-baseline gap-2 tabular-nums text-text-tertiary">
+                {datum.share !== undefined && (
+                  <span className="text-text-muted">{formatShare(datum.share)}</span>
+                )}
+                <span>{formatValue(datum.value)}</span>
+                {datum.detail && (
+                  <span className="w-16 text-right text-text-muted" title={datum.detailTitle}>
+                    {datum.detail}
+                  </span>
+                )}
+              </span>
+            </div>
+            <div className="mt-0.5 h-1.5 w-full overflow-hidden rounded-full bg-surface-tertiary">
+              <div
+                className="h-full rounded-full transition-[width]"
+                style={{ width: `${widthPercent}%`, backgroundColor: datum.color }}
+              />
+            </div>
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+
+export default BarChart;
diff --git a/frontend/src/components/ui/charts/DonutChart.tsx b/frontend/src/components/ui/charts/DonutChart.tsx
new file mode 100644
index 00000000..94c68a44
--- /dev/null
+++ b/frontend/src/components/ui/charts/DonutChart.tsx
@@ -0,0 +1,110 @@
+import { arcPath } from './chartScales';
+
+export interface DonutSlice {
+  label: string;
+  value: number;
+  color: string;
+}
+
+export interface DonutChartProps {
+  slices: DonutSlice[];
+  formatValue: (value: number) => string;
+  ariaLabel: string;
+  /** Large text in the middle of the ring. */
+  centerLabel?: string;
+  centerSublabel?: string;
+  size?: number;
+}
+
+/**
+ * Donut chart plus legend. The ring is decorative — every number it encodes is
+ * also printed in the legend, so the SVG itself is `aria-hidden` and the whole
+ * figure carries one summary label.
+ */
+export function DonutChart({
+  slices,
+  formatValue,
+  ariaLabel,
+  centerLabel,
+  centerSublabel,
+  size = 132,
+}: DonutChartProps) {
+  const total = slices.reduce((sum, slice) => sum + slice.value, 0);
+  const center = size / 2;
+  const outerRadius = center - 2;
+  const innerRadius = outerRadius * 0.62;
+
+  let cursor = 0;
+  const arcs = slices.map(slice => {
+    const fraction = total > 0 ? slice.value / total : 0;
+    const path = arcPath(center, center, outerRadius, innerRadius, cursor, cursor + fraction);
+    cursor += fraction;
+    return { ...slice, path, fraction };
+  });
+
+  return (
+    <figure className="flex items-center gap-4" aria-label={ariaLabel}>
+      <svg width={size} height={size} viewBox={`0 0 ${size} ${size}`} aria-hidden="true" className="flex-shrink-0">
+        {total === 0 ? (
+          <circle
+            cx={center}
+            cy={center}
+            r={(outerRadius + innerRadius) / 2}
+            fill="none"
+            stroke="currentColor"
+            strokeWidth={outerRadius - innerRadius}
+            className="text-surface-tertiary"
+          />
+        ) : (
+          arcs.map(arc => arc.path && <path key={arc.label} d={arc.path} fill={arc.color} />)
+        )}
+
+        {centerLabel && (
+          <text
+            x={center}
+            y={center - 1}
+            textAnchor="middle"
+            className="fill-current text-text-primary"
+            style={{ fontSize: 15, fontWeight: 600 }}
+          >
+            {centerLabel}
+          </text>
+        )}
+        {centerSublabel && (
+          <text
+            x={center}
+            y={center + 12}
+            textAnchor="middle"
+            className="fill-current text-text-muted"
+            style={{ fontSize: 9 }}
+          >
+            {centerSublabel}
+          </text>
+        )}
+      </svg>
+
+      <figcaption className="min-w-0 flex-1">
+        <ul className="space-y-1">
+          {arcs.map(arc => (
+            <li key={arc.label} className="flex items-center gap-2 text-[11px]">
+              <span
+                className="h-2 w-2 flex-shrink-0 rounded-sm"
+                style={{ backgroundColor: arc.color }}
+                aria-hidden="true"
+              />
+              <span className="min-w-0 flex-1 truncate text-text-secondary">{arc.label}</span>
+              <span className="flex-shrink-0 tabular-nums text-text-tertiary">
+                {formatValue(arc.value)}
+              </span>
+              <span className="w-9 flex-shrink-0 text-right tabular-nums text-text-muted">
+                {total > 0 ? `${Math.round(arc.fraction * 100)}%` : '—'}
+              </span>
+            </li>
+          ))}
+        </ul>
+      </figcaption>
+    </figure>
+  );
+}
+
+export default DonutChart;
diff --git a/frontend/src/components/ui/charts/chartScales.test.ts b/frontend/src/components/ui/charts/chartScales.test.ts
new file mode 100644
index 00000000..d3bf7c3c
--- /dev/null
+++ b/frontend/src/components/ui/charts/chartScales.test.ts
@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest';
+import { linearScale, niceTicks, niceMax, arcPath, formatTokens, formatUsd } from './chartScales';
+
+describe('linearScale', () => {
+  it('maps the domain onto the range linearly', () => {
+    expect(linearScale(5, 0, 10, 0, 100)).toBe(50);
+    expect(linearScale(0, 0, 10, 20, 120)).toBe(20);
+    expect(linearScale(10, 0, 10, 20, 120)).toBe(120);
+  });
+
+  it('supports an inverted range, as SVG y-axes need', () => {
+    expect(linearScale(10, 0, 10, 100, 0)).toBe(0);
+    expect(linearScale(0, 0, 10, 100, 0)).toBe(100);
+  });
+
+  it('collapses a zero-width domain to the range start instead of dividing by zero', () => {
+    expect(linearScale(5, 5, 5, 0, 100)).toBe(0);
+  });
+});
+
+describe('niceTicks', () => {
+  it('returns a usable axis for an empty chart', () => {
+    expect(niceTicks(0)).toEqual([0, 1]);
+    expect(niceTicks(-5)).toEqual([0, 1]);
+    expect(niceTicks(Number.NaN)).toEqual([0, 1]);
+  });
+
+  it('always starts at zero and covers the max', () => {
+    for (const max of [1, 7, 93, 1234, 987_654]) {
+      const ticks = niceTicks(max);
+      expect(ticks[0]).toBe(0);
+      expect(ticks[ticks.length - 1]).toBeGreaterThanOrEqual(max);
+      expect(ticks.length).toBeGreaterThanOrEqual(2);
+    }
+  });
+
+  it('produces evenly spaced round steps', () => {
+    const ticks = niceTicks(100, 4);
+    const step = ticks[1] - ticks[0];
+    for (let i = 1; i < ticks.length; i++) {
+      expect(ticks[i] - ticks[i - 1]).toBeCloseTo(step, 6);
+    }
+    expect([1, 2, 5, 10, 20, 25, 50].some(candidate => Math.abs(step - candidate) < 1e-9)).toBe(true);
+  });
+
+  it('handles a max of 1 without collapsing the axis', () => {
+    expect(niceTicks(1)).toEqual([0, 0.5, 1]);
+  });
+});
+
+describe('niceMax', () => {
+  it('rounds up to the top tick', () => {
+    expect(niceMax(93)).toBeGreaterThanOrEqual(93);
+    expect(niceMax(0)).toBe(1);
+  });
+});
+
+describe('arcPath', () => {
+  it('returns an empty path for a zero-width or reversed segment', () => {
+    expect(arcPath(50, 50, 40, 25, 0.5, 0.5)).toBe('');
+    expect(arcPath(50, 50, 40, 25, 0.8, 0.2)).toBe('');
+  });
+
+  it('draws a full circle as two arcs', () => {
+    const path = arcPath(50, 50, 40, 25, 0, 1);
+    expect(path.match(/M /g)).toHaveLength(2);
+  });
+
+  it('clamps fractions above 1', () => {
+    const clamped = arcPath(50, 50, 40, 25, 0, 1.4);
+    const full = arcPath(50, 50, 40, 25, 0, 1);
+    expect(clamped).toBe(full);
+  });
+
+  it('sets the large-arc flag only past a half turn', () => {
+    expect(arcPath(50, 50, 40, 25, 0, 0.25)).toContain('0 1');
+    expect(arcPath(50, 50, 40, 25, 0, 0.75)).toContain('1 1');
+  });
+});
+
+describe('formatTokens', () => {
+  it('abbreviates by magnitude', () => {
+    expect(formatTokens(999)).toBe('999');
+    expect(formatTokens(1200)).toBe('1.2K');
+    expect(formatTokens(3_400_000)).toBe('3.4M');
+    expect(formatTokens(2_500_000_000)).toBe('2.5B');
+  });
+
+  it('handles zero and non-finite input', () => {
+    expect(formatTokens(0)).toBe('0');
+    expect(formatTokens(Number.NaN)).toBe('0');
+  });
+});
+
+describe('formatUsd', () => {
+  it('marks sub-cent amounts rather than showing $0.00', () => {
+    expect(formatUsd(0.004)).toBe('<$0.01');
+    expect(formatUsd(0)).toBe('$0.00');
+    expect(formatUsd(12.345)).toBe('$12.35');
+  });
+});
diff --git a/frontend/src/components/ui/charts/chartScales.ts b/frontend/src/components/ui/charts/chartScales.ts
new file mode 100644
index 00000000..282cf685
--- /dev/null
+++ b/frontend/src/components/ui/charts/chartScales.ts
@@ -0,0 +1,119 @@
+/**
+ * Pure maths for the hand-rolled SVG charts.
+ *
+ * Pane deliberately ships no charting library — see AGENTS.md. Keeping the
+ * scale/tick/arc maths here means it can be unit-tested without a DOM, and the
+ * chart components stay thin presentational wrappers.
+ */
+
+/** Map a value from a data domain onto a pixel range. */
+export function linearScale(value: number, domainMin: number, domainMax: number, rangeMin: number, rangeMax: number): number {
+  if (domainMax === domainMin) return rangeMin;
+  const t = (value - domainMin) / (domainMax - domainMin);
+  return rangeMin + t * (rangeMax - rangeMin);
+}
+
+/**
+ * Round a raw step up to the next "nice" number (1, 2, 5, 10 x 10^n), so axis
+ * labels land on values a human would have chosen.
+ */
+function niceStep(rawStep: number): number {
+  if (rawStep <= 0) return 1;
+  const magnitude = 10 ** Math.floor(Math.log10(rawStep));
+  const normalized = rawStep / magnitude;
+  if (normalized <= 1) return magnitude;
+  if (normalized <= 2) return 2 * magnitude;
+  if (normalized <= 5) return 5 * magnitude;
+  return 10 * magnitude;
+}
+
+/**
+ * Evenly spaced axis ticks covering `[0, max]`.
+ *
+ * Always returns at least two ticks so an axis is never a single label, and
+ * handles a zero or negative max (an empty chart) by returning `[0, 1]`.
+ */
+export function niceTicks(max: number, targetCount = 4): number[] {
+  if (!Number.isFinite(max) || max <= 0) return [0, 1];
+
+  const step = niceStep(max / Math.max(targetCount, 1));
+  // Extend to the first step at or above max, so the top tick always covers
+  // the data. Ticks are generated by index to avoid accumulating float error.
+  const stepCount = Math.max(Math.ceil(max / step), 1);
+
+  const ticks: number[] = [];
+  for (let i = 0; i <= stepCount; i++) {
+    ticks.push(Number((i * step).toFixed(10)));
+  }
+  return ticks;
+}
+
+/** Upper bound of an axis: the smallest nice tick at or above `max`. */
+export function niceMax(max: number, targetCount = 4): number {
+  const ticks = niceTicks(max, targetCount);
+  return ticks[ticks.length - 1];
+}
+
+/**
+ * SVG path for a donut segment.
+ *
+ * `startFraction` and `endFraction` are 0..1 of a full turn, measured
+ * clockwise from 12 o'clock. Fractions are clamped, so a caller that computes
+ * slightly over 1 from floating-point error still renders.
+ */
+export function arcPath(
+  cx: number,
+  cy: number,
+  outerRadius: number,
+  innerRadius: number,
+  startFraction: number,
+  endFraction: number
+): string {
+  const start = Math.min(Math.max(startFraction, 0), 1);
+  const end = Math.min(Math.max(endFraction, 0), 1);
+  if (end <= start) return '';
+
+  // A full circle cannot be drawn with a single arc — two halves are needed.
+  if (end - start >= 1) {
+    return [
+      arcPath(cx, cy, outerRadius, innerRadius, 0, 0.5),
+      arcPath(cx, cy, outerRadius, innerRadius, 0.5, 1),
+    ].join(' ');
+  }
+
+  const toPoint = (fraction: number, radius: number) => {
+    const angle = fraction * Math.PI * 2 - Math.PI / 2;
+    return { x: cx + Math.cos(angle) * radius, y: cy + Math.sin(angle) * radius };
+  };
+
+  const largeArc = end - start > 0.5 ? 1 : 0;
+  const outerStart = toPoint(start, outerRadius);
+  const outerEnd = toPoint(end, outerRadius);
+  const innerEnd = toPoint(end, innerRadius);
+  const innerStart = toPoint(start, innerRadius);
+
+  return [
+    `M ${outerStart.x} ${outerStart.y}`,
+    `A ${outerRadius} ${outerRadius} 0 ${largeArc} 1 ${outerEnd.x} ${outerEnd.y}`,
+    `L ${innerEnd.x} ${innerEnd.y}`,
+    `A ${innerRadius} ${innerRadius} 0 ${largeArc} 0 ${innerStart.x} ${innerStart.y}`,
+    'Z',
+  ].join(' ');
+}
+
+/** Compact token counts: 1200 -> "1.2K", 3_400_000 -> "3.4M". */
+export function formatTokens(value: number): string {
+  if (!Number.isFinite(value)) return '0';
+  const abs = Math.abs(value);
+  if (abs >= 1_000_000_000) return `${(value / 1_000_000_000).toFixed(1)}B`;
+  if (abs >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`;
+  if (abs >= 1_000) return `${(value / 1_000).toFixed(1)}K`;
+  return String(Math.round(value));
+}
+
+/** Cost formatting that stays informative for very small amounts. */
+export function formatUsd(value: number): string {
+  if (!Number.isFinite(value) || value === 0) return '$0.00';
+  if (Math.abs(value) < 0.01) return '<$0.01';
+  return `$${value.toFixed(2)}`;
+}
diff --git a/frontend/src/components/usage/LimitGauge.tsx b/frontend/src/components/usage/LimitGauge.tsx
new file mode 100644
index 00000000..ac3bc6da
--- /dev/null
+++ b/frontend/src/components/usage/LimitGauge.tsx
@@ -0,0 +1,129 @@
+import { arcPath, formatTokens } from '../ui/charts/chartScales';
+import type { UsageWindow } from '../../../../shared/types/usage';
+
+const SIZE = 148;
+/** Three-quarter dial: leaves a gap at the bottom for the reset label. */
+const SWEEP = 0.75;
+
+function utilizationColor(utilization: number): string {
+  if (utilization >= 0.9) return 'var(--color-status-error, #e05a6b)';
+  if (utilization >= 0.7) return 'var(--color-status-warning, #e0913a)';
+  return 'var(--color-status-success, #37b877)';
+}
+
+function formatReset(resetsAtMs: number | null): string {
+  if (!resetsAtMs) return 'No activity in this window';
+  const remainingMs = resetsAtMs - Date.now();
+  if (remainingMs <= 0) return 'Window has reset';
+
+  const hours = Math.floor(remainingMs / 3_600_000);
+  const minutes = Math.round((remainingMs % 3_600_000) / 60_000);
+  return hours > 0 ? `Oldest usage ages out in ${hours}h ${minutes}m` : `Oldest usage ages out in ${minutes}m`;
+}
+
+/**
+ * What the current pace means for the window.
+ *
+ * The window total alone is a state, not a direction: 10% full and idle is a
+ * different situation from 10% full and climbing. The last hour is the honest
+ * proxy for "right now" — extrapolating from the 5-hour average would smooth
+ * away exactly the burst the user is asking about.
+ */
+function formatPace(usageWindow: UsageWindow): string | null {
+  const perHour = usageWindow.recentHourTokens;
+  if (perHour <= 0) return 'Nothing in the last hour';
+
+  const rate = `${formatTokens(perHour)}/h in the last hour`;
+  const limit = usageWindow.limitTokens;
+  if (limit === null) return rate;
+
+  const remaining = limit - usageWindow.totals.totalTokens;
+  if (remaining <= 0) return `${rate} · at the limit`;
+
+  const hoursToFull = remaining / perHour;
+  if (hoursToFull > usageWindow.windowHours) return `${rate} · well inside the limit`;
+
+  return hoursToFull < 1
+    ? `${rate} · limit in under an hour`
+    : `${rate} · limit in ~${Math.round(hoursToFull)}h`;
+}
+
+export interface LimitGaugeProps {
+  window: UsageWindow;
+}
+
+/**
+ * Rolling-window utilisation dial.
+ *
+ * When no limit is configured the backend falls back to the largest window
+ * ever observed. That is a lower bound, not the real cap, so the source is
+ * labelled explicitly rather than presented as an authoritative quota.
+ */
+export function LimitGauge({ window: usageWindow }: LimitGaugeProps) {
+  const center = SIZE / 2;
+  const outerRadius = center - 4;
+  const innerRadius = outerRadius * 0.72;
+  const utilization = usageWindow.utilization ?? 0;
+  const hasLimit = usageWindow.utilization !== null && usageWindow.limitTokens !== null;
+  const pace = formatPace(usageWindow);
+
+  // The dial starts at the lower-left so its gap sits at the bottom.
+  const startFraction = (1 - SWEEP) / 2 + 0.5;
+  const track = arcPath(center, center, outerRadius, innerRadius, 0, SWEEP);
+  const filled = hasLimit
+    ? arcPath(center, center, outerRadius, innerRadius, 0, SWEEP * utilization)
+    : '';
+
+  const summary = hasLimit
+    ? `${Math.round(utilization * 100)}% of the ${usageWindow.windowHours}-hour window used`
+    : `${formatTokens(usageWindow.totals.totalTokens)} tokens used in the last ${usageWindow.windowHours} hours; no limit known`;
+
+  return (
+    <div className="flex flex-col items-center">
+      <svg
+        width={SIZE}
+        height={SIZE}
+        viewBox={`0 0 ${SIZE} ${SIZE}`}
+        role="img"
+        aria-label={summary}
+        style={{ transform: `rotate(${startFraction * 360}deg)` }}
+      >
+        <path d={track} className="fill-current text-surface-tertiary" />
+        {filled && <path d={filled} fill={utilizationColor(utilization)} />}
+      </svg>
+
+      {/* Text sits outside the rotated SVG so it stays upright. */}
+      <div className="-mt-[5.6rem] mb-8 flex flex-col items-center">
+        <span className="text-2xl font-semibold tabular-nums text-text-primary">
+          {hasLimit ? `${Math.round(utilization * 100)}%` : '—'}
+        </span>
+        <span className="text-[10px] uppercase tracking-wider text-text-muted">
+          {usageWindow.windowHours}h window
+        </span>
+      </div>
+
+      <p className="text-center text-[11px] text-text-secondary">
+        {formatTokens(usageWindow.totals.totalTokens)} tokens
+        {usageWindow.limitTokens !== null && (
+          <> of ~{formatTokens(usageWindow.limitTokens)}</>
+        )}
+      </p>
+      <p className="mt-0.5 text-center text-[10px] text-text-muted">{formatReset(usageWindow.resetsAtMs)}</p>
+      {pace && (
+        <p className="mt-0.5 text-center text-[10px] font-medium text-text-secondary">{pace}</p>
+      )}
+      {usageWindow.limitSource === 'observed-max' && (
+        <p className="mt-1 max-w-[16rem] text-center text-[10px] text-text-muted">
+          No limit set — comparing against your highest recorded {usageWindow.windowHours}h window.
+        </p>
+      )}
+      {usageWindow.limitSource === 'unknown' && (
+        <p className="mt-1 max-w-[16rem] text-center text-[10px] text-text-muted">
+          Not enough history yet to estimate a limit.
+        </p>
+      )}
+    </div>
+  );
+}
+
+export default LimitGauge;
diff --git a/frontend/src/components/usage/UsageView.tsx b/frontend/src/components/usage/UsageView.tsx
new file mode 100644
index 00000000..1b78e721
--- /dev/null
+++ b/frontend/src/components/usage/UsageView.tsx
@@ -0,0 +1,691 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { BarChart3, Loader2, RefreshCw } from 'lucide-react';
+import { API } from '../../utils/api';
+import { AreaChart } from '../ui/charts/AreaChart';
+import { BarChart } from '../ui/charts/BarChart';
+import { DonutChart } from '../ui/charts/DonutChart';
+import { formatTokens, formatUsd } from '../ui/charts/chartScales';
+import { LimitGauge } from './LimitGauge';
+import { DEFAULT_USAGE_RANGE_DAYS, type UsageProvider, type UsageReport } from '../../../../shared/types/usage';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Poll while a scan is running so the progress line stays honest. */
+const SCAN_POLL_MS = 4000;
+
+const RANGE_OPTIONS = [
+  { days: 1, label: '24h' },
+  { days: 7, label: '7d' },
+  { days: DEFAULT_USAGE_RANGE_DAYS, label: '30d' },
+  { days: 90, label: '90d' },
+] as const;
+
+const PROVIDER_OPTIONS: Array<{ value: UsageProvider | 'all'; label: string }> = [
+  { value: 'all', label: 'All' },
+  { value: 'claude', label: 'Claude' },
+  { value: 'codex', label: 'Codex' },
+];
+
+const PROVIDER_LABEL: Record<UsageProvider, string> = {
+  claude: 'Anthropic',
+  codex: 'OpenAI',
+};
+
+const PROVIDER_COLOR: Record<UsageProvider, string> = {
+  claude: '#e0913a',
+  codex: '#37b877',
+};
+
+/** Chart palette, matching the graph view's lane colours. */
+const SERIES_COLORS = {
+  input: '#4f8ef7',
+  output: '#37b877',
+  cacheRead: '#8f8ff0',
+  cacheWrite: '#e0913a',
+} as const;
+
+const MODEL_COLORS = ['#4f8ef7', '#37b877', '#e0913a', '#c765d6', '#e05a6b', '#3fb8c4', '#8f8ff0', '#c2a63a'];
+
+/**
+ * The user's own cap for the rolling window, in millions of tokens.
+ *
+ * Kept client-side: it is a statement about the person's plan, not about the
+ * indexed data, and no provider publishes a number Pane could fill in for them.
+ */
+const WINDOW_LIMIT_KEY = 'pane.usage.windowLimitMTok';
+
+function readStoredLimit(): number | null {
+  try {
+    const raw = window.localStorage.getItem(WINDOW_LIMIT_KEY);
+    const parsed = raw === null ? NaN : Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeStoredLimit(value: number | null): void {
+  try {
+    if (value === null) window.localStorage.removeItem(WINDOW_LIMIT_KEY);
+    else window.localStorage.setItem(WINDOW_LIMIT_KEY, String(value));
+  } catch {
+    // Locked-down profile — the limit just stays session-only.
+  }
+}
+
+/** "10080" -> "7d", "300" -> "5h" — providers report windows in minutes. */
+function formatWindow(minutes: number): string {
+  if (minutes % (60 * 24) === 0) return `${minutes / (60 * 24)}d window`;
+  if (minutes % 60 === 0) return `${minutes / 60}h window`;
+  return `${minutes}m window`;
+}
+
+/** "2h ago" — how old a provider-reported reading is. */
+function formatAge(atMs: number): string {
+  const elapsed = Date.now() - atMs;
+  if (elapsed < 60_000) return 'just now';
+  const minutes = Math.floor(elapsed / 60_000);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+function formatReset(atMs: number): string {
+  const remaining = atMs - Date.now();
+  if (remaining <= 0) return 'now';
+  const hours = Math.floor(remaining / 3_600_000);
+  if (hours >= 24) return `in ${Math.floor(hours / 24)}d`;
+  if (hours >= 1) return `in ${hours}h`;
+  return `in ${Math.max(1, Math.round(remaining / 60_000))}m`;
+}
+
+function StatCard({
+  label,
+  value,
+  detail,
+}: {
+  label: string;
+  value: string;
+  detail?: string;
+}) {
+  return (
+    <div className="rounded border border-border-primary bg-surface-secondary px-3 py-2">
+      <p className="text-[10px] uppercase tracking-wider text-text-muted">{label}</p>
+      <p className="mt-0.5 text-lg font-semibold tabular-nums text-text-primary">{value}</p>
+      {detail && <p className="text-[10px] text-text-tertiary">{detail}</p>}
+    </div>
+  );
+}
+
+/**
+ * Token usage, cost and rate-limit page.
+ *
+ * The numbers come from the agent CLIs' own transcripts, indexed in the main
+ * process — Pane runs the agents as PTYs and never sees their token accounting
+ * directly.
+ */
+export function UsageView() {
+  const [report, setReport] = useState<UsageReport | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [refreshing, setRefreshing] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [rangeDays, setRangeDays] = useState<number>(DEFAULT_USAGE_RANGE_DAYS);
+  const [provider, setProvider] = useState<UsageProvider | 'all'>('all');
+  /** Series switched off in the legend — see `visibleAreaSeries`. */
+  const [hiddenSeries, setHiddenSeries] = useState<string[]>([]);
+  /**
+   * The user's own cap for the rolling window, in millions of tokens.
+   *
+   * Providers publish no per-plan token cap, so inventing one would be worse
+   * than useless — this is the user stating theirs. Null means "compare against
+   * my own busiest window", the previous behaviour.
+   */
+  const [windowLimitMTok, setWindowLimitMTok] = useState<number | null>(() => readStoredLimit());
+  const [limitDraft, setLimitDraft] = useState<string>(() => {
+    const stored = readStoredLimit();
+    return stored === null ? '' : String(stored);
+  });
+
+  const load = useCallback(async (mode: 'initial' | 'refresh') => {
+    if (mode === 'refresh') setRefreshing(true);
+    try {
+      const toMs = Date.now();
+      const response = await API.usage.getReport({
+        fromMs: toMs - rangeDays * DAY_MS,
+        toMs,
+        ...(provider === 'all' ? {} : { providers: [provider] }),
+        ...(windowLimitMTok ? { limitTokens: windowLimitMTok * 1_000_000 } : {}),
+      });
+      if (!response.success || !response.data) {
+        throw new Error(response.error || 'Failed to load usage');
+      }
+      setReport(response.data);
+      setError(null);
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : 'Failed to load usage');
+    } finally {
+      setLoading(false);
+      setRefreshing(false);
+    }
+  }, [rangeDays, provider, windowLimitMTok]);
+
+  /** Apply the typed limit: persist it and reload so the gauge uses it. */
+  const applyLimit = useCallback(() => {
+    const parsed = Number(limitDraft);
+    const next = limitDraft.trim() === '' || !Number.isFinite(parsed) || parsed <= 0
+      ? null
+      : parsed;
+    writeStoredLimit(next);
+    setWindowLimitMTok(next);
+    setLimitDraft(next === null ? '' : String(next));
+  }, [limitDraft]);
+
+  useEffect(() => {
+    void load('initial');
+  }, [load]);
+
+  // While the index is still building, keep refreshing so numbers fill in.
+  const scanning = report?.index.scanning ?? false;
+  useEffect(() => {
+    if (!scanning) return;
+    const timer = window.setInterval(() => { void load('refresh'); }, SCAN_POLL_MS);
+    return () => window.clearInterval(timer);
+  }, [scanning, load]);
+
+  const handleRescan = useCallback(async () => {
+    setRefreshing(true);
+    try {
+      await API.usage.rescan();
+      await load('refresh');
+    } catch {
+      setRefreshing(false);
+    }
+  }, [load]);
+
+  const seriesLabels = useMemo(
+    () => (report?.series ?? []).map(bucket =>
+      new Date(bucket.bucketStartMs).toLocaleDateString(undefined, { month: 'short', day: 'numeric' })
+    ),
+    [report]
+  );
+
+  const areaSeries = useMemo(() => {
+    const buckets = report?.series ?? [];
+    return [
+      { label: 'Input', color: SERIES_COLORS.input, values: buckets.map(b => b.inputTokens) },
+      { label: 'Output', color: SERIES_COLORS.output, values: buckets.map(b => b.outputTokens) },
+      { label: 'Cache read', color: SERIES_COLORS.cacheRead, values: buckets.map(b => b.cacheReadTokens) },
+      { label: 'Cache write', color: SERIES_COLORS.cacheWrite, values: buckets.map(b => b.cacheCreationTokens) },
+    ];
+  }, [report]);
+
+  /**
+   * Series the chart is currently drawing.
+   *
+   * Cache reads run two orders of magnitude above input and output, so on a
+   * shared axis those two are a flat line on the floor — the chart looked like
+   * it had no input/output data at all. Switching a series off rescales the
+   * axis to what is left, which is the only way to see them.
+   */
+  const visibleAreaSeries = useMemo(
+    () => areaSeries.filter(entry => !hiddenSeries.includes(entry.label)),
+    [areaSeries, hiddenSeries]
+  );
+
+  const toggleSeries = useCallback((label: string) => {
+    setHiddenSeries(current => (
+      current.includes(label)
+        ? current.filter(entry => entry !== label)
+        // Never hide the last one: an empty chart says nothing.
+        : current.length === areaSeries.length - 1
+          ? current
+          : [...current, label]
+    ));
+  }, [areaSeries.length]);
+
+  const modelBars = useMemo(() => {
+    const total = report?.totals.totalTokens ?? 0;
+    return (report?.byModel ?? []).slice(0, 10).map((entry, index) => ({
+      label: entry.model,
+      value: entry.totalTokens,
+      color: MODEL_COLORS[index % MODEL_COLORS.length],
+      tag: PROVIDER_LABEL[entry.provider],
+      share: total > 0 ? entry.totalTokens / total : 0,
+      detail: entry.costIncomplete ? 'n/a' : formatUsd(entry.estimatedCostUsd),
+      // Codex writes the active *profile* where a model id is expected, so a
+      // row with no price is usually a sub-agent rather than a missing price.
+      note: entry.costIncomplete ? 'no price' : undefined,
+      detailTitle: entry.costIncomplete
+        ? 'No published price for this id. Codex reports sub-agent profiles (for example codex-auto-review) in the model field, and those are billed under the model they run on.'
+        : undefined,
+    }));
+  }, [report]);
+
+  /** Which worktree spent the tokens — the question only Pane can answer. */
+  const projectBars = useMemo(() => {
+    const total = report?.totals.totalTokens ?? 0;
+    return (report?.byProject ?? []).slice(0, 8).map((entry, index) => ({
+      label: entry.label,
+      title: entry.path || 'No working directory recorded',
+      value: entry.totalTokens,
+      color: MODEL_COLORS[index % MODEL_COLORS.length],
+      share: total > 0 ? entry.totalTokens / total : 0,
+      detail: entry.costIncomplete ? 'n/a' : formatUsd(entry.estimatedCostUsd),
+    }));
+  }, [report]);
+
+  /**
+   * How much of the input never had to be re-read at full price.
+   *
+   * Cache reads dominate every other number on this page, and as a raw token
+   * count that reads as noise. As a hit rate plus the money it saved, it is the
+   * most actionable figure here.
+   */
+  const cacheEfficiency = useMemo(() => {
+    const totals = report?.totals;
+    if (!totals) return null;
+    const readable = totals.inputTokens + totals.cacheReadTokens;
+    if (readable === 0) return null;
+    return {
+      hitRate: totals.cacheReadTokens / readable,
+      savingsUsd: totals.cacheSavingsUsd,
+    };
+  }, [report]);
+
+  /** Anthropic vs OpenAI roll-up — the split the model list alone doesn't show. */
+  const providerBars = useMemo(() => {
+    const byProvider = new Map<UsageProvider, { tokens: number; cost: number; incomplete: boolean }>();
+    for (const entry of report?.byModel ?? []) {
+      const acc = byProvider.get(entry.provider) ?? { tokens: 0, cost: 0, incomplete: false };
+      acc.tokens += entry.totalTokens;
+      acc.cost += entry.estimatedCostUsd;
+      acc.incomplete = acc.incomplete || entry.costIncomplete;
+      byProvider.set(entry.provider, acc);
+    }
+
+    const total = report?.totals.totalTokens ?? 0;
+    return [...byProvider.entries()]
+      .sort((a, b) => b[1].tokens - a[1].tokens)
+      .map(([key, value]) => ({
+        label: PROVIDER_LABEL[key],
+        value: value.tokens,
+        color: PROVIDER_COLOR[key],
+        share: total > 0 ? value.tokens / total : 0,
+        detail: value.incomplete ? 'n/a' : formatUsd(value.cost),
+      }));
+  }, [report]);
+
+  const cacheSlices = useMemo(() => {
+    const totals = report?.totals;
+    if (!totals) return [];
+    return [
+      { label: 'Input', value: totals.inputTokens, color: SERIES_COLORS.input },
+      { label: 'Output', value: totals.outputTokens, color: SERIES_COLORS.output },
+      { label: 'Cache read', value: totals.cacheReadTokens, color: SERIES_COLORS.cacheRead },
+      { label: 'Cache write', value: totals.cacheCreationTokens, color: SERIES_COLORS.cacheWrite },
+    ];
+  }, [report]);
+
+  const bothRootsMissing = (report?.index.missingRoots.length ?? 0) >= 2;
+
+  return (
+    <div className="flex h-full min-h-0 flex-1 flex-col overflow-hidden bg-bg-primary">
+      <header className="flex flex-shrink-0 flex-wrap items-center gap-3 border-b border-border-primary bg-surface-secondary px-4 py-2">
+        <div className="flex items-center gap-2">
+          <BarChart3 className="h-4 w-4 text-text-tertiary" aria-hidden="true" />
+          <h1 className="text-sm font-medium text-text-primary">Usage &amp; limits</h1>
+        </div>
+
+        <div className="ml-auto flex flex-wrap items-center gap-3">
+          <fieldset className="flex items-center gap-1">
+            <legend className="sr-only">Provider</legend>
+            {PROVIDER_OPTIONS.map(option => (
+              <button
+                key={option.value}
+                type="button"
+                aria-pressed={provider === option.value}
+                onClick={() => setProvider(option.value)}
+                className={`rounded px-2 py-0.5 text-[11px] transition-colors ${
+                  provider === option.value
+                    ? 'bg-interactive text-text-on-interactive'
+                    : 'text-text-secondary hover:bg-surface-hover'
+                }`}
+              >
+                {option.label}
+              </button>
+            ))}
+          </fieldset>
+
+          <span className="h-4 w-px bg-border-primary" aria-hidden="true" />
+
+          <fieldset className="flex items-center gap-1">
+            <legend className="sr-only">Time range</legend>
+            {RANGE_OPTIONS.map(option => (
+              <button
+                key={option.days}
+                type="button"
+                aria-pressed={rangeDays === option.days}
+                onClick={() => setRangeDays(option.days)}
+                className={`rounded px-2 py-0.5 text-[11px] transition-colors ${
+                  rangeDays === option.days
+                    ? 'bg-interactive text-text-on-interactive'
+                    : 'text-text-secondary hover:bg-surface-hover'
+                }`}
+              >
+                {option.label}
+              </button>
+            ))}
+          </fieldset>
+
+          <button
+            type="button"
+            onClick={() => { void handleRescan(); }}
+            disabled={refreshing}
+            aria-label="Rescan transcripts"
+            className="rounded p-1 transition-colors hover:bg-surface-hover disabled:opacity-50"
+          >
+            <RefreshCw className={`h-3.5 w-3.5 text-text-tertiary ${refreshing ? 'animate-spin' : ''}`} aria-hidden="true" />
+          </button>
+        </div>
+      </header>
+
+      {report?.index.scanning && (
+        <div className="flex flex-shrink-0 items-center gap-2 border-b border-border-primary bg-surface-tertiary px-4 py-1 text-[11px] text-text-tertiary">
+          <Loader2 className="h-3 w-3 animate-spin" aria-hidden="true" />
+          Indexing transcripts… {report.index.filesScanned}/{report.index.filesTotal} files
+        </div>
+      )}
+
+      <div className="min-h-0 flex-1 overflow-auto p-4">
+        {loading ? (
+          <div className="flex items-center justify-center gap-2 py-10 text-xs text-text-tertiary">
+            <Loader2 className="h-4 w-4 animate-spin" aria-hidden="true" />
+            Reading usage…
+          </div>
+        ) : error ? (
+          <div className="rounded border border-status-error/30 bg-status-error/10 p-4 text-sm text-status-error">
+            {error}
+          </div>
+        ) : bothRootsMissing ? (
+          <div className="mx-auto max-w-lg rounded border border-border-primary bg-surface-secondary p-6 text-center">
+            <h2 className="mb-2 text-sm font-medium text-text-primary">No agent transcripts found</h2>
+            <p className="text-xs text-text-secondary">
+              Usage is read from the Claude Code and Codex transcript files in your home directory.
+              Neither <code className="font-mono">~/.claude/projects</code> nor{' '}
+              <code className="font-mono">~/.codex/sessions</code> exists yet — run an agent once and
+              come back.
+            </p>
+          </div>
+        ) : report ? (
+          <div className="mx-auto flex max-w-6xl flex-col gap-4">
+            {/* Summary */}
+            <div className="grid grid-cols-2 gap-2 sm:grid-cols-4">
+              <StatCard
+                label="Total tokens"
+                value={formatTokens(report.totals.totalTokens)}
+                detail={`${report.totals.messageCount.toLocaleString()} messages`}
+              />
+              <StatCard label="Input" value={formatTokens(report.totals.inputTokens)} />
+              <StatCard label="Output" value={formatTokens(report.totals.outputTokens)} />
+              {/*
+                Not a bill. These tokens were almost certainly paid for by a
+                flat-rate plan; the figure is what the same traffic would cost
+                billed per token through the APIs, which is the only number the
+                transcripts support.
+              */}
+              <StatCard
+                label="At API prices"
+                value={formatUsd(report.totals.estimatedCostUsd)}
+                detail={report.totals.costIncomplete
+                  ? 'What API billing would cost · some ids unpriced'
+                  : 'What API billing would cost, not your plan'}
+              />
+            </div>
+
+            {cacheEfficiency && (
+              <div className="grid grid-cols-2 gap-2 sm:grid-cols-4">
+                <StatCard
+                  label="Cache hit rate"
+                  value={`${Math.round(cacheEfficiency.hitRate * 100)}%`}
+                  detail="of read input came from cache"
+                />
+                <StatCard
+                  label="Saved by caching"
+                  value={formatUsd(cacheEfficiency.savingsUsd)}
+                  detail="vs. re-reading at full input price"
+                />
+                <StatCard
+                  label="Messages"
+                  value={report.totals.messageCount.toLocaleString()}
+                  detail={`${formatTokens(
+                    report.totals.messageCount > 0
+                      ? report.totals.totalTokens / report.totals.messageCount
+                      : 0
+                  )} per message`}
+                />
+                <StatCard
+                  label="Busiest project"
+                  value={report.byProject[0]?.label ?? '—'}
+                  detail={report.byProject[0]
+                    ? `${formatTokens(report.byProject[0].totalTokens)} tokens`
+                    : undefined}
+                />
+              </div>
+            )}
+
+            <div className="grid gap-4 lg:grid-cols-3">
+              {/* Time series */}
+              <section className="rounded border border-border-primary bg-surface-secondary p-3 lg:col-span-2">
+                <h2 className="mb-2 text-[11px] font-medium uppercase tracking-wider text-text-tertiary">
+                  Tokens over time
+                </h2>
+                <AreaChart
+                  labels={seriesLabels}
+                  series={visibleAreaSeries}
+                  formatValue={formatTokens}
+                  ariaLabel={`Token usage over the last ${rangeDays} days, totalling ${formatTokens(report.totals.totalTokens)} tokens`}
+                />
+                {/*
+                  A legend that switches series on and off, because the axis is
+                  shared: with cache reads drawn, input and output are a flat
+                  line on the floor.
+                */}
+                <ul className="mt-2 flex flex-wrap gap-2">
+                  {areaSeries.map(entry => {
+                    const hidden = hiddenSeries.includes(entry.label);
+                    const total = entry.values.reduce((sum, value) => sum + value, 0);
+
+                    return (
+                      <li key={entry.label}>
+                        <button
+                          type="button"
+                          onClick={() => toggleSeries(entry.label)}
+                          aria-pressed={!hidden}
+                          title={hidden ? `Show ${entry.label}` : `Hide ${entry.label}`}
+                          className={`flex items-center gap-1.5 rounded px-1.5 py-0.5 text-[10px] transition-colors hover:bg-surface-hover focus:outline-none focus-visible:ring-1 focus-visible:ring-interactive ${
+                            hidden ? 'text-text-muted' : 'text-text-tertiary'
+                          }`}
+                        >
+                          <span
+                            className="h-2 w-2 rounded-sm border"
+                            style={{
+                              backgroundColor: hidden ? 'transparent' : entry.color,
+                              borderColor: entry.color,
+                            }}
+                            aria-hidden="true"
+                          />
+                          <span className={hidden ? 'line-through' : undefined}>{entry.label}</span>
+                          <span className="tabular-nums text-text-muted">{formatTokens(total)}</span>
+                        </button>
+                      </li>
+                    );
+                  })}
+                </ul>
+              </section>
+
+              {/* Limits */}
+              <section className="rounded border border-border-primary bg-surface-secondary p-3">
+                <h2 className="mb-2 text-[11px] font-medium uppercase tracking-wider text-text-tertiary">
+                  Limits
+                </h2>
+
+                {/* Provider-reported quota beats anything we could infer. */}
+                {report.rateLimits.length > 0 && (
+                  <ul className="mb-3 space-y-2">
+                    {report.rateLimits.map(limit => (
+                      <li key={`${limit.provider}-${limit.limitId}-${limit.scope}`}>
+                        <div className="flex items-baseline justify-between gap-2 text-[11px]">
+                          <span className="truncate text-text-secondary">
+                            {PROVIDER_LABEL[limit.provider]}
+                            {limit.windowMinutes && (
+                              <span className="ml-1 text-text-muted">
+                                {formatWindow(limit.windowMinutes)}
+                              </span>
+                            )}
+                            {limit.planType && (
+                              <span className="ml-1 text-text-muted">· {limit.planType}</span>
+                            )}
+                          </span>
+                          <span className="flex-shrink-0 tabular-nums text-text-primary">
+                            {Math.round(limit.usedPercent)}%
+                          </span>
+                        </div>
+                        <div className="mt-0.5 h-1.5 w-full overflow-hidden rounded-full bg-surface-tertiary">
+                          <div
+                            className="h-full rounded-full"
+                            style={{
+                              width: `${Math.min(Math.max(limit.usedPercent, 0), 100)}%`,
+                              backgroundColor: limit.usedPercent >= 90
+                                ? 'var(--color-status-error, #e05a6b)'
+                                : limit.usedPercent >= 70
+                                  ? 'var(--color-status-warning, #e0913a)'
+                                  : 'var(--color-status-success, #37b877)',
+                            }}
+                          />
+                        </div>
+                        {/*
+                          When the reading was taken matters as much as the
+                          reading: these come from the last transcript line the
+                          agent wrote, and a 0% from yesterday is not a claim
+                          about now.
+                        */}
+                        <p className="mt-0.5 text-[10px] text-text-muted">
+                          Reported {formatAge(limit.capturedAtMs)}
+                          {limit.resetsAtMs
+                            ? limit.resetsAtMs <= Date.now()
+                              ? ' · window has since reset'
+                              : ` · resets ${formatReset(limit.resetsAtMs)}`
+                            : ''}
+                        </p>
+                      </li>
+                    ))}
+                  </ul>
+                )}
+
+                <LimitGauge window={report.window} />
+
+                {/*
+                  The window cap is the user's to state — no provider publishes
+                  a per-plan token number, and the gauge is guesswork until
+                  someone says what it is measuring against.
+                */}
+                <div className="mt-3 border-t border-border-primary pt-2">
+                  <label
+                    htmlFor="usage-window-limit"
+                    className="text-[10px] uppercase tracking-wider text-text-muted"
+                  >
+                    My {report.window.windowHours}h limit
+                  </label>
+                  <div className="mt-1 flex items-center gap-1.5">
+                    <input
+                      id="usage-window-limit"
+                      type="number"
+                      min={0}
+                      step={10}
+                      inputMode="decimal"
+                      value={limitDraft}
+                      placeholder="auto"
+                      onChange={event => setLimitDraft(event.target.value)}
+                      onBlur={applyLimit}
+                      onKeyDown={event => { if (event.key === 'Enter') applyLimit(); }}
+                      className="w-24 rounded border border-border-secondary bg-surface-primary px-1.5 py-0.5 text-[11px] tabular-nums text-text-primary focus:border-interactive focus:outline-none"
+                    />
+                    <span className="text-[10px] text-text-muted">million tokens</span>
+                    {windowLimitMTok !== null && (
+                      <button
+                        type="button"
+                        onClick={() => { setLimitDraft(''); writeStoredLimit(null); setWindowLimitMTok(null); }}
+                        className="ml-auto rounded px-1.5 py-0.5 text-[10px] text-text-tertiary transition-colors hover:bg-surface-hover hover:text-text-primary"
+                      >
+                        Clear
+                      </button>
+                    )}
+                  </div>
+                </div>
+              </section>
+            </div>
+
+            <div className="grid gap-4 lg:grid-cols-3">
+              <section className="rounded border border-border-primary bg-surface-secondary p-3 lg:col-span-2">
+                <h2 className="mb-2 text-[11px] font-medium uppercase tracking-wider text-text-tertiary">
+                  By model
+                </h2>
+                <BarChart
+                  data={modelBars}
+                  formatValue={formatTokens}
+                  ariaLabel="Token usage broken down by model"
+                />
+
+                <h2 className="mb-2 mt-4 text-[11px] font-medium uppercase tracking-wider text-text-tertiary">
+                  By project
+                </h2>
+                <BarChart
+                  data={projectBars}
+                  formatValue={formatTokens}
+                  ariaLabel="Token usage broken down by working directory"
+                />
+              </section>
+
+              <section className="rounded border border-border-primary bg-surface-secondary p-3">
+                <h2 className="mb-2 text-[11px] font-medium uppercase tracking-wider text-text-tertiary">
+                  By provider
+                </h2>
+                <BarChart
+                  data={providerBars}
+                  formatValue={formatTokens}
+                  ariaLabel="Token usage split between Anthropic and OpenAI"
+                />
+
+                <h2 className="mb-2 mt-4 text-[11px] font-medium uppercase tracking-wider text-text-tertiary">
+                  Token mix
+                </h2>
+                <DonutChart
+                  slices={cacheSlices}
+                  formatValue={formatTokens}
+                  ariaLabel="Share of input, output and cache tokens"
+                  centerLabel={formatTokens(report.totals.totalTokens)}
+                  centerSublabel="tokens"
+                />
+              </section>
+            </div>
+
+            <footer className="flex flex-wrap items-center gap-x-4 gap-y-1 text-[10px] text-text-muted">
+              <span>Prices as of {report.pricingAsOf}; costs are estimates.</span>
+              <span>{report.index.eventsIndexed.toLocaleString()} messages indexed from {report.index.filesTracked.toLocaleString()} transcripts.</span>
+              {/* The scanner reads this machine's home only; WSL distros keep their own. */}
+              <span>Agents running inside WSL write their transcripts in the distro’s home and are not counted.</span>
+              {report.index.missingRoots.length > 0 && (
+                <span>Not found: {report.index.missingRoots.join(', ')}</span>
+              )}
+              {report.index.lastError && (
+                <span className="text-status-warning">Last scan error: {report.index.lastError}</span>
+              )}
+            </footer>
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+export default UsageView;
diff --git a/frontend/src/stores/navigationStore.ts b/frontend/src/stores/navigationStore.ts
index 9a26e153..9c624d91 100644
--- a/frontend/src/stores/navigationStore.ts
+++ b/frontend/src/stores/navigationStore.ts
@@ -10,8 +10,15 @@ let hasRegisteredInitialProjectIds = false;
 const toProjectIdArray = (projectIds: Set<number>): number[] =>
   Array.from(projectIds).sort((a, b) => a - b);
 
+/**
+ * Pane has no router — this enum is the whole navigation model. Adding a value
+ * here also requires a branch in `SessionView` and an entry in *both* sidebar
+ * components (`Sidebar` compact rail and `ProjectSessionList` expanded tree).
+ */
+export type ActiveView = 'sessions' | 'project' | 'pane-chat' | 'usage';
+
 interface NavigationState {
-  activeView: 'sessions' | 'project' | 'pane-chat';
+  activeView: ActiveView;
   activeProjectId: number | null;
 
   // Sidebar collapse
@@ -37,11 +44,12 @@ interface NavigationState {
   setSidebarNavigationScope: (scope: SidebarNavigationScope) => void;
 
   // Actions
-  setActiveView: (view: 'sessions' | 'project' | 'pane-chat') => void;
+  setActiveView: (view: ActiveView) => void;
   setActiveProjectId: (projectId: number | null) => void;
   navigateToProject: (projectId: number) => void;
   navigateToSessions: () => void;
   navigateToPaneChat: () => void;
+  navigateToUsage: () => void;
 }
 
 export const useNavigationStore = create<NavigationState>((set, get) => ({
@@ -118,4 +126,10 @@ export const useNavigationStore = create<NavigationState>((set, get) => ({
     activeView: 'pane-chat',
     activeProjectId: null
   }),
+
+  // Usage is reported per host, not per project.
+  navigateToUsage: () => set({
+    activeView: 'usage',
+    activeProjectId: null
+  }),
 }));
diff --git a/frontend/src/types/electron.d.ts b/frontend/src/types/electron.d.ts
index 52281e2a..0ef3d395 100644
--- a/frontend/src/types/electron.d.ts
+++ b/frontend/src/types/electron.d.ts
@@ -27,6 +27,7 @@ import type {
 import type { ToolPanel } from '../../../shared/types/panels';
 import type { PanelAgentStatusEvent } from '../../../shared/types/agentStatus';
 import type { PaneChatAgent, PaneChatState } from '../../../shared/types/paneChat';
+import type { UsageIndexStatus, UsageReport, UsageReportRequest } from '../../../shared/types/usage';
 import type { CreateSessionRequest } from './session';
 import type { DetectedProjectConfig } from '../../../shared/types/projectConfig';
 import type { CloudVmState } from '../../../shared/types/cloud';
@@ -93,6 +94,13 @@ interface ElectronAPI {
     setAgent: (agent: PaneChatAgent) => Promise<IPCResponse<PaneChatState<Session>>>;
   };
 
+  // Token usage, cost and rate-limit reporting
+  usage: {
+    getReport: (request?: UsageReportRequest) => Promise<IPCResponse<UsageReport>>;
+    getStatus: () => Promise<IPCResponse<UsageIndexStatus>>;
+    rescan: () => Promise<IPCResponse<UsageIndexStatus>>;
+  };
+
   // Session management
   sessions: {
     getAll: () => Promise<IPCResponse>;
diff --git a/frontend/src/utils/api.ts b/frontend/src/utils/api.ts
index 6da34626..ad8f3e8f 100644
--- a/frontend/src/utils/api.ts
+++ b/frontend/src/utils/api.ts
@@ -4,6 +4,7 @@ import type { Project } from '../types/project';
 import type { UpdateConfigRequest } from '../types/config';
 import type { SessionCreationPreferences } from '../stores/sessionPreferencesStore';
 import type { PaneChatAgent, PaneChatState } from '../../../shared/types/paneChat';
+import type { UsageReportRequest } from '../../../shared/types/usage';
 import type {
   RemoteDaemonClientRecord,
   RemoteDaemonConnectionPair,
@@ -69,6 +70,24 @@ export class API {
     },
   };
 
+  // Token usage, cost and rate limits
+  static usage = {
+    /** Totals, time series, per-model breakdown and rolling-window state. */
+    async getReport(request?: UsageReportRequest) {
+      if (!isElectron()) throw new Error('Electron API not available');
+      return window.electronAPI.usage.getReport(request);
+    },
+    /** Health of the background transcript index. */
+    async getStatus() {
+      if (!isElectron()) throw new Error('Electron API not available');
+      return window.electronAPI.usage.getStatus();
+    },
+    async rescan() {
+      if (!isElectron()) throw new Error('Electron API not available');
+      return window.electronAPI.usage.rescan();
+    },
+  };
+
   // Session management
   static sessions = {
     async getAll() {
diff --git a/main/src/database/database.ts b/main/src/database/database.ts
index da7f6aeb..cd6514b9 100644
--- a/main/src/database/database.ts
+++ b/main/src/database/database.ts
@@ -2279,6 +2279,39 @@ export class DatabaseService {
         // Don't throw - allow app to continue
       }
     }
+
+    // Track which parser produced each transcript index, so a parser fix can
+    // invalidate stale rows instead of only applying to future transcripts.
+    const usageFilesInfo = this.db
+      .prepare("PRAGMA table_info(usage_files)")
+      .all() as SqliteTableInfo[];
+    const usageFilesExists = usageFilesInfo.length > 0;
+    const hasParserVersion = usageFilesInfo.some(
+      (col: SqliteTableInfo) => col.name === "parser_version",
+    );
+
+    if (usageFilesExists && !hasParserVersion) {
+      this.db
+        .prepare(
+          "ALTER TABLE usage_files ADD COLUMN parser_version INTEGER NOT NULL DEFAULT 0",
+        )
+        .run();
+      console.log("[Database] Added parser_version column to usage_files table");
+    }
+
+    // Codex states the model, session and cwd once at the top of a transcript.
+    // A scan resuming from a stored offset never sees those lines, so what they
+    // said is kept next to the offset they belong to.
+    const hasParseContext = usageFilesInfo.some(
+      (col: SqliteTableInfo) => col.name === "parse_context",
+    );
+
+    if (usageFilesExists && !hasParseContext) {
+      this.db
+        .prepare("ALTER TABLE usage_files ADD COLUMN parse_context TEXT")
+        .run();
+      console.log("[Database] Added parse_context column to usage_files table");
+    }
   }
 
   // Project operations
diff --git a/main/src/database/schema.sql b/main/src/database/schema.sql
index 841b632c..66878847 100644
--- a/main/src/database/schema.sql
+++ b/main/src/database/schema.sql
@@ -59,7 +59,57 @@ CREATE TABLE IF NOT EXISTS session_git_status_cache (
   FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
 );
 
+-- Incremental scan cursor for agent CLI transcript files. Pane reads these
+-- read-only. offset_bytes lets a re-scan resume instead of re-reading the file.
+-- parse_context carries the Codex model, session and cwd that the top of the
+-- transcript stated, since a resumed scan starts past those lines.
+-- NOTE this file is split on the statement separator at startup, so a comment
+-- must never contain one.
+CREATE TABLE IF NOT EXISTS usage_files (
+  path TEXT PRIMARY KEY,
+  provider TEXT NOT NULL,
+  size_bytes INTEGER NOT NULL,
+  mtime_ms INTEGER NOT NULL,
+  offset_bytes INTEGER NOT NULL DEFAULT 0,
+  last_scanned_ms INTEGER NOT NULL,
+  parser_version INTEGER NOT NULL DEFAULT 0,
+  parse_context TEXT
+);
+
+-- One row per assistant message with token accounting, normalised across
+-- providers. id is the provider message id when available, else path:offset.
+CREATE TABLE IF NOT EXISTS usage_events (
+  id TEXT PRIMARY KEY,
+  provider TEXT NOT NULL,
+  timestamp_ms INTEGER NOT NULL,
+  model TEXT NOT NULL,
+  input_tokens INTEGER NOT NULL DEFAULT 0,
+  output_tokens INTEGER NOT NULL DEFAULT 0,
+  cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+  cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
+  agent_session_id TEXT,
+  cwd TEXT,
+  source_path TEXT NOT NULL
+);
+
+-- Quota state as the provider itself reported it, newest sample per limit.
+-- Codex writes this into every token_count event. Claude reports nothing.
+CREATE TABLE IF NOT EXISTS usage_rate_limits (
+  provider TEXT NOT NULL,
+  limit_id TEXT NOT NULL,
+  scope TEXT NOT NULL,
+  used_percent REAL NOT NULL,
+  window_minutes INTEGER,
+  resets_at_ms INTEGER,
+  plan_type TEXT,
+  captured_at_ms INTEGER NOT NULL,
+  PRIMARY KEY (provider, limit_id, scope)
+);
+
 -- Index for faster lookups
+CREATE INDEX IF NOT EXISTS idx_usage_events_ts ON usage_events(timestamp_ms);
+CREATE INDEX IF NOT EXISTS idx_usage_events_model_ts ON usage_events(model, timestamp_ms);
+CREATE INDEX IF NOT EXISTS idx_usage_events_source ON usage_events(source_path);
 CREATE INDEX IF NOT EXISTS idx_session_outputs_session_id ON session_outputs(session_id);
 CREATE INDEX IF NOT EXISTS idx_session_outputs_timestamp ON session_outputs(timestamp);
 CREATE INDEX IF NOT EXISTS idx_conversation_messages_session_id ON conversation_messages(session_id);
diff --git a/main/src/database/schema.test.ts b/main/src/database/schema.test.ts
new file mode 100644
index 00000000..05bbe203
--- /dev/null
+++ b/main/src/database/schema.test.ts
@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * `DatabaseService.initializeSchema` splits this file on `;` and prepares each
+ * fragment. A `;` inside a comment therefore produces a comment-only fragment,
+ * which better-sqlite3 rejects with "The supplied SQL string contains no
+ * statements" — taking the whole database down with it, on every startup.
+ *
+ * The failure is total but the cause is invisible in review, so it is checked
+ * here rather than left to be rediscovered.
+ */
+describe('schema.sql', () => {
+  const schemaPath = path.join(__dirname, 'schema.sql');
+  const sql = fs.readFileSync(schemaPath, 'utf8');
+
+  it('splits into fragments that all contain a real statement', () => {
+    const offenders: string[] = [];
+
+    for (const fragment of sql.split(';')) {
+      const trimmed = fragment.trim();
+      if (!trimmed) continue;
+
+      const hasStatement = trimmed
+        .split('\n')
+        .some(line => line.trim() && !line.trim().startsWith('--'));
+
+      if (!hasStatement) offenders.push(trimmed.slice(0, 120));
+    }
+
+    expect(
+      offenders,
+      'A comment in schema.sql contains a ";" — remove it, or startup will throw.'
+    ).toEqual([]);
+  });
+
+  it('every statement is idempotent, since the file runs on every startup', () => {
+    const creates = sql.match(/CREATE\s+(TABLE|INDEX)(?!\s+IF\s+NOT\s+EXISTS)/gi) ?? [];
+    expect(creates).toEqual([]);
+  });
+});
diff --git a/main/src/index.ts b/main/src/index.ts
index 1b11f5fd..81f5db48 100644
--- a/main/src/index.ts
+++ b/main/src/index.ts
@@ -85,6 +85,7 @@ import { terminalPanelManager } from './services/terminalPanelManager';
 import { panelManager } from './services/panelManager';
 import { TerminalPanelState } from '../../shared/types/panels';
 import { worktreePoolManager } from './services/worktreePoolManager';
+import { usageManager } from './services/usage/usageManager';
 import { PtyHostSupervisor } from './ptyHost/ptyHostSupervisor';
 import { syncAutoStartOnBoot } from './utils/autoStart';
 import { createPaneDaemonHost, type PaneDaemonHost } from './daemon/bootstrap';
@@ -1264,6 +1265,14 @@ if (launchRemoteSetup) {
     }
   }, 5000); // Delay to not slow down app startup
 
+  // Index agent CLI transcripts for the usage page. Read-only, and deferred so
+  // a first pass over a large ~/.claude never delays window creation.
+  setTimeout(() => {
+    void usageManager.start().catch(error => {
+      console.warn('[Usage] Failed to start transcript indexing:', error);
+    });
+  }, 8000);
+
     app.on('activate', () => {
       if (BrowserWindow.getAllWindows().length === 0) {
         console.log('[Main] Activating app, creating new window...');
@@ -1289,6 +1298,8 @@ if (launchRemoteSetup) {
 
   logToFile('before-quit fired');
 
+  usageManager.stop();
+
   // Guard against multiple shutdown attempts
   if (shutdownInProgress) {
     logToFile('shutdown already in progress, skipping');
diff --git a/main/src/ipc/daemonRegistryBindings.test.ts b/main/src/ipc/daemonRegistryBindings.test.ts
index b2291bc3..fc76edfb 100644
--- a/main/src/ipc/daemonRegistryBindings.test.ts
+++ b/main/src/ipc/daemonRegistryBindings.test.ts
@@ -12,6 +12,7 @@ import { registerPromptHandlers } from './prompt';
 import { registerScriptHandlers } from './script';
 import { registerSessionHandlers } from './session';
 import { registerVoiceHandlers } from './voice';
+import { registerUsageHandlers } from './usage';
 import type { AppServices } from './types';
 
 vi.mock('../index', () => ({
@@ -38,6 +39,12 @@ vi.mock('../services/scriptExecutionTracker', () => ({
   scriptExecutionTracker: {},
 }));
 
+const USAGE_CHANNELS = [
+  'usage:get-report',
+  'usage:get-status',
+  'usage:rescan',
+] as const;
+
 const PROJECT_CHANNELS = [
   'projects:get-all',
   'projects:get-active',
@@ -360,6 +367,16 @@ describe('daemon registry IPC bindings', () => {
     expect(ipcMain.boundChannels.sort()).toEqual([...VOICE_CHANNELS].sort());
   });
 
+  it('binds daemon-owned usage channels through the shared registry', () => {
+    const registry = new PaneCommandRegistry();
+    const ipcMain = createIpcMainStub();
+
+    registerUsageHandlers(ipcMain, registry);
+
+    expect(registry.listChannels()).toEqual([...USAGE_CHANNELS].sort());
+    expect(ipcMain.boundChannels.sort()).toEqual([...USAGE_CHANNELS].sort());
+  });
+
   it('binds daemon-owned prompt channels through the shared registry', () => {
     const registry = new PaneCommandRegistry();
     const ipcMain = createIpcMainStub();
diff --git a/main/src/ipc/index.ts b/main/src/ipc/index.ts
index b4c71c86..6be8f651 100644
--- a/main/src/ipc/index.ts
+++ b/main/src/ipc/index.ts
@@ -26,6 +26,7 @@ import { registerResourceMonitorHandlers } from './resourceMonitor';
 import { registerOnboardingHandlers } from './onboarding';
 import { registerVoiceHandlers } from './voice';
 import { registerPaneChatHandlers } from './paneChat';
+import { registerUsageHandlers } from './usage';
 import { createDaemonBridgeRouter, registerDaemonBridgeHandlers } from './daemon';
 import { registerPermissionHandlers } from './permissions';
 import { PaneCommandRegistry } from '../daemon/commandRegistry';
@@ -77,6 +78,7 @@ export function registerIpcHandlers(services: AppServices): PaneCommandRegistry
   registerResourceMonitorHandlers(ipcMain, services, commandRegistry);
   registerVoiceHandlers(ipcMain, services, commandRegistry);
   registerPaneChatHandlers(ipcMain, services, commandRegistry);
+  registerUsageHandlers(ipcMain, commandRegistry);
   registerOnboardingHandlers(ipcMain, services);
   registerDaemonBridgeHandlers(ipcMain, bridgeRouter);
 
diff --git a/main/src/ipc/usage.ts b/main/src/ipc/usage.ts
new file mode 100644
index 00000000..b382d81e
--- /dev/null
+++ b/main/src/ipc/usage.ts
@@ -0,0 +1,57 @@
+import type { IpcMain } from 'electron';
+import type { PaneCommandRegistry } from '../daemon/commandRegistry';
+import { usageManager } from '../services/usage/usageManager';
+import type { UsageReportRequest } from '../../../shared/types/usage';
+
+export const DAEMON_USAGE_CHANNELS = [
+  'usage:get-report',
+  'usage:get-status',
+  'usage:rescan',
+] as const;
+
+/**
+ * Usage reporting reads the transcripts of whichever host actually runs the
+ * agents, so these channels are daemon-owned: when connected to a remote
+ * runtime the page reports that host's usage, not the laptop's.
+ */
+export function registerUsageHandlers(
+  ipcMain: IpcMain,
+  commandRegistry: PaneCommandRegistry,
+): void {
+  commandRegistry.register('usage:get-report', async (request?: UsageReportRequest) => {
+    try {
+      return { success: true, data: usageManager.getReport(request) };
+    } catch (error) {
+      console.error('[Usage] Failed to build report:', error);
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to build usage report',
+      };
+    }
+  });
+
+  commandRegistry.register('usage:get-status', async () => {
+    try {
+      return { success: true, data: usageManager.getStatus() };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to read usage index status',
+      };
+    }
+  });
+
+  commandRegistry.register('usage:rescan', async () => {
+    try {
+      return { success: true, data: await usageManager.rescan() };
+    } catch (error) {
+      console.error('[Usage] Rescan failed:', error);
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to rescan transcripts',
+      };
+    }
+  });
+
+  commandRegistry.bindChannels(ipcMain, DAEMON_USAGE_CHANNELS);
+}
diff --git a/main/src/preload.ts b/main/src/preload.ts
index 4ce5c9ad..c93afbd1 100644
--- a/main/src/preload.ts
+++ b/main/src/preload.ts
@@ -135,6 +135,7 @@ const DAEMON_OWNED_CHANNEL_PREFIXES = [
   'runpane:',
   'sessions:',
   'terminal:',
+  'usage:',
   'voice:',
 ] as const;
 
@@ -454,6 +455,13 @@ contextBridge.exposeInMainWorld('electronAPI', {
     setAgent: (agent: 'claude' | 'codex'): Promise<IPCResponse> => invokeIpc('pane-chat:set-agent', agent),
   },
 
+  // Token usage, cost and rate-limit reporting
+  usage: {
+    getReport: (request?: { fromMs?: number; toMs?: number; bucket?: 'hour' | 'day' }): Promise<IPCResponse> => invokeIpc('usage:get-report', request),
+    getStatus: (): Promise<IPCResponse> => invokeIpc('usage:get-status'),
+    rescan: (): Promise<IPCResponse> => invokeIpc('usage:rescan'),
+  },
+
   // Session management
   sessions: {
     getAll: (): Promise<IPCResponse> => invokeIpc('sessions:get-all'),
diff --git a/main/src/services/usage/jsonlScanner.codexContext.test.ts b/main/src/services/usage/jsonlScanner.codexContext.test.ts
new file mode 100644
index 00000000..5138aff3
--- /dev/null
+++ b/main/src/services/usage/jsonlScanner.codexContext.test.ts
@@ -0,0 +1,198 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm, writeFile, appendFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { scanJsonlFile } from './jsonlScanner';
+
+const FALLBACK_MS = 1_700_000_000_000;
+
+/**
+ * Codex names the model, session and cwd once, on the `session_meta` line at
+ * the very top of a transcript; its `token_count` events carry none of them.
+ * A scan that resumes at a byte offset is past that line for good, so the
+ * attribution has to be carried across the pass boundary.
+ *
+ * Without that, every event after the first pass was filed under model `codex`
+ * — which matches no entry in the price table — with no session and no cwd, so
+ * its cost went unpriced and the per-project breakdown lost the work entirely.
+ * The watcher rescans about every three seconds while an agent is running, so
+ * this was the normal case rather than an edge one.
+ */
+describe('scanJsonlFile carries Codex attribution across passes', () => {
+  let dir: string;
+  let file: string;
+
+  const meta = (model: string, sessionId: string, cwd: string) => JSON.stringify({
+    type: 'session_meta',
+    timestamp: '2026-05-01T09:00:00.000Z',
+    payload: { id: sessionId, model, cwd },
+  });
+
+  const turnContext = (model: string, cwd: string) => JSON.stringify({
+    type: 'turn_context',
+    timestamp: '2026-05-01T09:30:00.000Z',
+    payload: { model, cwd },
+  });
+
+  const tokenCount = (inputTokens: number, timestamp: string) => JSON.stringify({
+    type: 'event_msg',
+    timestamp,
+    payload: {
+      type: 'token_count',
+      info: { last_token_usage: { input_tokens: inputTokens, output_tokens: 2 } },
+    },
+  });
+
+  const assistantLine = JSON.stringify({
+    type: 'assistant',
+    timestamp: '2026-05-01T10:00:00.000Z',
+    message: { id: 'a', model: 'claude-sonnet-5', usage: { input_tokens: 10, output_tokens: 1 } },
+  });
+
+  /** Everything a usage row is filed under, ignoring where in the file it sat. */
+  const attribution = (result: {
+    events: Array<{
+      event: { model: string; agentSessionId: string | null; cwd: string | null; inputTokens: number };
+    }>;
+  }) => result.events.map(({ event }) => ({
+    model: event.model,
+    agentSessionId: event.agentSessionId,
+    cwd: event.cwd,
+    inputTokens: event.inputTokens,
+  }));
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'pane-usage-codex-'));
+    file = join(dir, 'rollout.jsonl');
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('reaches the same attribution as a single pass over the finished file', async () => {
+    await writeFile(
+      file,
+      `${meta('gpt-5.1-codex', 'sess-1', '/repo/alpha')}\n${tokenCount(10, '2026-05-01T10:00:00.000Z')}\n`,
+      'utf8'
+    );
+
+    const first = await scanJsonlFile(file, 'codex', 0, FALLBACK_MS);
+
+    // The agent keeps working: another turn lands, with no context line of its own.
+    await appendFile(file, `${tokenCount(20, '2026-05-01T10:05:00.000Z')}\n`, 'utf8');
+    const resumed = await scanJsonlFile(file, 'codex', first.nextOffsetBytes, FALLBACK_MS, first.context);
+
+    const incremental = [...attribution(first), ...attribution(resumed)];
+    const onePass = attribution(await scanJsonlFile(file, 'codex', 0, FALLBACK_MS));
+
+    expect(incremental).toEqual(onePass);
+    expect(incremental).toEqual([
+      { model: 'gpt-5.1-codex', agentSessionId: 'sess-1', cwd: '/repo/alpha', inputTokens: 10 },
+      { model: 'gpt-5.1-codex', agentSessionId: 'sess-1', cwd: '/repo/alpha', inputTokens: 20 },
+    ]);
+  });
+
+  it('loses the attribution when the previous pass hands nothing over', async () => {
+    await writeFile(
+      file,
+      `${meta('gpt-5.1-codex', 'sess-1', '/repo/alpha')}\n${tokenCount(10, '2026-05-01T10:00:00.000Z')}\n`,
+      'utf8'
+    );
+    const first = await scanJsonlFile(file, 'codex', 0, FALLBACK_MS);
+    await appendFile(file, `${tokenCount(20, '2026-05-01T10:05:00.000Z')}\n`, 'utf8');
+
+    // Exactly what the scanner used to do: a fresh context on every pass.
+    const blind = await scanJsonlFile(file, 'codex', first.nextOffsetBytes, FALLBACK_MS);
+
+    expect(attribution(blind)).toEqual([
+      { model: 'codex', agentSessionId: null, cwd: null, inputTokens: 20 },
+    ]);
+  });
+
+  it('hands the next pass what it will need', async () => {
+    await writeFile(
+      file,
+      `${meta('gpt-5.1-codex', 'sess-1', '/repo/alpha')}\n${tokenCount(10, '2026-05-01T10:00:00.000Z')}\n`,
+      'utf8'
+    );
+
+    const first = await scanJsonlFile(file, 'codex', 0, FALLBACK_MS);
+
+    expect(first.context).toEqual({
+      model: 'gpt-5.1-codex',
+      sessionId: 'sess-1',
+      cwd: '/repo/alpha',
+    });
+  });
+
+  it('follows a model change that arrives mid-session', async () => {
+    await writeFile(
+      file,
+      `${meta('gpt-5.1-codex', 'sess-1', '/repo/alpha')}\n${tokenCount(10, '2026-05-01T10:00:00.000Z')}\n`,
+      'utf8'
+    );
+    const first = await scanJsonlFile(file, 'codex', 0, FALLBACK_MS);
+
+    await appendFile(
+      file,
+      `${turnContext('gpt-5.3-codex', '/repo/beta')}\n${tokenCount(30, '2026-05-01T11:00:00.000Z')}\n`,
+      'utf8'
+    );
+    const second = await scanJsonlFile(file, 'codex', first.nextOffsetBytes, FALLBACK_MS, first.context);
+
+    expect(attribution(second)).toEqual([
+      { model: 'gpt-5.3-codex', agentSessionId: 'sess-1', cwd: '/repo/beta', inputTokens: 30 },
+    ]);
+    // The session id, which only session_meta ever states, is still carried.
+    expect(second.context).toEqual({
+      model: 'gpt-5.3-codex',
+      sessionId: 'sess-1',
+      cwd: '/repo/beta',
+    });
+  });
+
+  it('lets the file overrule a stale seed when it is read from the top again', async () => {
+    await writeFile(
+      file,
+      `${meta('gpt-5.1-codex', 'sess-new', '/repo/alpha')}\n${tokenCount(10, '2026-05-01T10:00:00.000Z')}\n`,
+      'utf8'
+    );
+
+    // What a rotated file's stored cursor would have offered.
+    const stale = { model: 'gpt-5-codex', sessionId: 'sess-old', cwd: '/repo/gone' };
+    const result = await scanJsonlFile(file, 'codex', 0, FALLBACK_MS, stale);
+
+    expect(attribution(result)).toEqual([
+      { model: 'gpt-5.1-codex', agentSessionId: 'sess-new', cwd: '/repo/alpha', inputTokens: 10 },
+    ]);
+  });
+
+  it('reports no context for Claude, whose lines each carry their own', async () => {
+    await writeFile(file, `${assistantLine}\n`, 'utf8');
+    const result = await scanJsonlFile(file, 'claude', 0, FALLBACK_MS);
+    expect(result.context).toBeNull();
+  });
+
+  it('does not replay quota samples the seed was never meant to hold', async () => {
+    const withLimits = JSON.stringify({
+      type: 'event_msg',
+      timestamp: '2026-05-01T10:00:00.000Z',
+      payload: {
+        type: 'token_count',
+        info: { last_token_usage: { input_tokens: 10, output_tokens: 2 } },
+        rate_limits: { limit_id: 'codex', primary: { used_percent: 42, window_minutes: 300 } },
+      },
+    });
+    await writeFile(file, `${meta('gpt-5.1-codex', 'sess-1', '/repo/alpha')}\n${withLimits}\n`, 'utf8');
+    const first = await scanJsonlFile(file, 'codex', 0, FALLBACK_MS);
+    expect(first.rateLimits).toHaveLength(1);
+
+    await appendFile(file, `${tokenCount(20, '2026-05-01T10:05:00.000Z')}\n`, 'utf8');
+    const resumed = await scanJsonlFile(file, 'codex', first.nextOffsetBytes, FALLBACK_MS, first.context);
+
+    // A quota reading belongs to the moment it was taken and lives in its own
+    // table; carrying it forward would keep re-announcing a stale number.
+    expect(resumed.rateLimits).toEqual([]);
+  });
+});
diff --git a/main/src/services/usage/jsonlScanner.test.ts b/main/src/services/usage/jsonlScanner.test.ts
new file mode 100644
index 00000000..e8894d4f
--- /dev/null
+++ b/main/src/services/usage/jsonlScanner.test.ts
@@ -0,0 +1,174 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm, writeFile, appendFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { scanJsonlFile, resolveStartOffset, isFileUnchanged } from './jsonlScanner';
+
+const FALLBACK_MS = 1_700_000_000_000;
+
+function assistantLine(id: string, inputTokens: number): string {
+  return JSON.stringify({
+    type: 'assistant',
+    timestamp: '2026-05-01T10:00:00.000Z',
+    message: { id, model: 'claude-sonnet-5', usage: { input_tokens: inputTokens, output_tokens: 1 } },
+  });
+}
+
+describe('resolveStartOffset', () => {
+  it('starts at zero for an unseen file', () => {
+    expect(resolveStartOffset(null, 100)).toBe(0);
+  });
+
+  it('resumes from the stored offset', () => {
+    expect(resolveStartOffset({ sizeBytes: 100, offsetBytes: 80 }, 120)).toBe(80);
+  });
+
+  it('re-reads from the start when the file shrank (rotation or truncation)', () => {
+    expect(resolveStartOffset({ sizeBytes: 100, offsetBytes: 80 }, 40)).toBe(0);
+  });
+
+  it('never resumes past the current end of file', () => {
+    expect(resolveStartOffset({ sizeBytes: 100, offsetBytes: 999 }, 100)).toBe(100);
+  });
+});
+
+describe('isFileUnchanged', () => {
+  it('is false without a recorded cursor', () => {
+    expect(isFileUnchanged(null, { size: 10, mtimeMs: 1 })).toBe(false);
+  });
+
+  it('requires both size and mtime to match', () => {
+    expect(isFileUnchanged({ sizeBytes: 10, mtimeMs: 1 }, { size: 10, mtimeMs: 1 })).toBe(true);
+    expect(isFileUnchanged({ sizeBytes: 10, mtimeMs: 1 }, { size: 11, mtimeMs: 1 })).toBe(false);
+    expect(isFileUnchanged({ sizeBytes: 10, mtimeMs: 1 }, { size: 10, mtimeMs: 2 })).toBe(false);
+  });
+});
+
+describe('scanJsonlFile', () => {
+  let dir: string;
+  let file: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'pane-usage-'));
+    file = join(dir, 'transcript.jsonl');
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('parses every complete line of a fresh file', async () => {
+    await writeFile(file, `${assistantLine('a', 10)}\n${assistantLine('b', 20)}\n`, 'utf8');
+
+    const result = await scanJsonlFile(file, 'claude', 0, FALLBACK_MS);
+
+    expect(result.linesRead).toBe(2);
+    expect(result.events.map(e => e.event.inputTokens)).toEqual([10, 20]);
+  });
+
+  it('reads only the appended delta on a second pass', async () => {
+    await writeFile(file, `${assistantLine('a', 10)}\n`, 'utf8');
+    const first = await scanJsonlFile(file, 'claude', 0, FALLBACK_MS);
+
+    await appendFile(file, `${assistantLine('b', 20)}\n`, 'utf8');
+    const second = await scanJsonlFile(file, 'claude', first.nextOffsetBytes, FALLBACK_MS);
+
+    expect(second.events).toHaveLength(1);
+    expect(second.events[0].event.inputTokens).toBe(20);
+  });
+
+  it('keeps byte offsets aligned across multi-byte characters', async () => {
+    // A cwd with non-ASCII makes a character-count offset drift from the file.
+    const withUnicode = JSON.stringify({
+      type: 'assistant',
+      timestamp: '2026-05-01T10:00:00.000Z',
+      cwd: '/répertoire/工作/проект',
+      message: { id: 'u1', model: 'claude-sonnet-5', usage: { input_tokens: 7, output_tokens: 1 } },
+    });
+    await writeFile(file, `${withUnicode}\n`, 'utf8');
+
+    const first = await scanJsonlFile(file, 'claude', 0, FALLBACK_MS);
+    expect(first.nextOffsetBytes).toBe(Buffer.byteLength(`${withUnicode}\n`, 'utf8'));
+
+    await appendFile(file, `${assistantLine('b', 20)}\n`, 'utf8');
+    const second = await scanJsonlFile(file, 'claude', first.nextOffsetBytes, FALLBACK_MS);
+
+    expect(second.events).toHaveLength(1);
+    expect(second.events[0].event.messageId).toBe('b');
+  });
+
+  it('holds back a partially written trailing line until it completes', async () => {
+    const partial = assistantLine('b', 20).slice(0, 30);
+    await writeFile(file, `${assistantLine('a', 10)}\n${partial}`, 'utf8');
+
+    const first = await scanJsonlFile(file, 'claude', 0, FALLBACK_MS);
+
+    // Only the complete line is reported, and the cursor stops before the partial one.
+    expect(first.events).toHaveLength(1);
+    expect(first.events[0].event.messageId).toBe('a');
+    expect(first.nextOffsetBytes).toBe(Buffer.byteLength(`${assistantLine('a', 10)}\n`, 'utf8'));
+
+    // Finish the line; the second pass picks it up exactly once.
+    await writeFile(file, `${assistantLine('a', 10)}\n${assistantLine('b', 20)}\n`, 'utf8');
+    const second = await scanJsonlFile(file, 'claude', first.nextOffsetBytes, FALLBACK_MS);
+
+    expect(second.events).toHaveLength(1);
+    expect(second.events[0].event.messageId).toBe('b');
+  });
+
+  it('returns nothing for an empty file', async () => {
+    await writeFile(file, '', 'utf8');
+    const result = await scanJsonlFile(file, 'claude', 0, FALLBACK_MS);
+    expect(result).toEqual({
+      events: [], nextOffsetBytes: 0, linesRead: 0, rateLimits: [], context: null,
+    });
+  });
+
+  it('surfaces Codex quota samples alongside the events', async () => {
+    const line = JSON.stringify({
+      timestamp: '2026-05-01T11:00:00.000Z',
+      type: 'event_msg',
+      payload: {
+        type: 'token_count',
+        info: { last_token_usage: { input_tokens: 10, output_tokens: 5 } },
+        rate_limits: { limit_id: 'codex', primary: { used_percent: 42, window_minutes: 300 } },
+      },
+    });
+    await writeFile(file, `${line}\n`, 'utf8');
+
+    const result = await scanJsonlFile(file, 'codex', 0, FALLBACK_MS);
+
+    expect(result.events).toHaveLength(1);
+    expect(result.rateLimits).toHaveLength(1);
+    expect(result.rateLimits[0].usedPercent).toBe(42);
+  });
+
+  it('reports no quota samples for Claude, which does not publish any', async () => {
+    await writeFile(file, `${assistantLine('a', 10)}\n`, 'utf8');
+    const result = await scanJsonlFile(file, 'claude', 0, FALLBACK_MS);
+    expect(result.rateLimits).toEqual([]);
+  });
+
+  it('skips malformed lines without losing the rest of the file', async () => {
+    await writeFile(
+      file,
+      `${assistantLine('a', 10)}\nnot json\n{"type":"assistant"\n${assistantLine('b', 20)}\n`,
+      'utf8'
+    );
+
+    const result = await scanJsonlFile(file, 'claude', 0, FALLBACK_MS);
+
+    expect(result.linesRead).toBe(4);
+    expect(result.events.map(e => e.event.messageId)).toEqual(['a', 'b']);
+  });
+
+  it('reports byte offsets that point at the start of each line', async () => {
+    const lineA = assistantLine('a', 10);
+    await writeFile(file, `${lineA}\n${assistantLine('b', 20)}\n`, 'utf8');
+
+    const result = await scanJsonlFile(file, 'claude', 0, FALLBACK_MS);
+
+    expect(result.events[0].byteOffset).toBe(0);
+    expect(result.events[1].byteOffset).toBe(Buffer.byteLength(`${lineA}\n`, 'utf8'));
+  });
+});
diff --git a/main/src/services/usage/jsonlScanner.ts b/main/src/services/usage/jsonlScanner.ts
new file mode 100644
index 00000000..ec3958ae
--- /dev/null
+++ b/main/src/services/usage/jsonlScanner.ts
@@ -0,0 +1,159 @@
+import { createReadStream } from 'fs';
+import { stat } from 'fs/promises';
+import { createInterface } from 'readline';
+import type { UsageEvent, UsageProvider, UsageRateLimitSample } from '../../../../shared/types/usage';
+import {
+  createCodexContext,
+  parseUsageLine,
+  snapshotCodexContext,
+  type CodexContextSnapshot,
+} from './usageParser';
+
+export interface ScannedFile {
+  /** Events parsed from the bytes read in this pass. */
+  events: Array<{ event: UsageEvent; byteOffset: number }>;
+  /** Byte offset to resume from next time — end of the last *complete* line. */
+  nextOffsetBytes: number;
+  linesRead: number;
+  /** Provider-reported quota state observed in this pass, newest per limit. */
+  rateLimits: UsageRateLimitSample[];
+  /**
+   * Codex attribution as it stood at `nextOffsetBytes`, to be handed back to
+   * the next pass. Null for Claude, whose lines each carry their own.
+   */
+  context: CodexContextSnapshot | null;
+}
+
+/**
+ * Read a JSONL transcript from `startOffset` and parse its usage events.
+ *
+ * Two details make this safe to re-run continuously:
+ *
+ * 1. **Byte-accurate offsets.** Offsets advance by `Buffer.byteLength(line)`,
+ *    not `line.length` — transcripts contain non-ASCII, and a character count
+ *    would desynchronise the cursor from the file.
+ * 2. **Complete lines only.** An agent may be mid-write when we read, so the
+ *    cursor only advances past lines that ended with a newline. A partial
+ *    trailing line is re-read on the next pass instead of being lost or
+ *    double-counted.
+ * 3. **Carried attribution.** Codex names the model, session and cwd once, at
+ *    the top of the transcript. A pass that starts at an offset is past them,
+ *    so `seedContext` — what the previous pass ended with — stands in for the
+ *    lines it cannot see.
+ */
+export async function scanJsonlFile(
+  path: string,
+  provider: UsageProvider,
+  startOffset: number,
+  fallbackTimestampMs: number,
+  seedContext?: CodexContextSnapshot | null
+): Promise<ScannedFile> {
+  // Determine up front whether the file currently ends mid-line; the answer
+  // decides whether the final emitted line may be trusted.
+  const endsWithNewline = await fileEndsWithNewline(path);
+
+  const events: Array<{ event: UsageEvent; byteOffset: number }> = [];
+  let offset = startOffset;
+  let lastLineStart = startOffset;
+  let linesRead = 0;
+
+  const stream = createReadStream(path, { start: startOffset, encoding: 'utf8' });
+  const reader = createInterface({ input: stream, crlfDelay: Infinity });
+
+  // Codex attributes usage from earlier lines in the same file (model, session,
+  // cwd), so the parser carries state across the whole transcript — including
+  // across the pass boundary, via the seed.
+  const codexContext = provider === 'codex' ? createCodexContext(seedContext) : undefined;
+  const collectedRateLimits = (): UsageRateLimitSample[] =>
+    codexContext ? [...codexContext.rateLimits.values()] : [];
+  const carriedContext = (): CodexContextSnapshot | null =>
+    codexContext ? snapshotCodexContext(codexContext) : null;
+
+  try {
+    for await (const line of reader) {
+      lastLineStart = offset;
+      // readline strips the terminator, so add it back to keep the cursor
+      // aligned with the file's actual bytes.
+      offset += Buffer.byteLength(line, 'utf8') + 1;
+
+      const event = parseUsageLine(provider, line, fallbackTimestampMs, codexContext);
+      if (event) events.push({ event, byteOffset: lastLineStart });
+      linesRead += 1;
+    }
+  } finally {
+    reader.close();
+    stream.destroy();
+  }
+
+  if (endsWithNewline || linesRead === 0) {
+    return {
+      events,
+      nextOffsetBytes: offset,
+      linesRead,
+      rateLimits: collectedRateLimits(),
+      context: carriedContext(),
+    };
+  }
+
+  // The last line was still being written. Rewind to its start and discard
+  // anything parsed from it, so the completed line is picked up next pass.
+  //
+  // The carried context is not rewound with it. A half-written line is either
+  // invalid JSON, which changes nothing, or a complete object whose newline has
+  // not landed yet — and re-reading that line next pass sets the same fields to
+  // the same values.
+  while (events.length > 0 && events[events.length - 1].byteOffset >= lastLineStart) {
+    events.pop();
+  }
+  return {
+    events,
+    nextOffsetBytes: Math.max(startOffset, lastLineStart),
+    linesRead: linesRead - 1,
+    rateLimits: collectedRateLimits(),
+    context: carriedContext(),
+  };
+}
+
+/**
+ * Whether the file's final byte is a newline. Only the last byte is read, so
+ * this stays cheap even for very large transcripts.
+ */
+async function fileEndsWithNewline(path: string): Promise<boolean> {
+  const stats = await stat(path);
+  if (stats.size === 0) return true;
+
+  return new Promise<boolean>((resolve) => {
+    const stream = createReadStream(path, { start: stats.size - 1, end: stats.size - 1 });
+    let byte: number | null = null;
+    stream.on('data', (chunk: string | Buffer) => {
+      const buffer = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+      if (buffer.length > 0) byte = buffer[buffer.length - 1];
+    });
+    stream.on('error', () => resolve(true));
+    stream.on('close', () => resolve(byte === 0x0a));
+  });
+}
+
+/**
+ * Decide where to resume reading a file.
+ *
+ * A file smaller than the recorded size was truncated or rotated, so its
+ * cursor is meaningless and the whole file is re-read.
+ */
+export function resolveStartOffset(
+  recorded: { sizeBytes: number; offsetBytes: number } | null,
+  currentSize: number
+): number {
+  if (!recorded) return 0;
+  if (currentSize < recorded.sizeBytes) return 0;
+  return Math.min(recorded.offsetBytes, currentSize);
+}
+
+/** True when the file is byte-for-byte what we last indexed. */
+export function isFileUnchanged(
+  recorded: { sizeBytes: number; mtimeMs: number } | null,
+  stats: { size: number; mtimeMs: number }
+): boolean {
+  if (!recorded) return false;
+  return recorded.sizeBytes === stats.size && recorded.mtimeMs === stats.mtimeMs;
+}
diff --git a/main/src/services/usage/modelPricing.test.ts b/main/src/services/usage/modelPricing.test.ts
new file mode 100644
index 00000000..b17a2d2f
--- /dev/null
+++ b/main/src/services/usage/modelPricing.test.ts
@@ -0,0 +1,113 @@
+import { describe, it, expect } from 'vitest';
+import { findModelPrice, estimateCostUsd, MODEL_PRICES, PRICING_AS_OF } from './modelPricing';
+
+describe('findModelPrice', () => {
+  it('resolves Claude models', () => {
+    expect(findModelPrice('claude-opus-5')?.model).toBe('claude-opus-5');
+    expect(findModelPrice('claude-sonnet-5-20260101')?.model).toBe('claude-sonnet-5');
+  });
+
+  it('resolves OpenAI and Codex models', () => {
+    expect(findModelPrice('gpt-5')?.model).toBe('gpt-5');
+    expect(findModelPrice('gpt-5-codex')?.model).toBe('gpt-5-codex');
+    expect(findModelPrice('gpt-5.3-codex')?.model).toBe('gpt-5.3-codex');
+    expect(findModelPrice('gpt-5.6-terra')?.model).toBe('gpt-5.6-terra');
+  });
+
+  it('prefers the longest matching id so variants beat their base model', () => {
+    // Every one of these also contains the shorter "gpt-5".
+    expect(findModelPrice('gpt-5-mini')?.model).toBe('gpt-5-mini');
+    expect(findModelPrice('gpt-5-nano')?.model).toBe('gpt-5-nano');
+    expect(findModelPrice('gpt-5-pro')?.model).toBe('gpt-5-pro');
+    expect(findModelPrice('gpt-5.4-mini')?.model).toBe('gpt-5.4-mini');
+    expect(findModelPrice('gpt-5.5-pro')?.model).toBe('gpt-5.5-pro');
+    expect(findModelPrice('gpt-5.1-codex')?.model).toBe('gpt-5.1-codex');
+  });
+
+  it('tolerates dated and prefixed ids', () => {
+    expect(findModelPrice('gpt-5.3-codex-20260224')?.model).toBe('gpt-5.3-codex');
+    expect(findModelPrice('openai/gpt-5-mini')?.model).toBe('gpt-5-mini');
+    expect(findModelPrice('GPT-5-CODEX')?.model).toBe('gpt-5-codex');
+  });
+
+  it('returns null for unknown or empty models', () => {
+    expect(findModelPrice('llama-4-70b')).toBeNull();
+    expect(findModelPrice('')).toBeNull();
+    // The Codex parser's fallback label is deliberately unpriced.
+    expect(findModelPrice('codex')).toBeNull();
+  });
+});
+
+describe('estimateCostUsd', () => {
+  it('prices a Claude request across all four token classes', () => {
+    // opus-5: 15 in / 75 out / 1.5 cache-read / 18.75 cache-write per Mtok.
+    const { costUsd, complete } = estimateCostUsd({
+      model: 'claude-opus-5',
+      inputTokens: 1_000_000,
+      outputTokens: 1_000_000,
+      cacheReadTokens: 1_000_000,
+      cacheCreationTokens: 1_000_000,
+    });
+    expect(complete).toBe(true);
+    expect(costUsd).toBeCloseTo(15 + 75 + 1.5 + 18.75, 6);
+  });
+
+  it('prices a Codex request', () => {
+    const { costUsd, complete } = estimateCostUsd({
+      model: 'gpt-5-codex',
+      inputTokens: 1_000_000,
+      outputTokens: 1_000_000,
+      cacheReadTokens: 0,
+      cacheCreationTokens: 0,
+    });
+    expect(complete).toBe(true);
+    expect(costUsd).toBeCloseTo(11.25, 6);
+  });
+
+  it('reports incomplete rather than guessing for an unknown model', () => {
+    const { costUsd, complete } = estimateCostUsd({
+      model: 'mystery-model',
+      inputTokens: 5_000_000,
+      outputTokens: 5_000_000,
+      cacheReadTokens: 0,
+      cacheCreationTokens: 0,
+    });
+    expect(complete).toBe(false);
+    expect(costUsd).toBe(0);
+  });
+
+  it('returns zero for zero tokens', () => {
+    expect(estimateCostUsd({
+      model: 'gpt-5',
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheCreationTokens: 0,
+    }).costUsd).toBe(0);
+  });
+});
+
+describe('price table integrity', () => {
+  it('covers both providers', () => {
+    expect(MODEL_PRICES.some(p => p.model.startsWith('claude-'))).toBe(true);
+    expect(MODEL_PRICES.some(p => p.model.startsWith('gpt-'))).toBe(true);
+  });
+
+  it('has no duplicate model ids', () => {
+    const ids = MODEL_PRICES.map(p => p.model);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('has non-negative prices and output at least input', () => {
+    for (const price of MODEL_PRICES) {
+      expect(price.inputPerMTok).toBeGreaterThan(0);
+      expect(price.outputPerMTok).toBeGreaterThanOrEqual(price.inputPerMTok);
+      expect(price.cacheReadPerMTok).toBeGreaterThanOrEqual(0);
+      expect(price.cacheWritePerMTok).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  it('carries a parseable as-of date, which the UI footer shows', () => {
+    expect(Number.isNaN(Date.parse(PRICING_AS_OF))).toBe(false);
+  });
+});
diff --git a/main/src/services/usage/modelPricing.ts b/main/src/services/usage/modelPricing.ts
new file mode 100644
index 00000000..e663efe6
--- /dev/null
+++ b/main/src/services/usage/modelPricing.ts
@@ -0,0 +1,108 @@
+import type { ModelPrice } from '../../../../shared/types/usage';
+
+/**
+ * Bundled price table, USD per 1M tokens.
+ *
+ * Hard-coded prices go stale, so {@link PRICING_AS_OF} is rendered in the
+ * usage page footer and unknown models are reported as `costIncomplete`
+ * rather than silently priced at zero.
+ */
+export const PRICING_AS_OF = '2026-08-10';
+
+/**
+ * OpenAI publishes no separate cache-write price — writing to the prompt cache
+ * bills at the standard input rate — so `cacheWritePerMTok` mirrors input for
+ * those models.
+ */
+const PRICES: ModelPrice[] = [
+  // --- Anthropic (Claude Code) ---
+  // Claude 5 family
+  { model: 'claude-opus-5', inputPerMTok: 15, outputPerMTok: 75, cacheReadPerMTok: 1.5, cacheWritePerMTok: 18.75 },
+  { model: 'claude-sonnet-5', inputPerMTok: 3, outputPerMTok: 15, cacheReadPerMTok: 0.3, cacheWritePerMTok: 3.75 },
+  { model: 'claude-fable-5', inputPerMTok: 3, outputPerMTok: 15, cacheReadPerMTok: 0.3, cacheWritePerMTok: 3.75 },
+  // Claude 4.x family
+  { model: 'claude-opus-4', inputPerMTok: 15, outputPerMTok: 75, cacheReadPerMTok: 1.5, cacheWritePerMTok: 18.75 },
+  { model: 'claude-sonnet-4', inputPerMTok: 3, outputPerMTok: 15, cacheReadPerMTok: 0.3, cacheWritePerMTok: 3.75 },
+  { model: 'claude-haiku-4-5', inputPerMTok: 1, outputPerMTok: 5, cacheReadPerMTok: 0.1, cacheWritePerMTok: 1.25 },
+  { model: 'claude-3-5-haiku', inputPerMTok: 0.8, outputPerMTok: 4, cacheReadPerMTok: 0.08, cacheWritePerMTok: 1 },
+
+  // --- OpenAI (Codex) ---
+  // Codex variants first: they are the models the Codex CLI actually reports.
+  { model: 'gpt-5.3-codex', inputPerMTok: 1.75, outputPerMTok: 14, cacheReadPerMTok: 0.175, cacheWritePerMTok: 1.75 },
+  { model: 'gpt-5.1-codex', inputPerMTok: 1.25, outputPerMTok: 10, cacheReadPerMTok: 0.125, cacheWritePerMTok: 1.25 },
+  { model: 'gpt-5-codex', inputPerMTok: 1.25, outputPerMTok: 10, cacheReadPerMTok: 0.125, cacheWritePerMTok: 1.25 },
+  // GPT-5.6 line
+  { model: 'gpt-5.6-sol', inputPerMTok: 5, outputPerMTok: 30, cacheReadPerMTok: 0.5, cacheWritePerMTok: 5 },
+  { model: 'gpt-5.6-terra', inputPerMTok: 2, outputPerMTok: 12, cacheReadPerMTok: 0.2, cacheWritePerMTok: 2 },
+  { model: 'gpt-5.6-luna', inputPerMTok: 0.2, outputPerMTok: 1.2, cacheReadPerMTok: 0.02, cacheWritePerMTok: 0.2 },
+  // GPT-5.5 / 5.4 lines
+  { model: 'gpt-5.5-pro', inputPerMTok: 30, outputPerMTok: 180, cacheReadPerMTok: 30, cacheWritePerMTok: 30 },
+  { model: 'gpt-5.5', inputPerMTok: 5, outputPerMTok: 30, cacheReadPerMTok: 0.5, cacheWritePerMTok: 5 },
+  { model: 'gpt-5.4-pro', inputPerMTok: 30, outputPerMTok: 180, cacheReadPerMTok: 30, cacheWritePerMTok: 30 },
+  { model: 'gpt-5.4-mini', inputPerMTok: 0.75, outputPerMTok: 4.5, cacheReadPerMTok: 0.075, cacheWritePerMTok: 0.75 },
+  { model: 'gpt-5.4-nano', inputPerMTok: 0.2, outputPerMTok: 1.25, cacheReadPerMTok: 0.02, cacheWritePerMTok: 0.2 },
+  { model: 'gpt-5.4', inputPerMTok: 2.5, outputPerMTok: 15, cacheReadPerMTok: 0.25, cacheWritePerMTok: 2.5 },
+  // GPT-5.2 / 5.1 lines
+  { model: 'gpt-5.2-pro', inputPerMTok: 21, outputPerMTok: 168, cacheReadPerMTok: 21, cacheWritePerMTok: 21 },
+  { model: 'gpt-5.2', inputPerMTok: 1.75, outputPerMTok: 14, cacheReadPerMTok: 0.175, cacheWritePerMTok: 1.75 },
+  { model: 'gpt-5.1', inputPerMTok: 1.25, outputPerMTok: 10, cacheReadPerMTok: 0.125, cacheWritePerMTok: 1.25 },
+  // Base GPT-5 line
+  { model: 'gpt-5-pro', inputPerMTok: 15, outputPerMTok: 120, cacheReadPerMTok: 15, cacheWritePerMTok: 15 },
+  { model: 'gpt-5-mini', inputPerMTok: 0.25, outputPerMTok: 2, cacheReadPerMTok: 0.025, cacheWritePerMTok: 0.25 },
+  { model: 'gpt-5-nano', inputPerMTok: 0.05, outputPerMTok: 0.4, cacheReadPerMTok: 0.005, cacheWritePerMTok: 0.05 },
+  { model: 'gpt-5', inputPerMTok: 1.25, outputPerMTok: 10, cacheReadPerMTok: 0.125, cacheWritePerMTok: 1.25 },
+];
+
+/**
+ * Match by longest prefix so dated ids (`claude-sonnet-5-20260101`) and
+ * region-prefixed ids resolve to their base model.
+ */
+export function findModelPrice(model: string): ModelPrice | null {
+  if (!model) return null;
+  const normalized = model.toLowerCase();
+
+  let best: ModelPrice | null = null;
+  for (const price of PRICES) {
+    if (!normalized.includes(price.model)) continue;
+    if (!best || price.model.length > best.model.length) best = price;
+  }
+  return best;
+}
+
+export interface CostInput {
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheCreationTokens: number;
+}
+
+/**
+ * Estimate cost in USD. `complete` is false when the model has no price
+ * entry, so the UI can mark the figure as a lower bound.
+ *
+ * `cacheSavingsUsd` is the counterfactual: what those cached input tokens
+ * would have cost at the full input rate had the cache missed.
+ */
+export function estimateCostUsd(
+  input: CostInput
+): { costUsd: number; complete: boolean; cacheSavingsUsd: number } {
+  const price = findModelPrice(input.model);
+  if (!price) return { costUsd: 0, complete: false, cacheSavingsUsd: 0 };
+
+  const perToken = 1_000_000;
+  const costUsd =
+    (input.inputTokens * price.inputPerMTok
+      + input.outputTokens * price.outputPerMTok
+      + input.cacheReadTokens * price.cacheReadPerMTok
+      + input.cacheCreationTokens * price.cacheWritePerMTok) / perToken;
+
+  const cacheSavingsUsd = Math.max(
+    input.cacheReadTokens * (price.inputPerMTok - price.cacheReadPerMTok) / perToken,
+    0
+  );
+
+  return { costUsd, complete: true, cacheSavingsUsd };
+}
+
+export { PRICES as MODEL_PRICES };
diff --git a/main/src/services/usage/usageAggregator.test.ts b/main/src/services/usage/usageAggregator.test.ts
new file mode 100644
index 00000000..cd1a249a
--- /dev/null
+++ b/main/src/services/usage/usageAggregator.test.ts
@@ -0,0 +1,262 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import Database from 'better-sqlite3-multiple-ciphers';
+import { UsageAggregator, resolveReportRange } from './usageAggregator';
+import { USAGE_WINDOW_HOURS } from '../../../../shared/types/usage';
+
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+const NOW = Date.UTC(2026, 4, 15, 12, 0, 0);
+
+function createDb() {
+  const db = new Database(':memory:');
+  db.exec(`
+    CREATE TABLE usage_events (
+      id TEXT PRIMARY KEY,
+      provider TEXT NOT NULL,
+      timestamp_ms INTEGER NOT NULL,
+      model TEXT NOT NULL,
+      input_tokens INTEGER NOT NULL DEFAULT 0,
+      output_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
+      agent_session_id TEXT,
+      cwd TEXT,
+      source_path TEXT NOT NULL
+    );
+  `);
+  return db;
+}
+
+let db: ReturnType<typeof createDb>;
+let aggregator: UsageAggregator;
+let seq = 0;
+
+function seed(options: {
+  timestampMs: number;
+  model?: string;
+  provider?: string;
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+}) {
+  seq += 1;
+  db.prepare(`
+    INSERT INTO usage_events (id, provider, timestamp_ms, model, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, source_path)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    `e${seq}`,
+    options.provider ?? 'claude',
+    options.timestampMs,
+    options.model ?? 'claude-sonnet-5',
+    options.input ?? 0,
+    options.output ?? 0,
+    options.cacheRead ?? 0,
+    options.cacheWrite ?? 0,
+    '/t.jsonl'
+  );
+}
+
+beforeEach(() => {
+  db = createDb();
+  aggregator = new UsageAggregator(db);
+  seq = 0;
+});
+
+describe('UsageAggregator.getTotals', () => {
+  it('returns zeroed totals for an empty database', () => {
+    const totals = aggregator.getTotals(0, NOW);
+    expect(totals.totalTokens).toBe(0);
+    expect(totals.messageCount).toBe(0);
+    expect(totals.estimatedCostUsd).toBe(0);
+    expect(totals.costIncomplete).toBe(false);
+  });
+
+  it('sums every token category and counts messages', () => {
+    seed({ timestampMs: NOW - HOUR_MS, input: 100, output: 50, cacheRead: 20, cacheWrite: 10 });
+    seed({ timestampMs: NOW - 2 * HOUR_MS, input: 200, output: 60 });
+
+    const totals = aggregator.getTotals(NOW - DAY_MS, NOW);
+
+    expect(totals.inputTokens).toBe(300);
+    expect(totals.outputTokens).toBe(110);
+    expect(totals.cacheReadTokens).toBe(20);
+    expect(totals.cacheCreationTokens).toBe(10);
+    expect(totals.totalTokens).toBe(440);
+    expect(totals.messageCount).toBe(2);
+  });
+
+  it('excludes events outside the requested range', () => {
+    seed({ timestampMs: NOW - 40 * DAY_MS, input: 1000 });
+    seed({ timestampMs: NOW - HOUR_MS, input: 10 });
+
+    expect(aggregator.getTotals(NOW - 30 * DAY_MS, NOW).inputTokens).toBe(10);
+  });
+
+  it('flags costs as incomplete when a model has no price entry', () => {
+    seed({ timestampMs: NOW - HOUR_MS, model: 'some-unlisted-model', input: 100, output: 10 });
+
+    const totals = aggregator.getTotals(NOW - DAY_MS, NOW);
+    expect(totals.costIncomplete).toBe(true);
+    expect(totals.estimatedCostUsd).toBe(0);
+  });
+
+  it('prices each model separately rather than blending rates', () => {
+    seed({ timestampMs: NOW - HOUR_MS, model: 'claude-opus-5', input: 1_000_000 });
+    seed({ timestampMs: NOW - HOUR_MS, model: 'claude-sonnet-5', input: 1_000_000 });
+
+    // Opus input is $15/Mtok and Sonnet $3/Mtok.
+    expect(aggregator.getTotals(NOW - DAY_MS, NOW).estimatedCostUsd).toBeCloseTo(18, 6);
+  });
+
+  it('prices OpenAI / Codex models, not just Claude', () => {
+    // gpt-5-codex: $1.25/Mtok input, $10/Mtok output.
+    seed({ timestampMs: NOW - HOUR_MS, provider: 'codex', model: 'gpt-5-codex', input: 1_000_000, output: 1_000_000 });
+
+    const totals = aggregator.getTotals(NOW - DAY_MS, NOW);
+    expect(totals.costIncomplete).toBe(false);
+    expect(totals.estimatedCostUsd).toBeCloseTo(11.25, 6);
+  });
+
+  it('resolves dated and versioned OpenAI ids to their base model', () => {
+    // Longest-prefix matching must pick gpt-5.3-codex, not the shorter gpt-5.
+    seed({ timestampMs: NOW - HOUR_MS, provider: 'codex', model: 'gpt-5.3-codex-20260224', input: 1_000_000 });
+
+    const totals = aggregator.getTotals(NOW - DAY_MS, NOW);
+    expect(totals.costIncomplete).toBe(false);
+    expect(totals.estimatedCostUsd).toBeCloseTo(1.75, 6);
+  });
+
+  it('filters by provider when asked', () => {
+    seed({ timestampMs: NOW - HOUR_MS, provider: 'claude', input: 10 });
+    seed({ timestampMs: NOW - HOUR_MS, provider: 'codex', model: 'gpt-5-codex', input: 90 });
+
+    expect(aggregator.getTotals(NOW - DAY_MS, NOW, ['claude']).inputTokens).toBe(10);
+    expect(aggregator.getTotals(NOW - DAY_MS, NOW, ['codex']).inputTokens).toBe(90);
+  });
+});
+
+describe('UsageAggregator.getByModel', () => {
+  it('groups by model and orders by volume', () => {
+    seed({ timestampMs: NOW - HOUR_MS, model: 'claude-sonnet-5', input: 10 });
+    seed({ timestampMs: NOW - HOUR_MS, model: 'claude-opus-5', input: 500 });
+
+    const byModel = aggregator.getByModel(NOW - DAY_MS, NOW);
+
+    expect(byModel).toHaveLength(2);
+    expect(byModel[0].model).toBe('claude-opus-5');
+    expect(byModel[0].provider).toBe('claude');
+  });
+});
+
+describe('UsageAggregator.getSeries', () => {
+  it('returns no buckets when there is no data', () => {
+    expect(aggregator.getSeries(NOW - DAY_MS, NOW, 'day')).toEqual([]);
+  });
+
+  it('collapses events into hourly buckets', () => {
+    seed({ timestampMs: NOW - 90 * 60 * 1000, input: 10 });
+    seed({ timestampMs: NOW - 80 * 60 * 1000, input: 20 });
+    seed({ timestampMs: NOW - 10 * 60 * 1000, input: 5 });
+
+    const series = aggregator.getSeries(NOW - DAY_MS, NOW, 'hour');
+
+    expect(series.length).toBeGreaterThanOrEqual(2);
+    expect(series.every((bucket, i) => i === 0 || bucket.bucketStartMs > series[i - 1].bucketStartMs)).toBe(true);
+    expect(series.reduce((sum, bucket) => sum + bucket.inputTokens, 0)).toBe(35);
+  });
+
+  it('merges several models within one bucket into a single point', () => {
+    seed({ timestampMs: NOW - HOUR_MS, model: 'claude-opus-5', input: 10 });
+    seed({ timestampMs: NOW - HOUR_MS, model: 'claude-sonnet-5', input: 20 });
+
+    const series = aggregator.getSeries(NOW - DAY_MS, NOW, 'hour');
+    const bucket = series.find(entry => entry.inputTokens === 30);
+    expect(bucket).toBeDefined();
+    expect(bucket?.messageCount).toBe(2);
+  });
+
+  it('buckets by day when asked', () => {
+    seed({ timestampMs: NOW - 2 * DAY_MS, input: 10 });
+    seed({ timestampMs: NOW - 2 * DAY_MS + HOUR_MS, input: 10 });
+
+    const series = aggregator.getSeries(NOW - 7 * DAY_MS, NOW, 'day');
+    expect(series).toHaveLength(1);
+    expect(series[0].inputTokens).toBe(20);
+  });
+});
+
+describe('UsageAggregator.getWindow', () => {
+  it('counts only events inside the rolling window', () => {
+    seed({ timestampMs: NOW - (USAGE_WINDOW_HOURS + 1) * HOUR_MS, input: 1000 });
+    seed({ timestampMs: NOW - HOUR_MS, input: 25 });
+
+    const window = aggregator.getWindow(NOW, null);
+
+    expect(window.windowHours).toBe(USAGE_WINDOW_HOURS);
+    expect(window.totals.inputTokens).toBe(25);
+  });
+
+  it('uses a configured limit and reports utilisation', () => {
+    seed({ timestampMs: NOW - HOUR_MS, input: 250 });
+
+    const window = aggregator.getWindow(NOW, 1000);
+
+    expect(window.limitSource).toBe('configured');
+    expect(window.limitTokens).toBe(1000);
+    expect(window.utilization).toBeCloseTo(0.25, 6);
+  });
+
+  it('clamps utilisation at 1 when usage exceeds the limit', () => {
+    seed({ timestampMs: NOW - HOUR_MS, input: 5000 });
+    expect(aggregator.getWindow(NOW, 1000).utilization).toBe(1);
+  });
+
+  it('falls back to the largest observed window when no limit is configured', () => {
+    seed({ timestampMs: NOW - 40 * DAY_MS, input: 900 });
+    seed({ timestampMs: NOW - HOUR_MS, input: 100 });
+
+    const window = aggregator.getWindow(NOW, null);
+
+    expect(window.limitSource).toBe('observed-max');
+    expect(window.limitTokens).toBe(900);
+  });
+
+  it('reports an unknown limit and no utilisation for an empty database', () => {
+    const window = aggregator.getWindow(NOW, null);
+
+    expect(window.limitSource).toBe('unknown');
+    expect(window.limitTokens).toBeNull();
+    expect(window.utilization).toBeNull();
+    expect(window.resetsAtMs).toBeNull();
+  });
+
+  it('reports when the oldest event in the window ages out', () => {
+    const oldest = NOW - 2 * HOUR_MS;
+    seed({ timestampMs: oldest, input: 10 });
+
+    expect(aggregator.getWindow(NOW, null).resetsAtMs).toBe(oldest + USAGE_WINDOW_HOURS * HOUR_MS);
+  });
+});
+
+describe('resolveReportRange', () => {
+  it('defaults to the trailing window ending now', () => {
+    const range = resolveReportRange(undefined, NOW, 30);
+    expect(range.toMs).toBe(NOW);
+    expect(range.fromMs).toBe(NOW - 30 * DAY_MS);
+  });
+
+  it('picks hourly buckets for short ranges and daily for long ones', () => {
+    expect(resolveReportRange({ fromMs: NOW - DAY_MS, toMs: NOW }, NOW, 30).bucket).toBe('hour');
+    expect(resolveReportRange({ fromMs: NOW - 30 * DAY_MS, toMs: NOW }, NOW, 30).bucket).toBe('day');
+  });
+
+  it('honours an explicit bucket', () => {
+    expect(resolveReportRange({ fromMs: NOW - 30 * DAY_MS, toMs: NOW, bucket: 'hour' }, NOW, 30).bucket).toBe('hour');
+  });
+
+  it('never returns an inverted range', () => {
+    const range = resolveReportRange({ fromMs: NOW, toMs: NOW - DAY_MS }, NOW, 30);
+    expect(range.fromMs).toBeLessThanOrEqual(range.toMs);
+  });
+});
diff --git a/main/src/services/usage/usageAggregator.ts b/main/src/services/usage/usageAggregator.ts
new file mode 100644
index 00000000..3e6d2536
--- /dev/null
+++ b/main/src/services/usage/usageAggregator.ts
@@ -0,0 +1,268 @@
+import { basename } from 'path';
+import type { Database } from 'better-sqlite3-multiple-ciphers';
+import {
+  USAGE_WINDOW_HOURS,
+  type UsageBucket,
+  type UsageByModel,
+  type UsageByProject,
+  type UsageProvider,
+  type UsageReportRequest,
+  type UsageTotals,
+  type UsageWindow,
+} from '../../../../shared/types/usage';
+import { estimateCostUsd } from './modelPricing';
+
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+
+interface TokenRow {
+  model: string;
+  provider: string;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+  message_count: number;
+}
+
+interface BucketRow extends TokenRow {
+  bucket_start_ms: number;
+}
+
+function emptyTotals(): UsageTotals {
+  return {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheCreationTokens: 0,
+    totalTokens: 0,
+    messageCount: 0,
+    estimatedCostUsd: 0,
+    costIncomplete: false,
+    cacheSavingsUsd: 0,
+  };
+}
+
+/**
+ * Fold per-model rows into one total, pricing each model separately — a single
+ * blended rate would be wrong whenever a range mixes Opus and Haiku traffic.
+ */
+function foldTotals(rows: TokenRow[]): UsageTotals {
+  const totals = emptyTotals();
+
+  for (const row of rows) {
+    totals.inputTokens += row.input_tokens;
+    totals.outputTokens += row.output_tokens;
+    totals.cacheReadTokens += row.cache_read_tokens;
+    totals.cacheCreationTokens += row.cache_creation_tokens;
+    totals.messageCount += row.message_count;
+
+    const { costUsd, complete, cacheSavingsUsd } = estimateCostUsd({
+      model: row.model,
+      inputTokens: row.input_tokens,
+      outputTokens: row.output_tokens,
+      cacheReadTokens: row.cache_read_tokens,
+      cacheCreationTokens: row.cache_creation_tokens,
+    });
+    totals.estimatedCostUsd += costUsd;
+    totals.cacheSavingsUsd += cacheSavingsUsd;
+    if (!complete) totals.costIncomplete = true;
+  }
+
+  totals.totalTokens =
+    totals.inputTokens + totals.outputTokens + totals.cacheReadTokens + totals.cacheCreationTokens;
+  return totals;
+}
+
+const AGGREGATE_COLUMNS = `
+  model,
+  provider,
+  SUM(input_tokens)          AS input_tokens,
+  SUM(output_tokens)         AS output_tokens,
+  SUM(cache_read_tokens)     AS cache_read_tokens,
+  SUM(cache_creation_tokens) AS cache_creation_tokens,
+  COUNT(*)                   AS message_count
+`;
+
+export class UsageAggregator {
+  constructor(private db: Database) {}
+
+  /**
+   * Per-model rollup for a time range. Buckets by model *and* provider so a
+   * model id shared across providers stays distinguishable.
+   */
+  getByModel(fromMs: number, toMs: number, providers?: UsageProvider[]): UsageByModel[] {
+    const { clause, params } = this.providerFilter(providers);
+    const rows = this.db.prepare(`
+      SELECT ${AGGREGATE_COLUMNS}
+      FROM usage_events
+      WHERE timestamp_ms >= ? AND timestamp_ms <= ? ${clause}
+      GROUP BY model, provider
+      ORDER BY SUM(input_tokens + output_tokens) DESC
+    `).all(fromMs, toMs, ...params) as TokenRow[];
+
+    return rows.map(row => ({
+      model: row.model,
+      provider: row.provider === 'codex' ? 'codex' : 'claude',
+      ...foldTotals([row]),
+    }));
+  }
+
+  /**
+   * Per-directory rollup — "which worktree spent my quota".
+   *
+   * The transcripts know nothing about Pane's sessions; the working directory
+   * each message recorded is the only link back to a project, so that is what
+   * is grouped on. Rows without a cwd are folded into one "Unknown" entry
+   * rather than dropped, so the parts still sum to the whole.
+   */
+  getByProject(fromMs: number, toMs: number, providers?: UsageProvider[]): UsageByProject[] {
+    const { clause, params } = this.providerFilter(providers);
+    const rows = this.db.prepare(`
+      SELECT cwd, ${AGGREGATE_COLUMNS}
+      FROM usage_events
+      WHERE timestamp_ms >= ? AND timestamp_ms <= ? ${clause}
+      GROUP BY cwd, model, provider
+    `).all(fromMs, toMs, ...params) as Array<TokenRow & { cwd: string | null }>;
+
+    const byPath = new Map<string, TokenRow[]>();
+    for (const row of rows) {
+      const path = row.cwd && row.cwd.trim().length > 0 ? row.cwd : '';
+      const existing = byPath.get(path);
+      if (existing) existing.push(row);
+      else byPath.set(path, [row]);
+    }
+
+    return [...byPath.entries()]
+      .map(([path, pathRows]) => ({
+        path,
+        label: path ? basename(path) || path : 'Unknown',
+        ...foldTotals(pathRows),
+      }))
+      .sort((a, b) => b.totalTokens - a.totalTokens);
+  }
+
+  getTotals(fromMs: number, toMs: number, providers?: UsageProvider[]): UsageTotals {
+    const { clause, params } = this.providerFilter(providers);
+    const rows = this.db.prepare(`
+      SELECT ${AGGREGATE_COLUMNS}
+      FROM usage_events
+      WHERE timestamp_ms >= ? AND timestamp_ms <= ? ${clause}
+      GROUP BY model, provider
+    `).all(fromMs, toMs, ...params) as TokenRow[];
+
+    return foldTotals(rows);
+  }
+
+  /**
+   * Time series. Bucketing is arithmetic on the epoch value rather than
+   * `strftime`, so it never depends on the SQLite build's timezone handling.
+   */
+  getSeries(
+    fromMs: number,
+    toMs: number,
+    bucket: 'hour' | 'day',
+    providers?: UsageProvider[]
+  ): UsageBucket[] {
+    const bucketMs = bucket === 'hour' ? HOUR_MS : DAY_MS;
+    const { clause, params } = this.providerFilter(providers);
+
+    const rows = this.db.prepare(`
+      SELECT
+        (timestamp_ms / ${bucketMs}) * ${bucketMs} AS bucket_start_ms,
+        ${AGGREGATE_COLUMNS}
+      FROM usage_events
+      WHERE timestamp_ms >= ? AND timestamp_ms <= ? ${clause}
+      GROUP BY bucket_start_ms, model, provider
+      ORDER BY bucket_start_ms ASC
+    `).all(fromMs, toMs, ...params) as BucketRow[];
+
+    const byBucket = new Map<number, TokenRow[]>();
+    for (const row of rows) {
+      const existing = byBucket.get(row.bucket_start_ms);
+      if (existing) existing.push(row);
+      else byBucket.set(row.bucket_start_ms, [row]);
+    }
+
+    return [...byBucket.entries()]
+      .sort((a, b) => a[0] - b[0])
+      .map(([bucketStartMs, bucketRows]) => ({ bucketStartMs, ...foldTotals(bucketRows) }));
+  }
+
+  /**
+   * Rolling-window utilisation — "how much of my quota is left".
+   *
+   * When no explicit limit is configured, the largest window ever observed is
+   * used as a proxy: it is a lower bound on the real cap, which makes the
+   * gauge useful without inventing a number.
+   */
+  getWindow(nowMs: number, configuredLimitTokens: number | null): UsageWindow {
+    const windowMs = USAGE_WINDOW_HOURS * HOUR_MS;
+    const windowStartMs = nowMs - windowMs;
+    const totals = this.getTotals(windowStartMs, nowMs);
+
+    const oldest = this.db.prepare(
+      'SELECT MIN(timestamp_ms) AS oldest FROM usage_events WHERE timestamp_ms >= ?'
+    ).get(windowStartMs) as { oldest: number | null };
+
+    let limitTokens = configuredLimitTokens;
+    let limitSource: UsageWindow['limitSource'] = configuredLimitTokens ? 'configured' : 'unknown';
+
+    if (!limitTokens) {
+      const observed = this.getObservedMaxWindowTokens(windowMs);
+      if (observed > 0) {
+        limitTokens = observed;
+        limitSource = 'observed-max';
+      }
+    }
+
+    return {
+      windowHours: USAGE_WINDOW_HOURS,
+      windowStartMs,
+      windowEndMs: nowMs,
+      totals,
+      limitTokens: limitTokens ?? null,
+      limitSource,
+      utilization: limitTokens ? Math.min(totals.totalTokens / limitTokens, 1) : null,
+      resetsAtMs: oldest.oldest ? oldest.oldest + windowMs : null,
+      recentHourTokens: this.getTotals(nowMs - HOUR_MS, nowMs).totalTokens,
+    };
+  }
+
+  /**
+   * Largest token count seen in any historical window, approximated by
+   * bucketing on window boundaries. Exact sliding maxima would require a scan
+   * over every event; the bucketed figure is close enough for a gauge.
+   */
+  private getObservedMaxWindowTokens(windowMs: number): number {
+    const row = this.db.prepare(`
+      SELECT MAX(window_tokens) AS peak FROM (
+        SELECT SUM(input_tokens + output_tokens + cache_read_tokens + cache_creation_tokens) AS window_tokens
+        FROM usage_events
+        GROUP BY timestamp_ms / ${windowMs}
+      )
+    `).get() as { peak: number | null };
+
+    return row.peak ?? 0;
+  }
+
+  private providerFilter(providers?: UsageProvider[]): { clause: string; params: string[] } {
+    if (!providers || providers.length === 0) return { clause: '', params: [] };
+    const placeholders = providers.map(() => '?').join(', ');
+    return { clause: `AND provider IN (${placeholders})`, params: [...providers] };
+  }
+}
+
+/** Normalise a report request into a concrete, bounded range. */
+export function resolveReportRange(
+  request: UsageReportRequest | undefined,
+  nowMs: number,
+  defaultDays: number
+): { fromMs: number; toMs: number; bucket: 'hour' | 'day' } {
+  const toMs = request?.toMs ?? nowMs;
+  const fromMs = request?.fromMs ?? toMs - defaultDays * DAY_MS;
+  // An hourly series over months would return thousands of points; pick the
+  // bucket from the range unless the caller was explicit.
+  const bucket = request?.bucket ?? (toMs - fromMs <= 2 * DAY_MS ? 'hour' : 'day');
+  return { fromMs: Math.min(fromMs, toMs), toMs, bucket };
+}
diff --git a/main/src/services/usage/usageManager.ts b/main/src/services/usage/usageManager.ts
new file mode 100644
index 00000000..a3a09722
--- /dev/null
+++ b/main/src/services/usage/usageManager.ts
@@ -0,0 +1,289 @@
+import { existsSync } from 'fs';
+import { stat } from 'fs/promises';
+import { homedir } from 'os';
+import { join } from 'path';
+import { glob } from 'glob';
+import chokidar, { type FSWatcher } from 'chokidar';
+import { databaseService } from '../database';
+import { UsageRepository } from './usageRepository';
+import { UsageAggregator, resolveReportRange } from './usageAggregator';
+import { isFileUnchanged, resolveStartOffset, scanJsonlFile } from './jsonlScanner';
+import { PRICING_AS_OF } from './modelPricing';
+import {
+  DEFAULT_USAGE_RANGE_DAYS,
+  USAGE_PARSER_VERSION,
+  USAGE_RETENTION_DAYS,
+  type UsageIndexStatus,
+  type UsageProvider,
+  type UsageRateLimitSample,
+  type UsageReport,
+  type UsageReportRequest,
+} from '../../../../shared/types/usage';
+
+interface TranscriptRoot {
+  provider: UsageProvider;
+  path: string;
+}
+
+/** Yield to the event loop every N files so a first scan never blocks the UI. */
+const YIELD_EVERY_FILES = 25;
+/** Coalesce watcher events — an active agent appends constantly. */
+const WATCH_DEBOUNCE_MS = 3000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function transcriptRoots(): TranscriptRoot[] {
+  const home = homedir();
+  return [
+    { provider: 'claude', path: join(home, '.claude', 'projects') },
+    { provider: 'codex', path: join(home, '.codex', 'sessions') },
+  ];
+}
+
+/**
+ * Indexes agent CLI transcripts so the usage page can report tokens, cost and
+ * rolling-window utilisation.
+ *
+ * Read-only by construction: it never writes to, creates or deletes anything
+ * under `~/.claude` or `~/.codex`.
+ *
+ * Known limitation: only the Electron host's home directory is scanned. On
+ * Windows with WSL-based projects the agents write inside the distro's home,
+ * which this does not reach.
+ */
+export class UsageManager {
+  // Resolved on first use, not in the constructor: this module is imported at
+  // load time and the database handle is only guaranteed after initialisation.
+  private repositoryRef: UsageRepository | null = null;
+  private aggregatorRef: UsageAggregator | null = null;
+  private watchers: FSWatcher[] = [];
+  private pendingFiles = new Map<string, UsageProvider>();
+  private debounceTimer: NodeJS.Timeout | undefined;
+  private scanning = false;
+  private started = false;
+
+  private status: UsageIndexStatus = {
+    lastScanStartedMs: null,
+    lastScanFinishedMs: null,
+    filesTracked: 0,
+    eventsIndexed: 0,
+    missingRoots: [],
+    scanning: false,
+    filesScanned: 0,
+    filesTotal: 0,
+    lastError: null,
+  };
+
+  private get repository(): UsageRepository {
+    if (!this.repositoryRef) this.repositoryRef = new UsageRepository(databaseService.getDb());
+    return this.repositoryRef;
+  }
+
+  private get aggregator(): UsageAggregator {
+    if (!this.aggregatorRef) this.aggregatorRef = new UsageAggregator(databaseService.getDb());
+    return this.aggregatorRef;
+  }
+
+  /** Call after `app.whenReady()` — never at module load. */
+  async start(): Promise<void> {
+    if (this.started) return;
+    this.started = true;
+
+    try {
+      this.repository.pruneOlderThan(Date.now() - USAGE_RETENTION_DAYS * DAY_MS);
+    } catch (error) {
+      console.error('[Usage] Retention sweep failed:', error);
+    }
+
+    void this.runFullScan();
+    this.startWatching();
+  }
+
+  stop(): void {
+    this.started = false;
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    for (const watcher of this.watchers) void watcher.close();
+    this.watchers = [];
+  }
+
+  getStatus(): UsageIndexStatus {
+    return {
+      ...this.status,
+      filesTracked: this.safeCount(() => this.repository.countFiles()),
+      eventsIndexed: this.safeCount(() => this.repository.countEvents()),
+    };
+  }
+
+  /** Force a full re-scan; used by the page's refresh action. */
+  async rescan(): Promise<UsageIndexStatus> {
+    await this.runFullScan();
+    return this.getStatus();
+  }
+
+  getReport(request?: UsageReportRequest): UsageReport {
+    const nowMs = Date.now();
+    const { fromMs, toMs, bucket } = resolveReportRange(request, nowMs, DEFAULT_USAGE_RANGE_DAYS);
+    const providers = request?.providers;
+
+    return {
+      totals: this.aggregator.getTotals(fromMs, toMs, providers),
+      series: this.aggregator.getSeries(fromMs, toMs, bucket, providers),
+      byModel: this.aggregator.getByModel(fromMs, toMs, providers),
+      byProject: this.aggregator.getByProject(fromMs, toMs, providers),
+      window: this.aggregator.getWindow(nowMs, request?.limitTokens ?? null),
+      rateLimits: this.safeRateLimits(nowMs, providers),
+      index: this.getStatus(),
+      pricingAsOf: PRICING_AS_OF,
+    };
+  }
+
+  /** Quota state, narrowed to the providers the page is showing. */
+  private safeRateLimits(nowMs: number, providers?: UsageProvider[]): UsageRateLimitSample[] {
+    try {
+      const samples = this.repository.getRateLimits(nowMs);
+      if (!providers || providers.length === 0) return samples;
+      return samples.filter(sample => providers.includes(sample.provider));
+    } catch {
+      return [];
+    }
+  }
+
+  private safeCount(read: () => number): number {
+    try {
+      return read();
+    } catch {
+      return 0;
+    }
+  }
+
+  private async runFullScan(): Promise<void> {
+    if (this.scanning) return;
+    this.scanning = true;
+    this.status = { ...this.status, scanning: true, lastScanStartedMs: Date.now(), lastError: null, filesScanned: 0 };
+
+    try {
+      const roots = transcriptRoots();
+      this.status.missingRoots = roots.filter(root => !existsSync(root.path)).map(root => root.path);
+
+      const files: Array<{ path: string; provider: UsageProvider }> = [];
+      for (const root of roots) {
+        if (!existsSync(root.path)) continue;
+        const matches = await glob('**/*.jsonl', { cwd: root.path, absolute: true, nodir: true });
+        for (const path of matches) files.push({ path, provider: root.provider });
+      }
+
+      this.status.filesTotal = files.length;
+
+      let processed = 0;
+      for (const file of files) {
+        await this.scanOne(file.path, file.provider);
+        processed += 1;
+        this.status.filesScanned = processed;
+        if (processed % YIELD_EVERY_FILES === 0) {
+          await new Promise<void>(resolve => setImmediate(resolve));
+        }
+      }
+    } catch (error) {
+      this.status.lastError = error instanceof Error ? error.message : String(error);
+      console.error('[Usage] Scan failed:', error);
+    } finally {
+      this.scanning = false;
+      this.status = { ...this.status, scanning: false, lastScanFinishedMs: Date.now() };
+    }
+  }
+
+  /**
+   * Index one transcript, resuming from its stored cursor. Files whose size
+   * and mtime are unchanged are skipped without being opened, which is what
+   * makes subsequent launches fast.
+   */
+  private async scanOne(path: string, provider: UsageProvider): Promise<void> {
+    try {
+      const stats = await stat(path);
+      let recorded = this.repository.getFileCursor(path);
+
+      // A parser fix must reach transcripts that were already indexed, so a
+      // version mismatch discards this file's rows and re-reads it in full.
+      if (recorded && recorded.parserVersion !== USAGE_PARSER_VERSION) {
+        this.repository.forgetFile(path);
+        recorded = null;
+      }
+
+      if (isFileUnchanged(recorded, stats)) return;
+
+      const startOffset = resolveStartOffset(recorded, stats.size);
+      // A file being re-read from the top states its own attribution again, and
+      // a stored context would describe bytes that are no longer there — this is
+      // the rotation and truncation case.
+      const seedContext = startOffset > 0 ? recorded?.parseContext ?? null : null;
+      const scanned = await scanJsonlFile(path, provider, startOffset, stats.mtimeMs, seedContext);
+
+      this.repository.commitFile(
+        {
+          path,
+          provider,
+          sizeBytes: stats.size,
+          mtimeMs: stats.mtimeMs,
+          offsetBytes: scanned.nextOffsetBytes,
+          lastScannedMs: Date.now(),
+          parserVersion: USAGE_PARSER_VERSION,
+          parseContext: scanned.context,
+        },
+        scanned.events,
+        Date.now()
+      );
+
+      this.repository.recordRateLimits(scanned.rateLimits);
+    } catch (error) {
+      // A single unreadable transcript must not abort the pass.
+      const code = (error as NodeJS.ErrnoException)?.code;
+      if (code === 'ENOENT') {
+        this.repository.forgetFile(path);
+        return;
+      }
+      console.warn(`[Usage] Skipped ${path}:`, error instanceof Error ? error.message : error);
+    }
+  }
+
+  private startWatching(): void {
+    for (const root of transcriptRoots()) {
+      if (!existsSync(root.path)) continue;
+
+      const watcher = chokidar.watch(root.path, {
+        ignoreInitial: true,
+        depth: 6,
+        // Transcripts are appended continuously; wait for a lull before reading.
+        awaitWriteFinish: { stabilityThreshold: 1500, pollInterval: 300 },
+      });
+
+      const queue = (path: string) => {
+        if (!path.endsWith('.jsonl')) return;
+        this.pendingFiles.set(path, root.provider);
+        this.scheduleFlush();
+      };
+
+      watcher.on('add', queue);
+      watcher.on('change', queue);
+      watcher.on('error', error => {
+        console.warn('[Usage] Watcher error:', error);
+      });
+
+      this.watchers.push(watcher);
+    }
+  }
+
+  private scheduleFlush(): void {
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    this.debounceTimer = setTimeout(() => {
+      const batch = [...this.pendingFiles.entries()];
+      this.pendingFiles.clear();
+      void (async () => {
+        for (const [path, provider] of batch) {
+          await this.scanOne(path, provider);
+        }
+      })();
+    }, WATCH_DEBOUNCE_MS);
+    this.debounceTimer.unref?.();
+  }
+}
+
+export const usageManager = new UsageManager();
diff --git a/main/src/services/usage/usageParser.test.ts b/main/src/services/usage/usageParser.test.ts
new file mode 100644
index 00000000..0b1d06f8
--- /dev/null
+++ b/main/src/services/usage/usageParser.test.ts
@@ -0,0 +1,285 @@
+import { describe, it, expect } from 'vitest';
+import { parseUsageLine, parseClaudeLine, parseCodexLine, usageEventId, createCodexContext } from './usageParser';
+
+const FALLBACK_MS = 1_700_000_000_000;
+
+function claudeLine(overrides: Record<string, unknown> = {}, usage: Record<string, unknown> = {}) {
+  return JSON.stringify({
+    type: 'assistant',
+    timestamp: '2026-05-01T10:00:00.000Z',
+    sessionId: 'sess-1',
+    cwd: '/repo',
+    message: {
+      id: 'msg_123',
+      model: 'claude-sonnet-5-20260101',
+      usage: {
+        input_tokens: 100,
+        output_tokens: 50,
+        cache_read_input_tokens: 20,
+        cache_creation_input_tokens: 10,
+        ...usage,
+      },
+      ...overrides,
+    },
+  });
+}
+
+describe('parseClaudeLine', () => {
+  it('extracts tokens, model, timestamp and identity', () => {
+    const event = parseUsageLine('claude', claudeLine(), FALLBACK_MS);
+
+    expect(event).toMatchObject({
+      provider: 'claude',
+      model: 'claude-sonnet-5-20260101',
+      inputTokens: 100,
+      outputTokens: 50,
+      cacheReadTokens: 20,
+      cacheCreationTokens: 10,
+      messageId: 'msg_123',
+      agentSessionId: 'sess-1',
+      cwd: '/repo',
+    });
+    expect(event?.timestampMs).toBe(Date.parse('2026-05-01T10:00:00.000Z'));
+  });
+
+  it('sums the nested cache_creation breakdown used by newer builds', () => {
+    const line = claudeLine({}, {
+      cache_creation_input_tokens: 0,
+      cache_creation: { ephemeral_5m_input_tokens: 300, ephemeral_1h_input_tokens: 200 },
+    });
+
+    expect(parseUsageLine('claude', line, FALLBACK_MS)?.cacheCreationTokens).toBe(500);
+  });
+
+  it('prefers the flat cache_creation_input_tokens when it is non-zero', () => {
+    const line = claudeLine({}, {
+      cache_creation_input_tokens: 42,
+      cache_creation: { ephemeral_5m_input_tokens: 999 },
+    });
+
+    expect(parseUsageLine('claude', line, FALLBACK_MS)?.cacheCreationTokens).toBe(42);
+  });
+
+  it('falls back to the file mtime when the line has no timestamp', () => {
+    const line = JSON.stringify({
+      type: 'assistant',
+      message: { model: 'claude-opus-5', usage: { input_tokens: 5, output_tokens: 1 } },
+    });
+
+    expect(parseUsageLine('claude', line, FALLBACK_MS)?.timestampMs).toBe(FALLBACK_MS);
+  });
+
+  it('ignores non-assistant lines', () => {
+    const line = JSON.stringify({ type: 'user', message: { content: 'hi' } });
+    expect(parseUsageLine('claude', line, FALLBACK_MS)).toBeNull();
+  });
+
+  it('ignores assistant lines without usage', () => {
+    const line = JSON.stringify({ type: 'assistant', message: { model: 'claude-opus-5' } });
+    expect(parseUsageLine('claude', line, FALLBACK_MS)).toBeNull();
+  });
+
+  it('ignores a usage object with all-zero counts', () => {
+    const line = claudeLine({}, {
+      input_tokens: 0,
+      output_tokens: 0,
+      cache_read_input_tokens: 0,
+      cache_creation_input_tokens: 0,
+    });
+    expect(parseUsageLine('claude', line, FALLBACK_MS)).toBeNull();
+  });
+
+  it('labels a missing model as unknown rather than dropping the event', () => {
+    const line = JSON.stringify({
+      type: 'assistant',
+      message: { usage: { input_tokens: 10, output_tokens: 2 } },
+    });
+    expect(parseClaudeLine(JSON.parse(line), FALLBACK_MS)?.model).toBe('unknown');
+  });
+});
+
+/**
+ * Fixtures below mirror what the Codex CLI actually writes, taken from real
+ * rollout transcripts rather than assumed.
+ */
+function tokenCountLine(usage: Record<string, number>, cumulative?: Record<string, number>) {
+  return JSON.stringify({
+    timestamp: '2026-05-01T11:00:00.000Z',
+    type: 'event_msg',
+    payload: {
+      type: 'token_count',
+      info: {
+        last_token_usage: usage,
+        total_token_usage: cumulative ?? usage,
+        model_context_window: 258400,
+      },
+    },
+  });
+}
+
+const TURN_CONTEXT = JSON.stringify({
+  timestamp: '2026-05-01T10:59:00.000Z',
+  type: 'turn_context',
+  payload: { model: 'gpt-5.6-sol', cwd: 'D:\\repo' },
+});
+
+const SESSION_META = JSON.stringify({
+  timestamp: '2026-05-01T10:58:00.000Z',
+  type: 'session_meta',
+  payload: { id: 'codex-session-1', cwd: 'D:\\repo', model_provider: 'openai' },
+});
+
+describe('parseCodexLine', () => {
+  it('reads last_token_usage from a token_count event', () => {
+    const line = tokenCountLine({
+      input_tokens: 18179,
+      cached_input_tokens: 4096,
+      cache_write_input_tokens: 100,
+      output_tokens: 52,
+      reasoning_output_tokens: 34,
+      total_tokens: 18231,
+    });
+
+    expect(parseUsageLine('codex', line, FALLBACK_MS)).toMatchObject({
+      provider: 'codex',
+      // input_tokens includes the cached part; they are priced separately.
+      inputTokens: 18179 - 4096,
+      cacheReadTokens: 4096,
+      cacheCreationTokens: 100,
+      outputTokens: 52,
+    });
+  });
+
+  it('attributes model, session and cwd from earlier context lines', () => {
+    const context = createCodexContext();
+    parseUsageLine('codex', SESSION_META, FALLBACK_MS, context);
+    parseUsageLine('codex', TURN_CONTEXT, FALLBACK_MS, context);
+
+    const event = parseUsageLine(
+      'codex',
+      tokenCountLine({ input_tokens: 10, cached_input_tokens: 0, output_tokens: 5 }),
+      FALLBACK_MS,
+      context
+    );
+
+    expect(event).toMatchObject({
+      model: 'gpt-5.6-sol',
+      agentSessionId: 'codex-session-1',
+      cwd: 'D:\\repo',
+    });
+  });
+
+  it('never accumulates the cumulative total_token_usage', () => {
+    // Three turns of a session: totals grow, deltas do not.
+    const context = createCodexContext();
+    const lines = [
+      tokenCountLine({ input_tokens: 100, output_tokens: 10 }, { input_tokens: 100, output_tokens: 10 }),
+      tokenCountLine({ input_tokens: 120, output_tokens: 12 }, { input_tokens: 220, output_tokens: 22 }),
+      tokenCountLine({ input_tokens: 130, output_tokens: 13 }, { input_tokens: 350, output_tokens: 35 }),
+    ];
+
+    const total = lines
+      .map(line => parseUsageLine('codex', line, FALLBACK_MS, context))
+      .reduce((sum, event) => sum + (event?.inputTokens ?? 0), 0);
+
+    // Sum of the deltas, not of the running totals (which would be 670).
+    expect(total).toBe(350);
+  });
+
+  it('captures the provider-reported quota state', () => {
+    const context = createCodexContext();
+    const line = JSON.stringify({
+      timestamp: '2026-05-01T11:00:00.000Z',
+      type: 'event_msg',
+      payload: {
+        type: 'token_count',
+        info: { last_token_usage: { input_tokens: 10, output_tokens: 5 } },
+        rate_limits: {
+          limit_id: 'codex',
+          primary: { used_percent: 59, window_minutes: 10080, resets_at: 1785497199 },
+          secondary: null,
+          plan_type: 'plus',
+        },
+      },
+    });
+
+    parseUsageLine('codex', line, FALLBACK_MS, context);
+    const limits = [...context.rateLimits.values()];
+
+    expect(limits).toHaveLength(1);
+    expect(limits[0]).toMatchObject({
+      provider: 'codex',
+      limitId: 'codex',
+      scope: 'primary',
+      usedPercent: 59,
+      windowMinutes: 10080,
+      planType: 'plus',
+      // resets_at is epoch seconds and must be promoted to milliseconds.
+      resetsAtMs: 1785497199 * 1000,
+    });
+  });
+
+  it('keeps the newest quota sample when several appear', () => {
+    const context = createCodexContext();
+    const sample = (ts: string, used: number) => JSON.stringify({
+      timestamp: ts,
+      type: 'event_msg',
+      payload: {
+        type: 'token_count',
+        info: { last_token_usage: { input_tokens: 1, output_tokens: 1 } },
+        rate_limits: { limit_id: 'codex', primary: { used_percent: used, window_minutes: 300 } },
+      },
+    });
+
+    parseUsageLine('codex', sample('2026-05-01T10:00:00.000Z', 20), FALLBACK_MS, context);
+    parseUsageLine('codex', sample('2026-05-01T12:00:00.000Z', 65), FALLBACK_MS, context);
+    parseUsageLine('codex', sample('2026-05-01T11:00:00.000Z', 40), FALLBACK_MS, context);
+
+    expect([...context.rateLimits.values()][0].usedPercent).toBe(65);
+  });
+
+  it('context lines themselves produce no usage event', () => {
+    const context = createCodexContext();
+    expect(parseUsageLine('codex', SESSION_META, FALLBACK_MS, context)).toBeNull();
+    expect(parseUsageLine('codex', TURN_CONTEXT, FALLBACK_MS, context)).toBeNull();
+  });
+
+  it('falls back to a generic model label with no context', () => {
+    const line = tokenCountLine({ input_tokens: 1, output_tokens: 1 });
+    expect(parseCodexLine(JSON.parse(line), FALLBACK_MS)?.model).toBe('codex');
+  });
+
+  it('ignores other event types and zero-token turns', () => {
+    expect(parseUsageLine('codex', JSON.stringify({ type: 'response_item', payload: {} }), FALLBACK_MS)).toBeNull();
+    expect(parseUsageLine('codex', tokenCountLine({ input_tokens: 0, output_tokens: 0 }), FALLBACK_MS)).toBeNull();
+  });
+});
+
+describe('parseUsageLine robustness', () => {
+  it('returns null for blank lines, prose and malformed JSON', () => {
+    expect(parseUsageLine('claude', '', FALLBACK_MS)).toBeNull();
+    expect(parseUsageLine('claude', '   ', FALLBACK_MS)).toBeNull();
+    expect(parseUsageLine('claude', 'not json at all', FALLBACK_MS)).toBeNull();
+    expect(parseUsageLine('claude', '{"type":"assistant"', FALLBACK_MS)).toBeNull();
+  });
+
+  it('returns null for a JSON array rather than throwing', () => {
+    expect(parseUsageLine('claude', '[1,2,3]', FALLBACK_MS)).toBeNull();
+  });
+});
+
+describe('usageEventId', () => {
+  it('prefers the provider message id so re-scans dedupe', () => {
+    const event = parseUsageLine('claude', claudeLine(), FALLBACK_MS)!;
+    expect(usageEventId(event, '/t.jsonl', 512)).toBe('claude:msg_123');
+  });
+
+  it('falls back to path and offset when there is no message id', () => {
+    const line = JSON.stringify({
+      type: 'assistant',
+      message: { model: 'claude-opus-5', usage: { input_tokens: 1, output_tokens: 1 } },
+    });
+    const event = parseUsageLine('claude', line, FALLBACK_MS)!;
+    expect(usageEventId(event, '/t.jsonl', 512)).toBe('/t.jsonl:512');
+  });
+});
diff --git a/main/src/services/usage/usageParser.ts b/main/src/services/usage/usageParser.ts
new file mode 100644
index 00000000..e088f972
--- /dev/null
+++ b/main/src/services/usage/usageParser.ts
@@ -0,0 +1,293 @@
+import type { UsageEvent, UsageProvider, UsageRateLimitSample } from '../../../../shared/types/usage';
+
+/**
+ * Transcript line -> {@link UsageEvent}. Pure: no filesystem, no clock.
+ *
+ * Transcript shapes drift between CLI releases, so every field is narrowed
+ * from `unknown` and any unrecognised line yields `null` rather than throwing.
+ * A malformed line must never abort a scan.
+ */
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function asNumber(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function toEpochMs(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    // Codex has used both seconds and milliseconds over time.
+    return value > 1e12 ? value : value * 1000;
+  }
+  const raw = asString(value);
+  if (!raw) return null;
+  const parsed = Date.parse(raw);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+
+/**
+ * Cache-creation tokens are reported either as a flat count or, in newer
+ * Claude builds, as a breakdown object keyed by TTL. Sum whatever is there.
+ */
+function readCacheCreation(usage: Record<string, unknown>): number {
+  const flat = asNumber(usage.cache_creation_input_tokens);
+  if (flat > 0) return flat;
+
+  const breakdown = usage.cache_creation;
+  if (isRecord(breakdown)) {
+    return Object.values(breakdown).reduce<number>((sum, entry) => sum + asNumber(entry), 0);
+  }
+  return 0;
+}
+
+function buildEvent(
+  provider: UsageProvider,
+  usage: Record<string, unknown>,
+  meta: { model: string; timestampMs: number; messageId: string | null; agentSessionId: string | null; cwd: string | null }
+): UsageEvent | null {
+  const inputTokens = asNumber(usage.input_tokens);
+  const outputTokens = asNumber(usage.output_tokens);
+  const cacheReadTokens = asNumber(usage.cache_read_input_tokens);
+  const cacheCreationTokens = readCacheCreation(usage);
+
+  // A usage object with no tokens at all carries no information.
+  if (inputTokens + outputTokens + cacheReadTokens + cacheCreationTokens === 0) return null;
+
+  return {
+    provider,
+    timestampMs: meta.timestampMs,
+    model: meta.model,
+    inputTokens,
+    outputTokens,
+    cacheReadTokens,
+    cacheCreationTokens,
+    agentSessionId: meta.agentSessionId,
+    messageId: meta.messageId,
+    cwd: meta.cwd,
+  };
+}
+
+/**
+ * Claude Code transcript line.
+ *
+ * Assistant entries carry `message.usage`; the timestamp, `sessionId` and
+ * `cwd` live at the top level.
+ */
+export function parseClaudeLine(value: unknown, fallbackTimestampMs: number): UsageEvent | null {
+  if (!isRecord(value)) return null;
+  if (value.type !== 'assistant') return null;
+
+  const message = value.message;
+  if (!isRecord(message)) return null;
+
+  const usage = message.usage;
+  if (!isRecord(usage)) return null;
+
+  return buildEvent('claude', usage, {
+    model: asString(message.model) ?? 'unknown',
+    timestampMs: toEpochMs(value.timestamp) ?? fallbackTimestampMs,
+    messageId: asString(message.id),
+    agentSessionId: asString(value.sessionId),
+    cwd: asString(value.cwd),
+  });
+}
+
+/**
+ * Rolling per-file state for the Codex parser.
+ *
+ * Codex's `token_count` events carry no model, session id or cwd — those
+ * arrive earlier in the file on `session_meta` / `turn_context` lines. The
+ * scanner threads one context per transcript so each usage event can be
+ * attributed correctly.
+ */
+export interface CodexParseContext {
+  model: string | null;
+  sessionId: string | null;
+  cwd: string | null;
+  /** Newest quota state seen in this file, keyed by `${limitId}:${scope}`. */
+  rateLimits: Map<string, UsageRateLimitSample>;
+}
+
+/**
+ * The part of a Codex context that has to outlive a single scan.
+ *
+ * A transcript is read in pieces as the agent appends to it, and the lines that
+ * carry the attribution are at the top — `session_meta` is the file's first
+ * line. A pass that resumes at a byte offset never sees them again, so what
+ * they said is stored with the file's cursor and handed back in.
+ *
+ * Quota samples are deliberately not part of this: they live in their own
+ * table, and replaying an old sample would move a rolling window backwards.
+ */
+export interface CodexContextSnapshot {
+  model: string | null;
+  sessionId: string | null;
+  cwd: string | null;
+}
+
+export function createCodexContext(seed?: CodexContextSnapshot | null): CodexParseContext {
+  return {
+    model: seed?.model ?? null,
+    sessionId: seed?.sessionId ?? null,
+    cwd: seed?.cwd ?? null,
+    rateLimits: new Map(),
+  };
+}
+
+/** What a later pass needs to attribute usage the same way this one did. */
+export function snapshotCodexContext(context: CodexParseContext): CodexContextSnapshot {
+  return { model: context.model, sessionId: context.sessionId, cwd: context.cwd };
+}
+
+/**
+ * Pull Codex's self-reported quota state out of a `token_count` event.
+ *
+ * This is the accurate answer to "how much have I used": the provider states
+ * it directly, rather than us inferring it from token sums.
+ */
+function collectCodexRateLimits(
+  payload: Record<string, unknown>,
+  capturedAtMs: number,
+  context: CodexParseContext
+): void {
+  const rateLimits = payload.rate_limits;
+  if (!isRecord(rateLimits)) return;
+
+  const limitId = asString(rateLimits.limit_id) ?? 'codex';
+  const planType = asString(rateLimits.plan_type);
+
+  for (const scope of ['primary', 'secondary'] as const) {
+    const entry = rateLimits[scope];
+    if (!isRecord(entry)) continue;
+
+    const usedPercent = asNumber(entry.used_percent);
+    const windowMinutes = asNumber(entry.window_minutes);
+    // `resets_at` is epoch seconds.
+    const resetsAt = asNumber(entry.resets_at);
+
+    const sample: UsageRateLimitSample = {
+      provider: 'codex',
+      limitId,
+      scope,
+      usedPercent,
+      windowMinutes: windowMinutes > 0 ? windowMinutes : null,
+      resetsAtMs: resetsAt > 0 ? resetsAt * 1000 : null,
+      planType,
+      capturedAtMs,
+    };
+
+    const key = `${limitId}:${scope}`;
+    const existing = context.rateLimits.get(key);
+    if (!existing || existing.capturedAtMs <= capturedAtMs) {
+      context.rateLimits.set(key, sample);
+    }
+  }
+}
+
+/**
+ * Codex transcript line.
+ *
+ * Real shape, as written by the Codex CLI:
+ *
+ *   {"type":"event_msg","timestamp":"…","payload":{"type":"token_count",
+ *     "info":{"last_token_usage":{input_tokens,cached_input_tokens,
+ *       cache_write_input_tokens,output_tokens,reasoning_output_tokens,
+ *       total_tokens}, "total_token_usage":{…}}}}
+ *
+ * **`total_token_usage` is cumulative for the session** — summing it would
+ * multiply the real figure many times over. Only `last_token_usage`, the delta
+ * for the turn that just finished, may be accumulated.
+ *
+ * OpenAI reports `input_tokens` inclusive of `cached_input_tokens`, so the
+ * cached part is subtracted out to keep the two priced separately.
+ */
+export function parseCodexLine(
+  value: unknown,
+  fallbackTimestampMs: number,
+  context?: CodexParseContext
+): UsageEvent | null {
+  if (!isRecord(value)) return null;
+  const payload = isRecord(value.payload) ? value.payload : null;
+
+  // Context-carrying lines: remember what later usage events will need.
+  if (context) {
+    if (value.type === 'session_meta' && payload) {
+      context.sessionId = asString(payload.id) ?? context.sessionId;
+      context.cwd = asString(payload.cwd) ?? context.cwd;
+      context.model = asString(payload.model) ?? context.model;
+    } else if ((value.type === 'turn_context' || value.type === 'world_state') && payload) {
+      context.model = asString(payload.model) ?? context.model;
+      context.cwd = asString(payload.cwd) ?? context.cwd;
+    }
+  }
+
+  if (value.type !== 'event_msg' || !payload || payload.type !== 'token_count') return null;
+
+  const timestampMs = toEpochMs(value.timestamp) ?? fallbackTimestampMs;
+  if (context) collectCodexRateLimits(payload, timestampMs, context);
+
+  const info = isRecord(payload.info) ? payload.info : null;
+  const last = info && isRecord(info.last_token_usage) ? info.last_token_usage : null;
+  if (!last) return null;
+
+  const cachedInput = asNumber(last.cached_input_tokens);
+  const totalInput = asNumber(last.input_tokens);
+
+  const normalized: Record<string, unknown> = {
+    // Fresh (uncached) input, so cache reads are not billed twice.
+    input_tokens: Math.max(totalInput - cachedInput, 0),
+    output_tokens: asNumber(last.output_tokens),
+    cache_read_input_tokens: cachedInput,
+    cache_creation_input_tokens: asNumber(last.cache_write_input_tokens),
+  };
+
+  return buildEvent('codex', normalized, {
+    model: context?.model ?? asString(payload.model) ?? 'codex',
+    timestampMs,
+    // token_count events have no id; the scanner falls back to path:offset.
+    messageId: null,
+    agentSessionId: context?.sessionId ?? null,
+    cwd: context?.cwd ?? null,
+  });
+}
+
+/**
+ * Parse one raw JSONL line for a provider. Returns `null` for blank lines,
+ * malformed JSON, and lines that carry no token accounting.
+ */
+export function parseUsageLine(
+  provider: UsageProvider,
+  line: string,
+  fallbackTimestampMs: number,
+  context?: CodexParseContext
+): UsageEvent | null {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed[0] !== '{') return null;
+
+  let value: unknown;
+  try {
+    value = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+
+  return provider === 'claude'
+    ? parseClaudeLine(value, fallbackTimestampMs)
+    : parseCodexLine(value, fallbackTimestampMs, context);
+}
+
+/**
+ * Stable row id. Prefers the provider's message id; falls back to the file
+ * offset so re-scanning the same bytes cannot double-count.
+ */
+export function usageEventId(event: UsageEvent, sourcePath: string, byteOffset: number): string {
+  return event.messageId
+    ? `${event.provider}:${event.messageId}`
+    : `${sourcePath}:${byteOffset}`;
+}
diff --git a/main/src/services/usage/usageRepository.ts b/main/src/services/usage/usageRepository.ts
new file mode 100644
index 00000000..87b79647
--- /dev/null
+++ b/main/src/services/usage/usageRepository.ts
@@ -0,0 +1,262 @@
+import type { Database } from 'better-sqlite3-multiple-ciphers';
+import type { UsageEvent, UsageProvider, UsageRateLimitSample } from '../../../../shared/types/usage';
+import { usageEventId, type CodexContextSnapshot } from './usageParser';
+
+export interface UsageFileCursor {
+  path: string;
+  provider: UsageProvider;
+  sizeBytes: number;
+  mtimeMs: number;
+  offsetBytes: number;
+  lastScannedMs: number;
+  /** Parser that produced this file's events; see USAGE_PARSER_VERSION. */
+  parserVersion: number;
+  /**
+   * Codex attribution as of `offsetBytes`. Stored with the cursor because it
+   * describes the same point in the file, and a resumed scan is past the lines
+   * that state it. Null for Claude and for files never scanned as Codex.
+   */
+  parseContext: CodexContextSnapshot | null;
+}
+
+interface UsageFileRow {
+  path: string;
+  provider: string;
+  size_bytes: number;
+  mtime_ms: number;
+  offset_bytes: number;
+  last_scanned_ms: number;
+  parser_version: number | null;
+  parse_context: string | null;
+}
+
+/** A stored context, or null if the column is empty or no longer parses. */
+function readParseContext(raw: string | null | undefined): CodexContextSnapshot | null {
+  if (!raw) return null;
+  try {
+    const value = JSON.parse(raw) as Partial<CodexContextSnapshot>;
+    return {
+      model: typeof value.model === 'string' ? value.model : null,
+      sessionId: typeof value.sessionId === 'string' ? value.sessionId : null,
+      cwd: typeof value.cwd === 'string' ? value.cwd : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persistence for the transcript index.
+ *
+ * Uses the raw better-sqlite3 handle rather than growing the ~5,000-line
+ * `DatabaseService` facade — the same escape hatch `ScrollbackRetentionService`
+ * uses for its sweeps.
+ */
+export class UsageRepository {
+  constructor(private db: Database) {}
+
+  getFileCursor(path: string): UsageFileCursor | null {
+    const row = this.db
+      .prepare('SELECT * FROM usage_files WHERE path = ?')
+      .get(path) as UsageFileRow | undefined;
+    if (!row) return null;
+
+    return {
+      path: row.path,
+      provider: row.provider === 'codex' ? 'codex' : 'claude',
+      sizeBytes: row.size_bytes,
+      mtimeMs: row.mtime_ms,
+      offsetBytes: row.offset_bytes,
+      lastScannedMs: row.last_scanned_ms,
+      parserVersion: row.parser_version ?? 0,
+      parseContext: readParseContext(row.parse_context),
+    };
+  }
+
+  /**
+   * Persist a file's parsed events and advance its cursor in one transaction,
+   * so a crash mid-file cannot leave the cursor ahead of the stored rows.
+   */
+  commitFile(
+    cursor: UsageFileCursor,
+    events: Array<{ event: UsageEvent; byteOffset: number }>,
+    nowMs: number
+  ): number {
+    const insert = this.db.prepare(`
+      INSERT OR IGNORE INTO usage_events (
+        id, provider, timestamp_ms, model,
+        input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens,
+        agent_session_id, cwd, source_path
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    const upsertFile = this.db.prepare(`
+      INSERT INTO usage_files (
+        path, provider, size_bytes, mtime_ms, offset_bytes, last_scanned_ms,
+        parser_version, parse_context
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(path) DO UPDATE SET
+        provider = excluded.provider,
+        size_bytes = excluded.size_bytes,
+        mtime_ms = excluded.mtime_ms,
+        offset_bytes = excluded.offset_bytes,
+        last_scanned_ms = excluded.last_scanned_ms,
+        parser_version = excluded.parser_version,
+        parse_context = excluded.parse_context
+    `);
+
+    const run = this.db.transaction(() => {
+      let inserted = 0;
+      for (const { event, byteOffset } of events) {
+        const result = insert.run(
+          usageEventId(event, cursor.path, byteOffset),
+          event.provider,
+          event.timestampMs,
+          event.model,
+          event.inputTokens,
+          event.outputTokens,
+          event.cacheReadTokens,
+          event.cacheCreationTokens,
+          event.agentSessionId,
+          event.cwd,
+          cursor.path
+        );
+        inserted += result.changes;
+      }
+
+      upsertFile.run(
+        cursor.path,
+        cursor.provider,
+        cursor.sizeBytes,
+        cursor.mtimeMs,
+        cursor.offsetBytes,
+        nowMs,
+        cursor.parserVersion,
+        cursor.parseContext ? JSON.stringify(cursor.parseContext) : null
+      );
+
+      return inserted;
+    });
+
+    return run();
+  }
+
+  /** Keep only the newest sample per limit; older re-scans must not regress it. */
+  recordRateLimits(samples: UsageRateLimitSample[]): void {
+    if (samples.length === 0) return;
+
+    const upsert = this.db.prepare(`
+      INSERT INTO usage_rate_limits (
+        provider, limit_id, scope, used_percent, window_minutes,
+        resets_at_ms, plan_type, captured_at_ms
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(provider, limit_id, scope) DO UPDATE SET
+        used_percent = excluded.used_percent,
+        window_minutes = excluded.window_minutes,
+        resets_at_ms = excluded.resets_at_ms,
+        plan_type = excluded.plan_type,
+        captured_at_ms = excluded.captured_at_ms
+      WHERE excluded.captured_at_ms > usage_rate_limits.captured_at_ms
+    `);
+
+    this.db.transaction(() => {
+      for (const sample of samples) {
+        upsert.run(
+          sample.provider,
+          sample.limitId,
+          sample.scope,
+          sample.usedPercent,
+          sample.windowMinutes,
+          sample.resetsAtMs,
+          sample.planType,
+          sample.capturedAtMs
+        );
+      }
+    })();
+  }
+
+  /**
+   * The current quota state, one row per provider and window.
+   *
+   * Rows are stored per `limit_id`, which the provider changes when the plan or
+   * account behind a session changes — so the table accumulates several ids over
+   * time and listing it raw showed four near-identical "OpenAI 7d window" bars.
+   * A provider only ever has one primary (rolling) and one secondary (weekly)
+   * window in force, so the newest capture of each is the answer; the older
+   * ids are history, not additional limits.
+   *
+   * Readings whose window has already elapsed are dropped rather than shown at
+   * their last value: "0% of a window that ended 54 days ago" is not a fact
+   * about the present, and a progress bar makes it look like one.
+   */
+  getRateLimits(nowMs: number): UsageRateLimitSample[] {
+    const rows = this.db.prepare(`
+      SELECT * FROM usage_rate_limits ORDER BY provider, scope, captured_at_ms DESC
+    `).all() as Array<{
+      provider: string;
+      limit_id: string;
+      scope: string;
+      used_percent: number;
+      window_minutes: number | null;
+      resets_at_ms: number | null;
+      plan_type: string | null;
+      captured_at_ms: number;
+    }>;
+
+    const newestPerWindow = new Map<string, UsageRateLimitSample>();
+
+    for (const row of rows) {
+      // Expired by its own reset time, or — when the provider named no reset —
+      // older than the window it describes.
+      const windowMs = (row.window_minutes ?? 0) * 60_000;
+      const expired = row.resets_at_ms !== null
+        ? row.resets_at_ms <= nowMs
+        : windowMs > 0 && row.captured_at_ms + windowMs <= nowMs;
+      if (expired) continue;
+
+      const sample: UsageRateLimitSample = {
+        provider: row.provider === 'codex' ? 'codex' : 'claude',
+        limitId: row.limit_id,
+        scope: row.scope === 'secondary' ? 'secondary' : 'primary',
+        usedPercent: row.used_percent,
+        windowMinutes: row.window_minutes,
+        resetsAtMs: row.resets_at_ms,
+        planType: row.plan_type,
+        capturedAtMs: row.captured_at_ms,
+      };
+
+      const key = `${sample.provider}:${sample.scope}`;
+      const existing = newestPerWindow.get(key);
+      if (!existing || existing.capturedAtMs < sample.capturedAtMs) {
+        newestPerWindow.set(key, sample);
+      }
+    }
+
+    return [...newestPerWindow.values()]
+      .sort((a, b) => a.provider.localeCompare(b.provider) || a.scope.localeCompare(b.scope));
+  }
+
+  countFiles(): number {
+    const row = this.db.prepare('SELECT COUNT(*) AS n FROM usage_files').get() as { n: number };
+    return row.n;
+  }
+
+  countEvents(): number {
+    const row = this.db.prepare('SELECT COUNT(*) AS n FROM usage_events').get() as { n: number };
+    return row.n;
+  }
+
+  /** Drop events older than the cutoff so the table stays bounded. */
+  pruneOlderThan(cutoffMs: number): number {
+    return this.db.prepare('DELETE FROM usage_events WHERE timestamp_ms < ?').run(cutoffMs).changes;
+  }
+
+  /** Forget a transcript file that no longer exists on disk. */
+  forgetFile(path: string): void {
+    this.db.transaction(() => {
+      this.db.prepare('DELETE FROM usage_events WHERE source_path = ?').run(path);
+      this.db.prepare('DELETE FROM usage_files WHERE path = ?').run(path);
+    })();
+  }
+}
diff --git a/shared/types/daemon.ts b/shared/types/daemon.ts
index c3eac085..4827a09c 100644
--- a/shared/types/daemon.ts
+++ b/shared/types/daemon.ts
@@ -78,6 +78,7 @@ export const DAEMON_OWNED_CHANNEL_PREFIXES = [
   'runpane:',
   'sessions:',
   'terminal:',
+  'usage:',
   'voice:',
 ] as const;
 
diff --git a/shared/types/usage.ts b/shared/types/usage.ts
new file mode 100644
index 00000000..b6727e3d
--- /dev/null
+++ b/shared/types/usage.ts
@@ -0,0 +1,184 @@
+/**
+ * Token usage, cost and rate-limit types.
+ *
+ * Pane runs Claude and Codex as PTY terminals, so no structured usage flows
+ * through the app itself. The authoritative record is each CLI's own transcript
+ * (`~/.claude/projects/**\/*.jsonl`, `~/.codex/sessions/**\/*.jsonl`), which
+ * Pane reads read-only and indexes incrementally.
+ */
+
+export type UsageProvider = 'claude' | 'codex';
+
+/** One assistant message's token accounting, normalised across providers. */
+export interface UsageEvent {
+  provider: UsageProvider;
+  /** Epoch milliseconds — the indexed column. */
+  timestampMs: number;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheCreationTokens: number;
+  /** Provider session id from the transcript, when present. */
+  agentSessionId: string | null;
+  /** Message id — the primary dedupe key across re-scans. */
+  messageId: string | null;
+  /** Working directory recorded in the transcript, for project attribution. */
+  cwd: string | null;
+}
+
+export interface ModelPrice {
+  model: string;
+  /** USD per 1M tokens. */
+  inputPerMTok: number;
+  outputPerMTok: number;
+  cacheReadPerMTok: number;
+  cacheWritePerMTok: number;
+}
+
+export interface UsageTotals {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheCreationTokens: number;
+  totalTokens: number;
+  messageCount: number;
+  estimatedCostUsd: number;
+  /** True when at least one model in the range had no price entry. */
+  costIncomplete: boolean;
+  /**
+   * What the cached input would have cost at the full input rate, minus what
+   * it did cost. With cache reads running two orders of magnitude above fresh
+   * input, this is the single largest lever on the bill.
+   */
+  cacheSavingsUsd: number;
+}
+
+export interface UsageBucket extends UsageTotals {
+  /** Bucket start, epoch milliseconds. */
+  bucketStartMs: number;
+}
+
+export interface UsageByModel extends UsageTotals {
+  model: string;
+  provider: UsageProvider;
+}
+
+/**
+ * Usage attributed to the directory the agent ran in.
+ *
+ * Both CLIs record their working directory per message, which is the only
+ * link back to a Pane project or worktree — the transcripts know nothing about
+ * Pane's own session model.
+ */
+export interface UsageByProject extends UsageTotals {
+  /** Absolute working directory as the transcript recorded it. */
+  path: string;
+  /** Last path segment — the worktree or repo folder name. */
+  label: string;
+}
+
+/** Rolling-window utilisation, the "how much limit is left" figure. */
+export interface UsageWindow {
+  windowHours: number;
+  windowStartMs: number;
+  windowEndMs: number;
+  totals: UsageTotals;
+  /** Configured cap, or the largest window observed historically. */
+  limitTokens: number | null;
+  limitSource: 'configured' | 'observed-max' | 'unknown';
+  /** 0..1, or null when no limit is known. */
+  utilization: number | null;
+  /** When the oldest event in the window ages out, epoch milliseconds. */
+  resetsAtMs: number | null;
+  /**
+   * Tokens in the last hour — the current pace, as opposed to the window's
+   * average. A window that is 10% full but filling fast is a different
+   * situation from one that is 10% full and idle.
+   */
+  recentHourTokens: number;
+}
+
+export interface UsageReportRequest {
+  /** Inclusive epoch-ms range. Defaults to the last 30 days. */
+  fromMs?: number;
+  toMs?: number;
+  bucket?: 'hour' | 'day';
+  providers?: UsageProvider[];
+  /**
+   * The user's own cap for the rolling window, in tokens. Without one the
+   * gauge compares against the largest window ever observed, which flatters
+   * a heavy day and understates a quiet one.
+   */
+  limitTokens?: number | null;
+}
+
+/** Health of the background transcript index, surfaced in the page header. */
+export interface UsageIndexStatus {
+  lastScanStartedMs: number | null;
+  lastScanFinishedMs: number | null;
+  filesTracked: number;
+  eventsIndexed: number;
+  /** Transcript roots that do not exist — drives the empty state. */
+  missingRoots: string[];
+  scanning: boolean;
+  /** Files scanned so far in the current pass, for a progress indicator. */
+  filesScanned: number;
+  filesTotal: number;
+  lastError: string | null;
+}
+
+/**
+ * A rate limit as the provider itself reported it.
+ *
+ * Codex writes its live quota state into every `token_count` event, which
+ * makes this a measured figure rather than an estimate. Claude Code's
+ * transcripts carry no equivalent, so Claude falls back to
+ * {@link UsageWindow}'s computed rolling window.
+ */
+export interface UsageRateLimitSample {
+  provider: UsageProvider;
+  limitId: string;
+  scope: 'primary' | 'secondary';
+  /** 0-100, as reported. */
+  usedPercent: number;
+  windowMinutes: number | null;
+  resetsAtMs: number | null;
+  /** Subscription tier, when the provider names it. */
+  planType: string | null;
+  capturedAtMs: number;
+}
+
+export interface UsageReport {
+  totals: UsageTotals;
+  series: UsageBucket[];
+  byModel: UsageByModel[];
+  /** Busiest working directories in the range, largest first. */
+  byProject: UsageByProject[];
+  window: UsageWindow;
+  /** Provider-reported quota state; empty when nobody reported any. */
+  rateLimits: UsageRateLimitSample[];
+  index: UsageIndexStatus;
+  /** Date the bundled price table was last verified, shown in the footer. */
+  pricingAsOf: string;
+}
+
+/**
+ * Bumped whenever the transcript parsers change in a way that alters the
+ * events they produce. Files indexed by an older parser are re-read from the
+ * start instead of being silently trusted — otherwise a fix would only apply
+ * to transcripts written after it.
+ *
+ * v2: Codex `token_count` events parsed from `last_token_usage` (v1 read the
+ *     wrong shape entirely and recorded nothing).
+ * v3: Codex attribution carried across an incremental scan. Every event a
+ *     resumed pass produced before this was filed under model `codex` with no
+ *     session and no cwd, so those rows have to be read again.
+ */
+export const USAGE_PARSER_VERSION = 3;
+
+/** Claude's published quota window, and the one ccusage-style tools track. */
+export const USAGE_WINDOW_HOURS = 5;
+export const DEFAULT_USAGE_RANGE_DAYS = 30;
+/** Events older than this are swept at startup to bound the table. */
+export const USAGE_RETENTION_DAYS = 180;