claude-rpc 0.15.5 → 0.16.0

package/README.md

@@ -109,6 +109,8 @@ A card that updates as you work. The large image swaps between five states (work
 
 A *View on GitHub →* button appears automatically when your cwd is a git repo with a github origin. The daemon checks `.git/config` directly — no shell-out, no surprise GH API call.
 
+A rotation frame can show your **subscription usage** — `Usage · 34% weekly` — the exact numbers Claude Code's own `/usage` screen shows. The daemon asks Anthropic's usage endpoint with the OAuth token Claude Code already stores locally; the token goes only to its issuer, the percentages go only where you template them, and `usage.enabled: false` turns the whole thing off ([`SECURITY.md` §3d](SECURITY.md)). `claude-rpc usage` prints the same data as heat-graded bars in your terminal.
+
 ### on your machine
 
 Three local surfaces, all reading the same `~/.claude-rpc/aggregate.json`:
@@ -269,6 +271,7 @@ The full default config is in [`src/default-config.js`](src/default-config.js)
 | `start` / `stop` / `restart` | Lifecycle for the detached daemon |
 | `status`         | Interactive TUI — heatmap, hour histogram, leaderboards (`--dump` for plain output) |
 | `today` / `week` | Focused views (today's stats, weekday breakdown) |
+| `usage`          | Subscription limits — session + weekly %, the same numbers `/usage` shows |
 | `serve`          | Open the local web dashboard (port 47474) |
 | `preview`        | Render every rotation frame against real state |
 | `scan` / `rescan`| Incremental / forced re-parse of `~/.claude/projects` |

package/SECURITY.md

@@ -78,7 +78,9 @@ events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`,
 
 ## 3. Outbound network
 
-There are three distinct network behaviors. Two are optional; one is cosmetic.
+There are five distinct network behaviors: community totals (3a), gist
+publishing (3b), squads/web login (3c), subscription-usage polling (3d), and
+the cosmetic GIF assets (3e). Each is independently optional.
 
 ### 3a. Community totals (telemetry) — ON by default for fresh installs
 
@@ -142,7 +144,36 @@ Worker-side storage adds: `gh:<login>` → profile link, `squad:*` membership
 records, and weekly baseline snapshots (auto-expiring). Leaving your last
 squad deletes its record.
 
-### 3d. Presence GIF assets — Discord-side only
+### 3d. Subscription usage — your own token, to its issuer, ON by default
+
+**Source:** `src/usage.js`; consumed by the daemon poll, `claude-rpc usage`,
+and the `{usageWeeklyPct}`-family template variables.
+
+The daemon reads the OAuth access token Claude Code already stores on your
+machine (`~/.claude/.credentials.json`; the login keychain on macOS) and calls
+`GET https://api.anthropic.com/api/oauth/usage` — the same internal endpoint
+Claude Code's own `/usage` screen uses — every 10 minutes **while a session is
+live**. The response (session %, weekly %, reset times) is cached in
+`$TMPDIR/claude-rpc/usage.json`.
+
+The trust boundary is deliberately narrow:
+
+- The token is sent **only to `api.anthropic.com` — the party that issued
+  it**. It is never logged, never written anywhere new, and never sent to the
+  claude-rpc worker or any other host. Only the daemon and the one-shot
+  `claude-rpc usage` command touch credentials; every other surface reads the
+  percentage cache.
+- **Read-only:** the refresh token is never used or modified. If the access
+  token expires, polling goes quiet until Claude Code itself refreshes it.
+- The percentages stay local unless **you** template them into your Discord
+  card (a default rotation frame does, and disappears whenever data is
+  missing or stale).
+- Installs without OAuth credentials (API key, enterprise gateways) are
+  silently skipped — there is nothing to fetch.
+- **Off switch:** `usage.enabled: false` in `config.json` stops the polling,
+  the command's live fetch, and the card frame in one go.
+
+### 3e. Presence GIF assets — Discord-side only
 
 `default-config.js` references `https://cdn.qualit.ly/clawd-*.gif`. These URLs
 are handed to Discord as image keys; **Discord's** client fetches them to render

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-rpc",
-  "version": "0.15.5",
+  "version": "0.16.0",
   "description": "Discord Rich Presence for Claude Code — live model, project, tokens, and lifetime stats driven by Claude Code's hook system.",
   "type": "module",
   "license": "MIT",

package/src/cli.js

@@ -23,13 +23,14 @@ import { badgeSvg } from './badge.js';
 import { fmtCost } from './pricing.js';
 import { addPrivateCwd, removePrivateCwd, listPrivateCwds, resolveVisibility } from './privacy.js';
 import { parseDuration, setPause, clearPause, pauseUntil } from './pause.js';
+import { readUsageCache, fetchUsage, writeUsageCache, fmtResetTime, fmtResetDay } from './usage.js';
 import { loadConfig, hasUserConfig } from './config.js';
 import * as lb from './leaderboard.js';
 import { VERSION } from './version.js';
 import { fail, tailLines, heat, sparkline, fmtDelta, topPercentile, EX_USER_ERROR, EX_BAD_STATE, EX_SYS_ERROR } from './ui.js';
 import { randomUUID } from 'node:crypto';
 import { createInterface } from 'node:readline';
-import { basename } from 'node:path';
+import { basename, join } from 'node:path';
 
 const cmd = process.argv[2];
 
@@ -316,6 +317,7 @@ function showStatus() {
   const config = loadConfig();
   const live = findLiveSessions({ thresholdMs: 90_000 });
   state.liveSessions = live;
+  state.usage = readUsageCache();
   const vars = buildVars(state, config, aggregate);
   const pid = daemonPid();
 
@@ -357,6 +359,11 @@ function showStatus() {
     box('today', todayBoxLines(vars, aggregate));
     console.log('');
 
+    if (state.usage) {
+      box('claude usage', usageBoxLines(state.usage));
+      console.log('');
+    }
+
     box('streak', [
       pair('current',   `${c.bold}${c.magenta}${vars.streak}${c.reset} ${c.dim}days${c.reset}`, ''),
       pair('longest',   `${vars.longestStreak} ${c.dim}days${c.reset}`, c.cyan),
@@ -581,6 +588,54 @@ function showWeek() {
   }
 }
 
+// Rows for the subscription-usage box (shared by `status` and `usage`).
+// Bars ride the heat ramp — the % IS the intensity. Absent buckets (per-model
+// outside Max plans) drop out.
+function usageBoxLines(u) {
+  const row = (label, pct, resets) => pct == null ? null : pair(
+    label,
+    `${bar(pct, 100, 18)} ${c.bold}${String(pct).padStart(3)}%${c.reset}${resets ? `  ${c.dim}resets ${resets}${c.reset}` : ''}`,
+    '',
+  );
+  return [
+    row('session (5h)', u.sessionPct, fmtResetTime(u.sessionResetsAt)),
+    row('week',         u.weeklyPct,  fmtResetDay(u.weeklyResetsAt)),
+    row('  sonnet',     u.weeklySonnetPct, null),
+    row('  opus',       u.weeklyOpusPct,   null),
+  ].filter(Boolean);
+}
+
+// `claude-rpc usage` — subscription limits, the same numbers Claude Code's
+// /usage screen shows. Prefers the daemon's cache; falls back to a one-shot
+// live fetch so it works with the daemon stopped.
+async function showUsage() {
+  let u = readUsageCache();
+  let src = 'cached by the daemon';
+  if (!u) {
+    const r = await fetchUsage();
+    if (!r.ok) {
+      const hints = {
+        'no-credentials': 'claude-rpc reads Claude Code\'s own OAuth credentials (~/.claude) — API-key installs have no subscription limits to show',
+        'token-expired': 'Claude Code\'s token has expired — open Claude Code once; it refreshes itself',
+        unauthorized: 'the token was rejected — open Claude Code once; it refreshes itself',
+      };
+      return fail(`could not fetch usage: ${r.reason}`,
+        { hint: hints[r.reason] || 'check your network and try again', code: EX_SYS_ERROR });
+    }
+    u = r.usage;
+    src = 'live';
+    writeUsageCache(u); // so preview/status/frames see it without the daemon
+  }
+  const plan = u.plan ? ` · Claude ${u.plan.charAt(0).toUpperCase()}${u.plan.slice(1)}` : '';
+  console.log('');
+  console.log(`  ${c.bold}${c.magenta}◆ usage${c.reset}  ${c.dim}— subscription limits${plan} (what /usage shows)${c.reset}`);
+  console.log('');
+  box('usage', usageBoxLines(u));
+  console.log('');
+  console.log(`  ${c.dim}${src} · the daemon polls every ${loadConfig().usage?.pollIntervalMin || 10} min while you code · off: usage.enabled false${c.reset}`);
+  console.log('');
+}
+
 function statusColor(status) {
   switch (status) {
     case 'working':  return c.green;
@@ -598,6 +653,7 @@ function showPreview() {
   const live = findLiveSessions({ thresholdMs: 90_000 });
   state.liveSessions = live;
   state = applyIdle(state, config);
+  state.usage = readUsageCache();
   const vars = buildVars(state, config, aggregate);
   const p = config.presence || {};
   const frames = (Array.isArray(p.rotation) ? p.rotation : [{ details: p.details, state: p.state }]);
@@ -637,6 +693,7 @@ function dumpVars() {
   const config = loadConfig();
   state.liveSessions = findLiveSessions({ thresholdMs: 90_000 });
   state = applyIdle(state, config);
+  state.usage = readUsageCache();
   const live = buildVars(state, config, readAggregate() || {});
   process.stdout.write(JSON.stringify({ vars: Object.keys(live).sort(), live }));
 }
@@ -863,6 +920,7 @@ function liveVars() {
   state.liveSessions = findLiveSessions({ thresholdMs: 90_000 });
   const config = loadConfig();
   const resolved = applyIdle(state, config);
+  resolved.usage = readUsageCache();
   return { vars: buildVars(resolved, config, readAggregate()), config };
 }
 
@@ -1713,6 +1771,7 @@ function overview() {
   const state = readState();
   const aggregate = readAggregate();
   state.liveSessions = findLiveSessions({ thresholdMs: 90_000 });
+  state.usage = readUsageCache();
   const vars = buildVars(state, cfg, aggregate);
   const dot = pid
     ? `${c.green}●${c.reset} running ${c.dim}pid ${pid}${c.reset}`
@@ -1768,6 +1827,7 @@ function help() {
     ['status',    'Print current session + all-time stats'],
     ['today',     'Focus view: today\'s stats + 24h activity histogram'],
     ['week',      'Focus view: this week, daily breakdown'],
+    ['usage',     'Subscription limits — session + weekly % (what /usage shows)'],
     ['serve',     'Open a live web dashboard in your browser'],
     ['preview',   'Show how each rotation frame renders right now'],
     ['scan',      'Incrementally scan ~/.claude/projects for all-time totals'],
@@ -1849,14 +1909,33 @@ const packagedDefault = IS_PACKAGED && !cmd;
       try {
         if (IS_NPX) {
           // Our own tree is npm's throwaway _npx cache; launch from the global
-          // install setup just promoted to, via the PATH-resolved bin.
+          // install setup just promoted to. The global copy must be resolved
+          // EXPLICITLY (npm root -g): inside an npx run, PATH has the _npx
+          // cache's .bin first, so a bare `claude-rpc` resolves right back
+          // into the cache we're escaping. And it must be spawned as a direct
+          // `node <script>` child — a shell+shim chain (cmd → .cmd → node)
+          // only hides the FIRST hop's window; the detached cmd loses its
+          // console, the grandchild node allocates a fresh one, and Windows 11
+          // pops it as a visible Windows Terminal window whose closure kills
+          // the daemon.
           if (!daemonPid()) {
-            const child = spawn('claude-rpc', ['daemon'], {
+            let script = null;
+            try {
+              const r = spawnSync('npm', ['root', '-g'], {
+                encoding: 'utf8', timeout: 8000, windowsHide: true,
+                shell: process.platform === 'win32',   // npm is npm.cmd on Windows
+              });
+              const root = (r.stdout || '').trim();
+              const candidate = root && join(root, 'claude-rpc', 'src', 'daemon.js');
+              if (candidate && existsSync(candidate)) script = candidate;
+            } catch { /* npm unavailable → fall back below */ }
+            // Fallback: run from this (npx) tree. Still invisible — only the
+            // npx-cache-eviction caveat remains, healed by the next setup.
+            const child = spawn(process.execPath, [script || DAEMON_SCRIPT], {
               detached: true, stdio: 'ignore', windowsHide: true,
-              shell: process.platform === 'win32',
             });
             child.unref();
-            console.log(`  ${c.green}✓${c.reset}  ${'daemon launched'.padEnd(16)}${c.dim}log ${shortPath(LOG_PATH)}${c.reset}`);
+            console.log(`  ${c.green}✓${c.reset}  ${'daemon launched'.padEnd(16)}${c.dim}pid ${c.reset}${c.cyan}${child.pid}${c.reset}${c.dim} · log ${shortPath(LOG_PATH)}${c.reset}`);
           } else {
             console.log(`  ${c.cyan}·${c.reset}  ${'daemon running'.padEnd(16)}${c.dim}pid ${daemonPid()}${c.reset}`);
           }
@@ -1886,6 +1965,7 @@ const packagedDefault = IS_PACKAGED && !cmd;
     case 'dump':      showStatus(); break;
     case 'today':     showToday(); break;
     case 'week':      showWeek(); break;
+    case 'usage':     await showUsage(); break;
     case 'serve':     await import('./server/index.js'); break;
     case 'preview':   showPreview(); break;
     case 'vars':      dumpVars(); break;

package/src/daemon.js

@@ -13,6 +13,7 @@ import { migrateConfig } from './install.js';
 import { desktopNotify, postWebhook, shouldWebhook, shouldNotify } from './notify.js';
 import { humanProject } from './format.js';
 import { CONFIG_PATH, STATE_PATH, PID_PATH, LOG_PATH, STATE_DIR, AGGREGATE_PATH, PAUSE_PATH } from './paths.js';
+import { readUsageCache, pollUsage } from './usage.js';
 
 if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true });
 
@@ -184,6 +185,9 @@ function buildActivity(opts = {}) {
   // pushPresence). Fall back to resolving here for any standalone caller.
   const state = opts.resolved || resolvePresence(opts);
 
+  // Subscription usage rides in like liveSessions: injected onto state so
+  // buildVars stays pure. Stale/missing cache → null → usage frames vanish.
+  state.usage = readUsageCache();
   const vars = buildVars(state, config, opts.aggregate || aggregate);
   const p = config.presence || {};
 
@@ -643,6 +647,40 @@ async function runCommunityFlush() {
 }
 const communityFlushMs = Math.max(60_000, (config.community?.flushIntervalMin || 30) * 60 * 1000);
 setInterval(runCommunityFlush, communityFlushMs);
+
+// Subscription-usage poll (feeds {usageWeeklyPct} & friends + `claude-rpc
+// usage`). Only while something is live — no point burning requests against
+// an idle account — and backs off to hourly retries after a bad run, since
+// the endpoint is internal and deserves politeness. pollUsage never throws.
+let usageFailStreak = 0;
+let usageSkipUntil = 0;
+async function runUsagePoll() {
+  if (config.usage?.enabled === false) return;
+  if (Date.now() < usageSkipUntil) return;
+  try {
+    if (!findLiveSessions({ thresholdMs: 30 * 60_000 }).length) return;
+  } catch { /* detection hiccup — poll anyway */ }
+  try {
+    const r = await pollUsage(config);
+    if (r.ok) {
+      usageFailStreak = 0;
+      log(`usage: session ${r.usage.sessionPct}% · week ${r.usage.weeklyPct}%`);
+    } else if (r.reason !== 'disabled') {
+      usageFailStreak += 1;
+      log(`usage: ${r.reason}${r.error ? ' (' + r.error + ')' : ''}`);
+      if (usageFailStreak >= 3) {
+        usageSkipUntil = Date.now() + 60 * 60_000;
+        usageFailStreak = 0;
+      }
+    }
+  } catch (e) {
+    log('usage poll threw:', e.message);
+  }
+}
+const usagePollMs = Math.max(5 * 60_000, (config.usage?.pollIntervalMin || 10) * 60_000);
+setInterval(runUsagePoll, usagePollMs);
+// First poll shortly after startup so the frame doesn't wait a full interval.
+setTimeout(runUsagePoll, 15_000);
 // Initial flush after a short delay — gives the scan above a chance to
 // build aggregate.json before we ask community.js to read it.
 setTimeout(runCommunityFlush, 60_000);

package/src/default-config.js

@@ -104,6 +104,18 @@ export const DEFAULT_CONFIG = {
     endpoint: "https://claude-rpc-totals.claude-rpc.workers.dev",
     flushIntervalMin: 30,
   },
+  // Subscription usage — the numbers Claude Code's own /usage screen shows
+  // (5h session %, weekly %). The daemon reads Claude Code's OAuth token
+  // LOCALLY and asks api.anthropic.com — the token's issuer — for the
+  // utilization; the token and the percentages are never sent anywhere else
+  // and the leaderboard never sees them (SECURITY.md §3d). Feeds the
+  // {usageWeeklyPct}-family template vars and `claude-rpc usage`. Installs
+  // without OAuth credentials (API key / enterprise) simply get no data.
+  // Kill switch: `usage.enabled: false`.
+  usage: {
+    enabled: true,
+    pollIntervalMin: 10,
+  },
   // Public leaderboard / profile (opt-in, off by default). When enabled with a
   // handle, the daemon flush also publishes your display identity + validated
   // usage deltas to the board. Link a GitHub user to earn the verified ✓.
@@ -144,6 +156,9 @@ export const DEFAULT_CONFIG = {
           // Pops in for ~5min when the session crosses an hour milestone, then
           // the `requires` gate drops it and we're back to the single frame.
           { details: "{sessionMilestoneLabel} · {project}", state: "{tokensLabel} · {messagesLabel}", requires: ["sessionMilestoneHit"] },
+          // Subscription usage — only renders while the daemon's usage poll
+          // is fresh (requires drops it otherwise; see the `usage` block).
+          { details: "Usage · {usageWeeklyPct}% weekly",    state: "{usageStateLabel}",               requires: ["usageWeeklyPct", "usageStateLabel"] },
         ],
       },
       thinking: {
@@ -182,6 +197,7 @@ export const DEFAULT_CONFIG = {
           { details: "{allFreshTokensFmt} fresh tokens",       state: "{allCachePctLabel}",                         requires: ["allCachePctLabel"] },
           { details: "Code churn · {linesAddedFmt} added",     state: "{linesNetFmt} net · {topLanguage}",            requires: ["topLanguage"] },
           { details: "Cost · {todayCostFmt} today",            state: "{allCostFmt} all-time",                        requires: ["allCost"] },
+          { details: "Usage · {usageWeeklyPct}% weekly",       state: "{usageStateLabel}",                            requires: ["usageWeeklyPct", "usageStateLabel"] },
           { details: "Daily goal",                             state: "{goalLabel}",                                  requires: ["goalLabel"] },
           { details: "Monthly budget",                         state: "{budgetLabel}",                                requires: ["budgetLabel"] },
         ],

package/src/doctor.js

@@ -16,6 +16,7 @@ import {
 } from './paths.js';
 import { findLiveSessions } from './scanner.js';
 import { resolveVisibility, listPrivateCwds } from './privacy.js';
+import { readClaudeCredentials, readUsageCache } from './usage.js';
 import { c, check as uiCheck } from './ui.js';
 
 const counters = { pass: 0, fail: 0, warn: 0 };
@@ -349,6 +350,30 @@ function checkLiveSessions() {
   }
 }
 
+// Subscription-usage polling (src/usage.js). Three healthy non-pass states
+// exist — disabled, no OAuth credentials, daemon hasn't polled yet — so only
+// the last is a warn; the others are informational.
+function checkUsage(cfg) {
+  if (cfg?.usage?.enabled === false) {
+    check('usage polling', 'info', 'disabled in config (usage.enabled: false)');
+    return;
+  }
+  const creds = readClaudeCredentials();
+  if (!creds) {
+    check('usage polling', 'info',
+      'no Claude Code OAuth credentials — subscription limits unavailable (API-key install?)');
+    return;
+  }
+  const u = readUsageCache();
+  if (u) {
+    check('usage polling', 'pass',
+      `week ${u.weeklyPct}% · session ${u.sessionPct}% · fetched ${Math.max(0, Math.round((Date.now() - u.fetchedAt) / 60_000))} min ago`);
+  } else {
+    check('usage polling', 'warn', 'no fresh usage data yet',
+      'the daemon polls every 10 min while a session is live — or run `claude-rpc usage` for a live fetch');
+  }
+}
+
 function checkDataDir() {
   if (!existsSync(USER_CONFIG_DIR)) {
     check('user config dir', 'warn', `${USER_CONFIG_DIR} missing`,
@@ -389,6 +414,7 @@ export function runDoctor() {
   section('Data');
   checkAggregate();
   checkLiveSessions();
+  checkUsage(cfg);
 
   section('Privacy');
   checkPrivacy(cfg);

package/src/format.js

@@ -3,6 +3,7 @@ import { dayKey, weekKey, DATE_SUFFIX_RE, cleanProjectName } from './scanner.js'
 import { fmtCost } from './pricing.js';
 import { languageOf } from './languages.js';
 import { detectGitBranch, detectGitRepo } from './git.js';
+import { fmtResetTime, fmtResetDay } from './usage.js';
 
 const WEEKDAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
 
@@ -438,6 +439,22 @@ export function buildVars(state, config, aggregate) {
   const filesRead = (state.filesRead || []).length;
   const filesOpened = (state.filesOpened || []).length;
 
+  // ── Subscription usage (state.usage, injected by the caller from
+  // readUsageCache like liveSessions is). All-empty when the daemon hasn't
+  // polled / polling is disabled / the cache went stale, so `requires`-gated
+  // usage frames simply vanish rather than rendering blanks.
+  const usage = state.usage || null;
+  const usageSessionPct = usage?.sessionPct ?? '';
+  const usageWeeklyPct = usage?.weeklyPct ?? '';
+  let usageStateLabel = '';
+  if (usage) {
+    const bits = [];
+    if (usage.sessionPct != null) bits.push(`session ${usage.sessionPct}%`);
+    const day = fmtResetDay(usage.weeklyResetsAt);
+    if (day) bits.push(`resets ${day}`);
+    usageStateLabel = bits.join(' · ');
+  }
+
   return {
     // session — raw
     status: state.status || 'idle',
@@ -471,6 +488,16 @@ export function buildVars(state, config, aggregate) {
     currentFile: state.currentFile || '',
     currentFilePretty,
 
+    // ── Subscription usage (v0.16) — what Claude Code's /usage shows ──
+    usageSessionPct,
+    usageWeeklyPct,
+    usageWeeklyOpusPct: usage?.weeklyOpusPct ?? '',
+    usageWeeklySonnetPct: usage?.weeklySonnetPct ?? '',
+    usageSessionResets: usage ? fmtResetTime(usage.sessionResetsAt) : '',
+    usageWeeklyResets: usage ? fmtResetDay(usage.weeklyResetsAt) : '',
+    usageStateLabel,
+    usagePlan: usage?.plan ? usage.plan.charAt(0).toUpperCase() + usage.plan.slice(1) : '',
+
     // ── File / directory / language (v0.3.6) ────────────────────
     fileName,
     fileExt,

package/src/paths.js

@@ -73,6 +73,9 @@ export const LOG_PATH = join(STATE_DIR, 'daemon.log');
 // Presence snooze marker (`claude-rpc pause`). Lives in the tmp state dir on
 // purpose — a reboot clearing a forgotten pause is the right failure mode.
 export const PAUSE_PATH = join(STATE_DIR, 'pause.json');
+// Subscription-usage cache (see src/usage.js). Volatile by design — stale
+// percentages are worse than none, so a reboot clearing it is correct.
+export const USAGE_CACHE_PATH = join(STATE_DIR, 'usage.json');
 export const DATA_DIR = join(homedir(), '.claude-rpc');
 export const AGGREGATE_PATH = join(DATA_DIR, 'aggregate.json');
 export const SCAN_CACHE_PATH = join(DATA_DIR, 'scan-cache.json');

package/src/usage.js

@@ -0,0 +1,151 @@
+// Subscription usage — the exact numbers Claude Code's /usage screen shows
+// (5-hour session window %, weekly %, per-model weekly buckets).
+//
+// Source: GET https://api.anthropic.com/api/oauth/usage, authenticated with
+// the SAME OAuth access token Claude Code itself uses — read from
+// ~/.claude/.credentials.json (Linux/Windows) or the login keychain (macOS).
+// The token is sent ONLY to api.anthropic.com — its issuer — never logged,
+// never stored anywhere else, never forwarded (SECURITY.md §3d). Strictly
+// read-only: the refresh token is never touched (refresh rotation could
+// corrupt Claude Code's own session), so an expired access token just means
+// "no data until Claude Code next runs".
+//
+// Same contract as community.js: never throws — every failure resolves to
+// { ok: false, reason }. The daemon polls while sessions are live and writes
+// a small cache file; every other surface (CLI, TUI, dashboard, VS Code
+// extension) reads the cache, never the credentials.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { CLAUDE_HOME, USAGE_CACHE_PATH } from './paths.js';
+
+const USAGE_ENDPOINT = 'https://api.anthropic.com/api/oauth/usage';
+// The oauth API requires this beta header — the same one Claude Code sends.
+const OAUTH_BETA = 'oauth-2025-04-20';
+// A dead daemon must not pin hours-old percentages on the card: cache entries
+// older than this read as "no data" and the usage frames/vars vanish.
+export const USAGE_STALE_MS = 30 * 60 * 1000;
+
+// Claude Code's credentials file: { claudeAiOauth: { accessToken, expiresAt,
+// subscriptionType, ... } }. macOS may keep the same JSON in the keychain
+// instead (item "Claude Code-credentials"); reading it can prompt once —
+// degrade silently if denied.
+export function readClaudeCredentials({ home = CLAUDE_HOME } = {}) {
+  try {
+    const p = join(home, '.credentials.json');
+    if (existsSync(p)) {
+      const o = JSON.parse(readFileSync(p, 'utf8'));
+      if (o?.claudeAiOauth?.accessToken) return o.claudeAiOauth;
+    }
+  } catch { /* unreadable → try the keychain below */ }
+  if (process.platform === 'darwin') {
+    try {
+      const r = spawnSync('security', ['find-generic-password', '-s', 'Claude Code-credentials', '-w'],
+        { encoding: 'utf8', timeout: 4000 });
+      if (r.status === 0 && r.stdout) {
+        const o = JSON.parse(r.stdout.trim());
+        if (o?.claudeAiOauth?.accessToken) return o.claudeAiOauth;
+      }
+    } catch { /* keychain locked or denied → no credentials */ }
+  }
+  return null;
+}
+
+// Normalize the API response to the few fields we surface. Percentages round
+// to integers; absent buckets (e.g. seven_day_opus outside Max plans) → null.
+// Unknown fields are deliberately ignored — the endpoint is internal and
+// carries experimental buckets that come and go between releases.
+export function normalizeUsage(json) {
+  const bucket = (b) => (b && Number.isFinite(Number(b.utilization)))
+    ? { pct: Math.round(Number(b.utilization)), resetsAt: b.resets_at || null }
+    : null;
+  const session = bucket(json?.five_hour);
+  const week = bucket(json?.seven_day);
+  if (!session && !week) return null;
+  return {
+    sessionPct:      session?.pct ?? null,
+    sessionResetsAt: session?.resetsAt ?? null,
+    weeklyPct:       week?.pct ?? null,
+    weeklyResetsAt:  week?.resetsAt ?? null,
+    weeklyOpusPct:   bucket(json?.seven_day_opus)?.pct ?? null,
+    weeklySonnetPct: bucket(json?.seven_day_sonnet)?.pct ?? null,
+  };
+}
+
+export async function fetchUsage({ fetchImpl = globalThis.fetch, creds = readClaudeCredentials(), now = Date.now() } = {}) {
+  if (!creds?.accessToken) return { ok: false, reason: 'no-credentials' };
+  if (creds.expiresAt && now > creds.expiresAt) return { ok: false, reason: 'token-expired' };
+  let res;
+  try {
+    res = await fetchImpl(USAGE_ENDPOINT, {
+      headers: {
+        Authorization: `Bearer ${creds.accessToken}`,
+        'anthropic-beta': OAUTH_BETA,
+        'Content-Type': 'application/json',
+      },
+      signal: AbortSignal.timeout(10_000),
+    });
+  } catch (e) {
+    return { ok: false, reason: 'network', error: e.message };
+  }
+  if (res.status === 401 || res.status === 403) return { ok: false, reason: 'unauthorized' };
+  if (!res.ok) return { ok: false, reason: `http-${res.status}` };
+  let json;
+  try { json = await res.json(); } catch { return { ok: false, reason: 'bad-json' }; }
+  const usage = normalizeUsage(json);
+  if (!usage) return { ok: false, reason: 'no-buckets' };
+  usage.plan = typeof creds.subscriptionType === 'string' ? creds.subscriptionType : null;
+  usage.fetchedAt = now;
+  return { ok: true, usage };
+}
+
+export function writeUsageCache(usage, path = USAGE_CACHE_PATH) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(usage, null, 2));
+  } catch { /* cache is best-effort — next poll retries */ }
+}
+
+// Fresh cache or null — staleness collapses to "no data" so consumers need
+// no freshness logic of their own.
+export function readUsageCache({ path = USAGE_CACHE_PATH, maxAgeMs = USAGE_STALE_MS, now = Date.now() } = {}) {
+  try {
+    const u = JSON.parse(readFileSync(path, 'utf8'));
+    if (!u?.fetchedAt || now - u.fetchedAt > maxAgeMs) return null;
+    return u;
+  } catch { return null; }
+}
+
+// Daemon-facing one-shot: config gate → fetch → cache. Never throws.
+export async function pollUsage(config, { fetchImpl } = {}) {
+  if (config?.usage?.enabled === false) return { ok: false, reason: 'disabled' };
+  const r = await fetchUsage(fetchImpl ? { fetchImpl } : {});
+  if (r.ok) writeUsageCache(r.usage);
+  return r;
+}
+
+// ── Display formatting (shared by template vars and the CLI view) ────────
+
+// "6pm" / "6:30pm" local — how the 5-hour window reset reads on a card.
+export function fmtResetTime(iso) {
+  const d = new Date(iso || NaN);
+  if (isNaN(d)) return '';
+  let h = d.getHours();
+  const m = d.getMinutes();
+  const ap = h >= 12 ? 'pm' : 'am';
+  h = h % 12 || 12;
+  return m ? `${h}:${String(m).padStart(2, '0')}${ap}` : `${h}${ap}`;
+}
+
+// "today" / "tomorrow" / "Tue" — how the weekly reset reads.
+export function fmtResetDay(iso, now = new Date()) {
+  const d = new Date(iso || NaN);
+  if (isNaN(d)) return '';
+  const today = new Date(now); today.setHours(0, 0, 0, 0);
+  const that = new Date(d); that.setHours(0, 0, 0, 0);
+  const diff = Math.round((that - today) / 86_400_000);
+  if (diff <= 0) return 'today';
+  if (diff === 1) return 'tomorrow';
+  return ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'][d.getDay()];
+}

package/src/version.js

@@ -11,7 +11,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ROOT } from './paths.js';
 
-const BAKED = '0.15.5';
+const BAKED = '0.16.0';
 
 function readPkgVersion() {
   try {