claude-usage-dashboard 1.4.2 → 1.5.1

package/README.md

@@ -3,9 +3,9 @@
 [![npm version](https://img.shields.io/npm/v/claude-usage-dashboard)](https://www.npmjs.com/package/claude-usage-dashboard)
 [![npm downloads](https://img.shields.io/npm/dm/claude-usage-dashboard)](https://www.npmjs.com/package/claude-usage-dashboard)
 
-> Find out what your Claude Code subscription is actually worth in API costs — across every machine you own.
+> Find out what your Claude Code subscription is actually worth in API costs — and whether your quota is shrinking — across every machine you own.
 
-Your $200/month Max plan might be consuming **$15,000+/month** in API-equivalent value. This dashboard shows you exactly how much — per project, per session, per model, and across all your machines in one unified view. One command to start. Completely local.
+Your $200/month Max plan might be consuming **$15,000+/month** in API-equivalent value. This dashboard shows you exactly how much — per project, per session, per model, and across all your machines in one unified view. It also tracks your 7-day quota cycles, projects token usage at full utilization, and keeps history so you can spot if your effective quota quietly changed. One command to start. Completely local.
 
 ```bash
 npx claude-usage-dashboard
@@ -15,31 +15,39 @@ npx claude-usage-dashboard
 
 ## What You'll See
 
-### See Every Machine in One Place
+### :computer: See Every Machine in One Place
 
 Use Claude on a laptop, a desktop, and a work machine? Most dashboards only see the one they're running on. This one syncs across all of them.
 
 Point it at any shared folder — Google Drive, Dropbox, OneDrive, a NAS, an rsync target — and every machine's logs roll up into one unified view. No server. No account. Just a folder you already have.
 
-### Know What You're Spending
+### :dollar: Know What You're Spending
 
 Real-time projected API cost at your current usage rate — weekly and monthly. At 5% quota utilization, you might be burning through **$3,600/week** equivalent. The dashboard calculates this from your actual quota window, not estimates.
 
-### Track Your Quota in Real Time
+### :bar_chart: Track Your Quota in Real Time
 
 Live utilization gauges for 5-hour, 7-day, and per-model quotas pulled directly from the Anthropic API. Auto-detects your plan tier (Pro / Max 5x / Max 20x). Never get throttled by surprise again.
 
-### Find What's Eating Your Tokens
+### :chart_with_upwards_trend: Track Your Quota Across Cycles
+
+Anthropic doesn't publish exact token limits, and those limits can change without notice. The Quota Cycle History section gives you a running record of each 7-day cycle so you can see exactly how much you got and whether it stayed consistent.
+
+For each cycle, the dashboard projects what your full token quota would be at 100% utilization — broken down by Input, Output, Cache Read, Cache Write, and Total. A horizontal bar chart overlays actual vs. projected per cycle, and the history table highlights projected tokens and cost with a delta column showing the change versus the previous cycle.
+
+That delta is the key signal: if your projected quota drops from one cycle to the next without you changing how you work, something changed on the platform side. Track your actual consumption week-over-week so you have real numbers when something feels off — not just a gut feeling. Up to 10 past cycles are retained across all your machines.
+
+### :mag: Find What's Eating Your Tokens
 
 Per-project and per-session cost breakdowns show exactly where your usage goes. Sortable session table with cost, duration, and full token breakdown. Spot the expensive sessions instantly.
 
-### Understand Your Cache Efficiency
+### :zap: Understand Your Cache Efficiency
 
 You'll probably discover that ~95% of your tokens are cache reads at 1/10th the cost. The dashboard visualizes cache read vs. cache write vs. uncached requests so you can see how efficiently Claude is using context.
 
 ### Everything Else
 
-**Multi-machine sync** — aggregate usage across all your devices via a shared folder · Hourly/daily/weekly/monthly token trends · Dollar and token toggle · Model distribution across Opus/Sonnet/Haiku · Active hours heatmap · Auto-refresh (30s) · Persistent filters via localStorage · Dark theme
+**Multi-machine sync** — aggregate usage across all your devices via a shared folder · **Quota cycle tracking** — monitors each 7-day reset window, projects usage at 100% utilization, logs history to detect quota changes · Hourly/daily/weekly/monthly token trends · Dollar and token toggle · Model distribution across Opus/Sonnet/Haiku · Active hours heatmap · Auto-refresh (30s) · Persistent filters via localStorage · Dark theme
 
 ## Quick Start
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-usage-dashboard",
-  "version": "1.4.2",
-  "description": "Claude Code usage dashboard with multi-machine sync — token costs, quota tracking, cache efficiency, across all your devices",
+  "version": "1.5.1",
+  "description": "Claude Code usage dashboard — token costs, quota cycle tracking, cache efficiency, multi-machine sync across all your devices",
   "main": "server/index.js",
   "bin": {
     "claude-usage-dashboard": "bin/cli.cjs"

package/public/css/style.css

@@ -259,7 +259,29 @@ body {
 }
 #quota-section .chart-container { min-height: auto; }
 
+.delta-positive { color: var(--green); }
+.delta-negative { color: var(--red); }
+.table-container th.col-highlight,
+.table-container td.col-highlight { color: var(--amber); font-weight: 600; }
+
+.cycle-summary {
+  font-size: 12px;
+  font-weight: 400;
+  color: var(--amber);
+  margin-left: 8px;
+}
+
+.quota-cycles-layout {
+  display: grid;
+  grid-template-columns: 300px 1fr;
+  gap: 12px;
+  align-items: start;
+}
+.quota-cycles-chart { min-height: 160px; position: relative; }
+.quota-cycles-table-wrap { overflow-x: auto; }
+
 @media (max-width: 768px) {
   .summary-cards { grid-template-columns: repeat(2, 1fr); }
   .chart-row-3 { grid-template-columns: 1fr; }
+  .quota-cycles-layout { grid-template-columns: 1fr; }
 }

package/public/index.html

@@ -50,6 +50,21 @@
     <div id="chart-quota" class="chart-container"></div>
   </section>
 
+  <section class="chart-section" id="quota-cycles-section">
+    <div class="chart-header">
+      <h2>Quota Cycle History <span id="cycle-projection-summary" class="cycle-summary"></span></h2>
+      <div class="granularity-toggle" id="cycle-model-toggle">
+        <button data-cycle-model="overall" class="active">Overall</button>
+        <button data-cycle-model="opus">Opus</button>
+        <button data-cycle-model="sonnet">Sonnet</button>
+      </div>
+    </div>
+    <div class="quota-cycles-layout">
+      <div id="chart-quota-cycles" class="quota-cycles-chart"></div>
+      <div id="quota-cycles-table" class="table-container quota-cycles-table-wrap"></div>
+    </div>
+  </section>
+
   <section class="chart-section">
     <div class="chart-header">
       <h2>Token Consumption Trend</h2>

package/public/js/api.js

@@ -14,3 +14,4 @@ export async function fetchCache(params = {}) { return (await fetch(`${BASE}/cac
 export async function fetchStatus() { return (await fetch(`${BASE}/status`)).json(); }
 export async function fetchQuota() { return (await fetch(`${BASE}/quota`)).json(); }
 export async function fetchSubscription() { return (await fetch(`${BASE}/subscription`)).json(); }
+export async function fetchQuotaCycles() { return (await fetch(`${BASE}/quota-cycles`)).json(); }

package/public/js/app.js

@@ -1,4 +1,4 @@
-import { fetchUsage, fetchModels, fetchProjects, fetchSessions, fetchCost, fetchCache, fetchStatus, fetchQuota, fetchSubscription } from './api.js';
+import { fetchUsage, fetchModels, fetchProjects, fetchSessions, fetchCost, fetchCache, fetchStatus, fetchQuota, fetchSubscription, fetchQuotaCycles } from './api.js';
 import { initDatePicker } from './components/date-picker.js';
 import { initPlanSelector } from './components/plan-selector.js';
 import { renderTokenTrend } from './charts/token-trend.js';
@@ -8,6 +8,7 @@ import { renderCacheEfficiency } from './charts/cache-efficiency.js';
 import { renderProjectDistribution } from './charts/project-distribution.js';
 import { renderSessionTable } from './charts/session-stats.js';
 import { renderQuotaGauges } from './charts/quota-gauge.js';
+import { renderQuotaCycles } from './charts/quota-cycles.js';
 
 const state = {
   dateRange: { from: null, to: null },
@@ -19,6 +20,7 @@ const state = {
   sessionPage: 1,
   sessionProject: '',
   autoRefresh: localStorage.getItem('autoRefresh') !== 'false',
+  cycleModel: 'overall',
   autoRefreshInterval: 30,
   _refreshTimer: null,
   quotaRefreshInterval: 120,
@@ -83,6 +85,16 @@ async function loadQuota() {
     });
     const el = document.getElementById('quota-last-updated');
     if (el && data.lastFetched) el.textContent = `Updated ${new Date(data.lastFetched).toLocaleTimeString()} ${getTimezoneAbbr()}`;
+    loadQuotaCyclesData();
+  } catch { /* silently degrade */ }
+}
+
+async function loadQuotaCyclesData() {
+  try {
+    const data = await fetchQuotaCycles();
+    renderQuotaCycles(document.getElementById('chart-quota-cycles'), data, {
+      modelKey: state.cycleModel,
+    });
   } catch { /* silently degrade */ }
 }
 
@@ -273,6 +285,16 @@ function init() {
     }
   });
 
+  document.getElementById('cycle-model-toggle').addEventListener('click', (e) => {
+    if (e.target.tagName === 'BUTTON') {
+      state.cycleModel = e.target.dataset.cycleModel;
+      document.querySelectorAll('#cycle-model-toggle button').forEach(btn => {
+        btn.classList.toggle('active', btn.dataset.cycleModel === state.cycleModel);
+      });
+      loadQuotaCyclesData();
+    }
+  });
+
   // Auto-detect subscription tier
   fetchSubscription().then(info => {
     if (info.plan) {

package/public/js/charts/quota-cycles.js

@@ -0,0 +1,209 @@
+const fmt = (n) => {
+  if (n == null) return '—';
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + 'M';
+  if (n >= 1_000) return (n / 1_000).toFixed(0) + 'K';
+  return n.toString();
+};
+
+const fmtCost = (n) => n == null ? '—' : `$${n.toFixed(2)}`;
+
+const fmtDate = (iso) => {
+  const d = new Date(iso);
+  return `${d.getMonth() + 1}/${d.getDate()}`;
+};
+
+function getModelData(cycle, modelKey) {
+  if (modelKey === 'overall') return cycle.overall;
+  return cycle.models?.[modelKey] || { utilization: 0, actualTokens: 0, projectedTokensAt100: null, actualCost: 0, projectedCostAt100: null, tokens: { input: 0, output: 0, cacheRead: 0, cacheCreation: 0 } };
+}
+
+const MAX_DISPLAY_CYCLES = 10;
+
+export function renderQuotaCycles(container, data, { modelKey = 'overall' } = {}) {
+  if (!container) return;
+
+  const hasModelData = data.currentCycle &&
+    ((data.currentCycle.models?.opus?.utilization > 0) ||
+     (data.currentCycle.models?.sonnet?.utilization > 0));
+
+  // --- Model toggle: grey out when no data ---
+  const toggleEl = document.getElementById('cycle-model-toggle');
+  if (toggleEl) {
+    toggleEl.querySelectorAll('button[data-cycle-model="opus"], button[data-cycle-model="sonnet"]').forEach(btn => {
+      btn.disabled = !hasModelData;
+    });
+  }
+
+  // --- Inline projection summary in header ---
+  const summaryEl = document.getElementById('cycle-projection-summary');
+  if (summaryEl) {
+    summaryEl.textContent = '';
+  }
+
+  // --- Bar Chart (compact) ---
+  container.innerHTML = '';
+
+  const allCycles = [];
+  if (data.history) allCycles.push(...[...data.history].reverse());
+  if (data.currentCycle) allCycles.push(data.currentCycle);
+
+  if (allCycles.length === 0) {
+    container.innerHTML = '<div style="color:#64748b;text-align:center;padding:20px;font-size:12px">No cycle data yet.</div>';
+    return;
+  }
+
+  const displayAll = allCycles.slice(-MAX_DISPLAY_CYCLES);
+
+  const chartData = displayAll.map(c => {
+    const d = getModelData(c, modelKey);
+    return {
+      label: `${fmtDate(c.start)}–${fmtDate(c.resets_at)}`,
+      actual: d.actualTokens,
+      projected: d.projectedTokensAt100,
+      isCurrent: c === data.currentCycle,
+    };
+  });
+
+  // Horizontal bar chart
+  const rowHeight = 28;
+  const margin = { top: 20, right: 50, bottom: 6, left: 70 };
+  const width = container.clientWidth - margin.left - margin.right;
+  const height = chartData.length * rowHeight;
+
+  const svg = d3.select(container).append('svg')
+    .attr('width', width + margin.left + margin.right)
+    .attr('height', height + margin.top + margin.bottom)
+    .append('g').attr('transform', `translate(${margin.left},${margin.top})`);
+
+  const y0 = d3.scaleBand().domain(chartData.map(d => d.label)).range([0, height]).padding(0.25);
+  const maxVal = d3.max(chartData, d => Math.max(d.actual, d.projected || 0)) || 1;
+  const x = d3.scaleLinear().domain([0, maxVal * 1.1]).range([0, width]);
+
+  // Axes
+  svg.append('g')
+    .call(d3.axisLeft(y0).tickSize(0))
+    .selectAll('text').attr('fill', '#94a3b8').style('font-size', '9px');
+  svg.append('g').attr('transform', `translate(0,${height})`)
+    .call(d3.axisBottom(x).ticks(4).tickFormat(d => fmt(d)))
+    .selectAll('text').attr('fill', '#94a3b8').style('font-size', '9px');
+  svg.selectAll('.domain, .tick line').attr('stroke', '#334155');
+
+  const barH = Math.min(y0.bandwidth() / 2.5, 12);
+
+  // Projected bars (behind, semi-transparent)
+  svg.selectAll('.bar-projected').data(chartData.filter(d => d.projected != null))
+    .join('rect').attr('class', 'bar-projected')
+    .attr('x', 0)
+    .attr('width', d => x(d.projected))
+    .attr('y', d => y0(d.label) + y0.bandwidth() / 2 - barH)
+    .attr('height', barH * 2)
+    .attr('fill', '#f59e0b').attr('opacity', 0.2)
+    .attr('rx', 2);
+
+  // Tooltip
+  const tooltip = d3.select(container).append('div')
+    .attr('class', 'd3-tooltip')
+    .style('opacity', 0);
+
+  function showTip(event, d) {
+    const proj = d.projected != null ? fmt(d.projected) : '—';
+    const rect = container.getBoundingClientRect();
+    tooltip.html(`<strong>${d.label}</strong><br>Actual: ${fmt(d.actual)}<br>Proj@100%: ${proj}`)
+      .style('opacity', 1)
+      .style('left', (event.clientX - rect.left + 12) + 'px')
+      .style('top', (event.clientY - rect.top - 10) + 'px');
+  }
+  function hideTip() { tooltip.style('opacity', 0); }
+
+  // Actual bars (front)
+  svg.selectAll('.bar-actual').data(chartData)
+    .join('rect').attr('class', 'bar-actual')
+    .attr('x', 0)
+    .attr('width', d => x(d.actual))
+    .attr('y', d => y0(d.label) + y0.bandwidth() / 2 - barH / 2)
+    .attr('height', barH)
+    .attr('fill', d => d.isCurrent ? '#3b82f6' : '#60a5fa')
+    .attr('rx', 2);
+
+  // Hover areas (full row for easy targeting)
+  svg.selectAll('.bar-hover').data(chartData)
+    .join('rect').attr('class', 'bar-hover')
+    .attr('x', 0)
+    .attr('width', width)
+    .attr('y', d => y0(d.label))
+    .attr('height', y0.bandwidth())
+    .attr('fill', 'transparent')
+    .style('cursor', 'pointer')
+    .on('mousemove', showTip)
+    .on('mouseleave', hideTip);
+
+  // Compact legend
+  const legend = svg.append('g').attr('transform', `translate(0, -8)`);
+  legend.append('rect').attr('width', 8).attr('height', 8).attr('fill', '#60a5fa').attr('rx', 1);
+  legend.append('text').attr('x', 10).attr('y', 7).text('Actual').attr('fill', '#64748b').style('font-size', '9px');
+  legend.append('rect').attr('x', 50).attr('width', 8).attr('height', 8).attr('fill', '#f59e0b').attr('opacity', 0.4).attr('rx', 1);
+  legend.append('text').attr('x', 60).attr('y', 7).text('Proj@100%').attr('fill', '#64748b').style('font-size', '9px');
+
+  // --- History Table ---
+  const tableEl = document.getElementById('quota-cycles-table');
+  if (!tableEl) return;
+  tableEl.innerHTML = '';
+
+  const table = document.createElement('table');
+  const thead = document.createElement('thead');
+  thead.innerHTML = `<tr>
+    <th>Cycle</th>
+    <th class="align-right">Util%</th>
+    <th class="align-right">In</th>
+    <th class="align-right">Out</th>
+    <th class="align-right">CR</th>
+    <th class="align-right">CW</th>
+    <th class="align-right">Total</th>
+    <th class="align-right">Excl CR</th>
+    <th class="align-right">Cost</th>
+    <th class="align-right col-highlight">Proj Tokens</th>
+    <th class="align-right col-highlight">Proj Cost</th>
+    <th class="align-right">\u0394 Prev</th>
+  </tr>`;
+  table.appendChild(thead);
+
+  const tbody = document.createElement('tbody');
+  const displayCycles = [...displayAll].reverse();
+  for (let i = 0; i < displayCycles.length; i++) {
+    const c = displayCycles[i];
+    const d = getModelData(c, modelKey);
+    const t = d.tokens || { input: 0, output: 0, cacheRead: 0, cacheCreation: 0 };
+    const totalInclCR = t.input + t.output + t.cacheRead + t.cacheCreation;
+    const prev = displayCycles[i + 1] ? getModelData(displayCycles[i + 1], modelKey) : null;
+
+    let deltaStr = '—';
+    let deltaClass = '';
+    if (prev && prev.projectedTokensAt100 != null && d.projectedTokensAt100 != null && prev.projectedTokensAt100 > 0) {
+      const delta = ((d.projectedTokensAt100 - prev.projectedTokensAt100) / prev.projectedTokensAt100) * 100;
+      deltaStr = `${delta >= 0 ? '+' : ''}${delta.toFixed(1)}%`;
+      deltaClass = delta >= 0 ? 'delta-positive' : 'delta-negative';
+    }
+
+    const isCurrent = c === data.currentCycle;
+    const label = `${fmtDate(c.start)}–${fmtDate(c.resets_at)}${isCurrent ? ' *' : ''}`;
+
+    const tr = document.createElement('tr');
+    tr.innerHTML = `
+      <td>${label}</td>
+      <td class="align-right">${d.utilization.toFixed(1)}%</td>
+      <td class="align-right">${fmt(t.input)}</td>
+      <td class="align-right">${fmt(t.output)}</td>
+      <td class="align-right">${fmt(t.cacheRead)}</td>
+      <td class="align-right">${fmt(t.cacheCreation)}</td>
+      <td class="align-right">${fmt(totalInclCR)}</td>
+      <td class="align-right">${fmt(d.actualTokens)}</td>
+      <td class="align-right">${fmtCost(d.actualCost)}</td>
+      <td class="align-right col-highlight">${fmt(d.projectedTokensAt100)}</td>
+      <td class="align-right col-highlight">${fmtCost(d.projectedCostAt100)}</td>
+      <td class="align-right ${deltaClass}">${deltaStr}</td>
+    `;
+    tbody.appendChild(tr);
+  }
+  table.appendChild(tbody);
+  tableEl.appendChild(table);
+}

package/server/quota-cycles.js

@@ -0,0 +1,274 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { parseLogDirectory } from './parser.js';
+import { filterByDateRange } from './aggregator.js';
+import { calculateRecordCost } from './pricing.js';
+
+const MAX_HISTORY = 52;
+
+/**
+ * Pure computation: given records (already filtered to a cycle) and quota data,
+ * compute actual tokens/cost and project at 100% utilization.
+ */
+export function computeCycleData(records, quotaData) {
+  const overallUtil = quotaData.seven_day?.utilization || 0;
+  const opusUtil = quotaData.seven_day_opus?.utilization || 0;
+  const sonnetUtil = quotaData.seven_day_sonnet?.utilization || 0;
+
+  // Per-type accumulators
+  let inTok = 0, outTok = 0, crTok = 0, cwTok = 0, totalCost = 0;
+  let opusIn = 0, opusOut = 0, opusCR = 0, opusCW = 0, opusCost = 0;
+  let sonIn = 0, sonOut = 0, sonCR = 0, sonCW = 0, sonnetCost = 0;
+
+  for (const r of records) {
+    const cost = calculateRecordCost(r);
+    inTok += r.input_tokens; outTok += r.output_tokens;
+    crTok += r.cache_read_tokens; cwTok += r.cache_creation_tokens;
+    totalCost += cost;
+
+    if (r.model?.includes('opus')) {
+      opusIn += r.input_tokens; opusOut += r.output_tokens;
+      opusCR += r.cache_read_tokens; opusCW += r.cache_creation_tokens;
+      opusCost += cost;
+    } else if (r.model?.includes('sonnet')) {
+      sonIn += r.input_tokens; sonOut += r.output_tokens;
+      sonCR += r.cache_read_tokens; sonCW += r.cache_creation_tokens;
+      sonnetCost += cost;
+    }
+  }
+
+  totalCost = Math.round(totalCost * 100) / 100;
+  opusCost = Math.round(opusCost * 100) / 100;
+  sonnetCost = Math.round(sonnetCost * 100) / 100;
+
+  function buildTokens(inp, out, cr, cw) {
+    return { input: inp, output: out, cacheRead: cr, cacheCreation: cw };
+  }
+
+  function project(actual, utilization) {
+    if (utilization <= 0) return null;
+    return Math.round(actual / (utilization / 100));
+  }
+
+  function projectCost(actual, utilization) {
+    if (utilization <= 0) return null;
+    return Math.round((actual / (utilization / 100)) * 100) / 100;
+  }
+
+  // actualTokens = total excluding cache reads (in + out + cw) — used for projections
+  const totalExclCR = inTok + outTok + cwTok;
+  const opusExclCR = opusIn + opusOut + opusCW;
+  const sonExclCR = sonIn + sonOut + sonCW;
+
+  return {
+    overall: {
+      utilization: overallUtil,
+      tokens: buildTokens(inTok, outTok, crTok, cwTok),
+      actualTokens: totalExclCR,
+      projectedTokensAt100: project(totalExclCR, overallUtil),
+      actualCost: totalCost,
+      projectedCostAt100: projectCost(totalCost, overallUtil),
+    },
+    models: {
+      opus: {
+        utilization: opusUtil,
+        tokens: buildTokens(opusIn, opusOut, opusCR, opusCW),
+        actualTokens: opusExclCR,
+        projectedTokensAt100: project(opusExclCR, opusUtil),
+        actualCost: opusCost,
+        projectedCostAt100: projectCost(opusCost, opusUtil),
+      },
+      sonnet: {
+        utilization: sonnetUtil,
+        tokens: buildTokens(sonIn, sonOut, sonCR, sonCW),
+        actualTokens: sonExclCR,
+        projectedTokensAt100: project(sonExclCR, sonnetUtil),
+        actualCost: sonnetCost,
+        projectedCostAt100: projectCost(sonnetCost, sonnetUtil),
+      },
+    },
+  };
+}
+
+/**
+ * Update the quota cycle snapshot file for this machine.
+ * Called after each successful quota API fetch.
+ *
+ * @param {object} quotaData - Quota API response (must have available === true)
+ * @param {string} logBaseDir - This machine's log directory (~/.claude/projects/)
+ * @param {string} machineName - Identifier for this machine
+ * @param {string} [snapshotDir] - Directory for snapshot files (defaults to syncDir or ~/.claude/)
+ * @param {string} [syncDir] - Shared sync directory; used as fallback when snapshotDir is not set
+ */
+export function updateQuotaCycleSnapshot(quotaData, logBaseDir, machineName, snapshotDir, syncDir) {
+  if (!quotaData?.available || !quotaData.seven_day?.resets_at) return;
+
+  const dir = snapshotDir || syncDir || path.join(os.homedir(), '.claude');
+  const filePath = path.join(dir, `quota-cycles-${machineName}.json`);
+
+  // Normalize resets_at to second precision — the API returns varying microseconds
+  // on each call (e.g. .905316 vs .581788) which would cause false cycle switches
+  const rawResetsAt = new Date(quotaData.seven_day.resets_at);
+  rawResetsAt.setMilliseconds(0);
+  const resetsAt = rawResetsAt.toISOString();
+  const start = new Date(rawResetsAt.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString();
+
+  let snapshot;
+  try {
+    snapshot = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    snapshot = { schemaVersion: 1, machineName, currentCycle: null, history: [] };
+  }
+
+  // Compare normalized timestamps to detect actual cycle boundary changes
+  const storedResetNorm = snapshot.currentCycle
+    ? new Date(snapshot.currentCycle.resets_at).setMilliseconds(0)
+    : null;
+  if (snapshot.currentCycle && storedResetNorm !== rawResetsAt.getTime()) {
+    snapshot.history.unshift(snapshot.currentCycle);
+    if (snapshot.history.length > MAX_HISTORY) {
+      snapshot.history = snapshot.history.slice(0, MAX_HISTORY);
+    }
+    snapshot.currentCycle = null;
+  }
+
+  const allRecords = parseLogDirectory(logBaseDir);
+  const cycleRecords = filterByDateRange(allRecords, start, resetsAt);
+  const cycleData = computeCycleData(cycleRecords, quotaData);
+
+  snapshot.currentCycle = {
+    resets_at: resetsAt,
+    start,
+    lastUpdated: new Date().toISOString(),
+    ...cycleData,
+  };
+
+  fs.writeFileSync(filePath, JSON.stringify(snapshot, null, 2));
+}
+
+/**
+ * Load and merge quota cycle data from all machines.
+ *
+ * @param {string} machineName - This machine's name
+ * @param {string|null} syncDir - Shared sync directory (null if single-machine)
+ * @param {string} [snapshotDir] - Directory for snapshot files (defaults to ~/.claude/)
+ * @returns {{ currentCycle: object|null, history: object[], machines: string[] }}
+ */
+export function loadQuotaCycles(machineName, syncDir, snapshotDir) {
+  const dir = snapshotDir || syncDir || path.join(os.homedir(), '.claude');
+  const empty = { currentCycle: null, history: [], machines: [] };
+
+  let files;
+  try {
+    files = fs.readdirSync(dir).filter(f => f.startsWith('quota-cycles-') && f.endsWith('.json'));
+  } catch {
+    return empty;
+  }
+
+  if (files.length === 0) return empty;
+
+  const snapshots = [];
+  for (const file of files) {
+    try {
+      const data = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf-8'));
+      if (data.schemaVersion === 1) snapshots.push(data);
+    } catch { /* skip corrupt files */ }
+  }
+
+  if (snapshots.length === 0) return empty;
+
+  const machines = snapshots.map(s => s.machineName);
+
+  if (snapshots.length === 1) {
+    const s = snapshots[0];
+    return { currentCycle: s.currentCycle, history: s.history, machines };
+  }
+
+  return {
+    currentCycle: mergeCycles(snapshots.map(s => s.currentCycle).filter(Boolean)),
+    history: mergeHistories(snapshots.map(s => s.history)),
+    machines,
+  };
+}
+
+function mergeCycles(cycles) {
+  if (cycles.length === 0) return null;
+  if (cycles.length === 1) return cycles[0];
+
+  const byReset = new Map();
+  for (const c of cycles) {
+    const key = c.resets_at;
+    if (!byReset.has(key)) byReset.set(key, []);
+    byReset.get(key).push(c);
+  }
+
+  let bestKey = null, bestCount = 0;
+  for (const [key, arr] of byReset) {
+    if (arr.length > bestCount || (arr.length === bestCount && key > bestKey)) { bestKey = key; bestCount = arr.length; }
+  }
+
+  const sameCycle = byReset.get(bestKey);
+  return mergeSamePeriodCycles(sameCycle);
+}
+
+function mergeSamePeriodCycles(cycles) {
+  const mostRecent = cycles.reduce((a, b) =>
+    new Date(a.lastUpdated) > new Date(b.lastUpdated) ? a : b
+  );
+
+  return {
+    resets_at: mostRecent.resets_at,
+    start: mostRecent.start,
+    lastUpdated: mostRecent.lastUpdated,
+    overall: mergeMetrics(cycles.map(c => c.overall), mostRecent.overall.utilization),
+    models: {
+      opus: mergeMetrics(cycles.map(c => c.models.opus), mostRecent.models?.opus?.utilization || 0),
+      sonnet: mergeMetrics(cycles.map(c => c.models.sonnet), mostRecent.models?.sonnet?.utilization || 0),
+    },
+  };
+}
+
+function mergeMetrics(metricsArray, utilization) {
+  const totalTokens = metricsArray.reduce((sum, m) => sum + (m?.actualTokens || 0), 0);
+  const totalCost = Math.round(metricsArray.reduce((sum, m) => sum + (m?.actualCost || 0), 0) * 100) / 100;
+
+  // Merge per-type token breakdown
+  const tokens = { input: 0, output: 0, cacheRead: 0, cacheCreation: 0 };
+  for (const m of metricsArray) {
+    if (m?.tokens) {
+      tokens.input += m.tokens.input || 0;
+      tokens.output += m.tokens.output || 0;
+      tokens.cacheRead += m.tokens.cacheRead || 0;
+      tokens.cacheCreation += m.tokens.cacheCreation || 0;
+    }
+  }
+
+  return {
+    utilization,
+    tokens,
+    actualTokens: totalTokens,
+    projectedTokensAt100: utilization > 0 ? Math.round(totalTokens / (utilization / 100)) : null,
+    actualCost: totalCost,
+    projectedCostAt100: utilization > 0 ? Math.round((totalCost / (utilization / 100)) * 100) / 100 : null,
+  };
+}
+
+function mergeHistories(historyArrays) {
+  const byReset = new Map();
+  for (const history of historyArrays) {
+    for (const entry of history) {
+      const key = entry.resets_at;
+      if (!byReset.has(key)) byReset.set(key, []);
+      byReset.get(key).push(entry);
+    }
+  }
+
+  const merged = [];
+  for (const [, entries] of byReset) {
+    merged.push(mergeSamePeriodCycles(entries));
+  }
+
+  merged.sort((a, b) => new Date(b.resets_at) - new Date(a.resets_at));
+  return merged.slice(0, MAX_HISTORY);
+}

package/server/routes/api.js

@@ -1,10 +1,12 @@
 import { Router } from 'express';
+import os from 'os';
 import { parseLogDirectory, parseMultiMachineDirectory } from '../parser.js';
 import { syncLocalToShared } from '../sync.js';
 import { filterByDateRange, autoGranularity, aggregateByTime, aggregateBySession, aggregateByProject, aggregateByModel, aggregateCache } from '../aggregator.js';
 import { calculateRecordCost, PLAN_DEFAULTS } from '../pricing.js';
 import { createQuotaFetcher } from '../quota.js';
 import { getSubscriptionInfo } from '../credentials.js';
+import { updateQuotaCycleSnapshot, loadQuotaCycles } from '../quota-cycles.js';
 
 export function createApiRouter(logBaseDir, options = {}) {
   const router = Router();
@@ -117,12 +119,44 @@ export function createApiRouter(logBaseDir, options = {}) {
   router.get('/quota', async (req, res) => {
     try {
       const data = await quotaFetcher.fetchQuota();
+      if (data.available) {
+        try {
+          updateQuotaCycleSnapshot(
+            data,
+            logBaseDir,
+            options.machineName || os.hostname(),
+            options.snapshotDir,
+            options.syncDir
+          );
+        } catch (err) {
+          console.warn('Failed to update quota cycle snapshot:', err.message);
+        }
+      }
       res.json(data);
     } catch (err) {
       res.json({ available: false, error: err.message });
     }
   });
 
+  router.get('/quota-cycles', (req, res) => {
+    try {
+      const data = loadQuotaCycles(
+        options.machineName || os.hostname(),
+        options.syncDir || null,
+        options.snapshotDir
+      );
+      if (data.currentCycle) {
+        const start = new Date(data.currentCycle.start);
+        const now = new Date();
+        data.currentCycle.daysElapsed = Math.round(((now - start) / (1000 * 60 * 60 * 24)) * 10) / 10;
+        data.currentCycle.daysTotal = 7;
+      }
+      res.json(data);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
   router.get('/subscription', (req, res) => {
     const info = options.getSubscriptionInfo ? options.getSubscriptionInfo() : getSubscriptionInfo();
     res.json(info || { plan: null, subscriptionType: null, rateLimitTier: null });