menubar: real Plan Usage via OAuth usage endpoint; cut Token Stats from V0

daemon grows fetchPlanUsage(): OAuthRefreshManager.ensureFresh() →
GET /api/oauth/usage (beta header oauth-2025-04-20) → parsed window
percentages. Closed result union (ok / signed_out / error), single-
flight + 30s TTL inside — the token never leaves the daemon. Live-
verified against a real account, which falsified the research notes:
`utilization` is a 0..100 percentage (71 = 71%), NOT a 0..1 fraction,
and per-model windows can be entirely absent (opus missing while
sonnet present) — absent windows are skipped, never rendered as 0%.

menubar: mock Plan Usage replaced with the daemon fetch (refresh on
tray click + startup; last-good kept through transient errors;
signed_out renders a "run claude /login" row). Token Stats section
CUT: its planned source (stats-cache.json) turned out to be lazily
written — only when the user runs /stats — so honest numbers need
Desktop-style JSONL aggregation; deferred past V0.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: yyq1025

packages/daemon/src/index.ts

@@ -18,6 +18,7 @@ import { KnownClients } from "./known-clients.js";
 import { foldEventDelta } from "./messages/fold.js";
 import { extractLatestUsage, normalize } from "./messages/normalize.js";
 import { createPairOffer } from "./pairing.js";
+import { createPlanUsageFetcher, type PlanUsageResult } from "./plan-usage.js";
 import { createCommandHandler } from "./router.js";
 import { ensureSessionLoop, pushPrompt } from "./runtime/run-query.js";
 import { SessionRuntimeManager } from "./runtime/session-runtime-manager.js";
@@ -36,6 +37,12 @@ export interface DaemonOptions {
   signalingScheme?: "ws" | "wss";
 }
 
+export type {
+  PlanUsage,
+  PlanUsageResult,
+  PlanUsageWindow,
+} from "./plan-usage.js";
+
 export interface Daemon {
   stop(): Promise<void>;
   /** Identity fingerprint, for status / pair display. */
@@ -76,6 +83,14 @@ export interface Daemon {
    * normal operation until a session is bridged.
    */
   readonly bridgeService: BridgeService;
+  /**
+   * Plan-utilization snapshot for the menubar's "Claude Plan Usage" rows
+   * (5h / weekly / per-model % + reset times). Never throws — returns a
+   * closed result union (`ok` / `signed_out` / `error`); single-flight +
+   * 30s cache inside, so call freely on every tray click. The OAuth token
+   * stays inside the daemon; callers get parsed numbers only.
+   */
+  fetchPlanUsage(): Promise<PlanUsageResult>;
 }
 
 export async function start(options: DaemonOptions = {}): Promise<Daemon> {
@@ -404,6 +419,7 @@ export async function start(options: DaemonOptions = {}): Promise<Daemon> {
     fingerprint: identity.fingerprint,
     pairedClientCount: () => knownClients.list().length,
     authenticatedPeerCount: () => webrtc.authenticatedCount(),
+    fetchPlanUsage: createPlanUsageFetcher(oauth),
     createPairOffer: (serviceName) => {
       const { encoded } = createPairOffer(identity, serviceName);
       return { encoded };

packages/daemon/src/plan-usage.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it, vi } from "vitest";
+import { OAuthRefreshError } from "./bridge/oauth-refresh.js";
+import { createPlanUsageFetcher, parsePlanUsage } from "./plan-usage.js";
+
+// createPlanUsageFetcher only calls `ensureFresh()` on the manager — a
+// stub with that one method is a faithful stand-in.
+function oauthStub(impl: () => Promise<string>) {
+  return { ensureFresh: impl } as unknown as Parameters<
+    typeof createPlanUsageFetcher
+  >[0];
+}
+
+function okResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+// Values are 0..100 percentages, matching the live endpoint (71 = 71%).
+const FULL_BODY = {
+  five_hour: { utilization: 91, resets_at: "2026-06-11T09:00:00Z" },
+  seven_day: { utilization: 99, resets_at: "2026-06-15T00:00:00Z" },
+  seven_day_opus: { utilization: 45 },
+  seven_day_sonnet: { utilization: 12, resets_at: "2026-06-15T00:00:00Z" },
+  // Unknown windows must be ignored, not break parsing.
+  seven_day_design: { utilization: 50 },
+};
+
+describe("parsePlanUsage", () => {
+  it("maps the documented window keys and passes fetchedAt through", () => {
+    const usage = parsePlanUsage(FULL_BODY, 1234);
+    expect(usage.fiveHour).toEqual({
+      utilization: 91,
+      resetsAt: "2026-06-11T09:00:00Z",
+    });
+    expect(usage.sevenDay?.utilization).toBe(99);
+    expect(usage.sevenDayOpus).toEqual({
+      utilization: 45,
+      resetsAt: undefined,
+    });
+    expect(usage.sevenDaySonnet?.utilization).toBe(12);
+    expect(usage.fetchedAt).toBe(1234);
+  });
+
+  it("treats absent / malformed windows as unavailable, never 0%", () => {
+    // Enterprise/org accounts return partial or null windows.
+    const usage = parsePlanUsage(
+      { five_hour: null, seven_day: { utilization: "0.5" } },
+      0,
+    );
+    expect(usage.fiveHour).toBeUndefined();
+    expect(usage.sevenDay).toBeUndefined();
+  });
+
+  it("survives a non-object body", () => {
+    expect(parsePlanUsage(null, 0).fiveHour).toBeUndefined();
+    expect(parsePlanUsage("nope", 0).fiveHour).toBeUndefined();
+  });
+});
+
+describe("createPlanUsageFetcher", () => {
+  it("ok path: fetches with bearer + beta header, returns parsed usage", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(okResponse(FULL_BODY));
+    const fetcher = createPlanUsageFetcher(
+      oauthStub(() => Promise.resolve("tok-123")),
+      { fetchImpl: fetchImpl as unknown as typeof fetch, now: () => 1000 },
+    );
+    const result = await fetcher();
+    if (result.status !== "ok") throw new Error(`got ${result.status}`);
+    expect(result.usage.fiveHour?.utilization).toBe(91);
+    const [url, init] = fetchImpl.mock.calls[0];
+    expect(url).toContain("/api/oauth/usage");
+    expect(init.headers.Authorization).toBe("Bearer tok-123");
+    expect(init.headers["anthropic-beta"]).toBe("oauth-2025-04-20");
+  });
+
+  it("serves from cache within the TTL (no second hit)", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(okResponse(FULL_BODY));
+    let t = 1000;
+    const fetcher = createPlanUsageFetcher(
+      oauthStub(() => Promise.resolve("tok")),
+      { fetchImpl: fetchImpl as unknown as typeof fetch, now: () => t },
+    );
+    await fetcher();
+    t += 10_000; // inside the 30s TTL
+    await fetcher();
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    t += 60_000; // past the TTL
+    fetchImpl.mockResolvedValue(okResponse(FULL_BODY));
+    await fetcher();
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+  });
+
+  it("no_credentials / needs_relogin → signed_out", async () => {
+    for (const kind of ["no_credentials", "needs_relogin"] as const) {
+      const fetcher = createPlanUsageFetcher(
+        oauthStub(() => Promise.reject(new OAuthRefreshError(kind, kind))),
+        { fetchImpl: vi.fn() as unknown as typeof fetch },
+      );
+      expect((await fetcher()).status).toBe("signed_out");
+    }
+  });
+
+  it("network refresh error → error (retryable), not signed_out", async () => {
+    const fetcher = createPlanUsageFetcher(
+      oauthStub(() => Promise.reject(new OAuthRefreshError("network", "boom"))),
+      { fetchImpl: vi.fn() as unknown as typeof fetch },
+    );
+    expect((await fetcher()).status).toBe("error");
+  });
+
+  it("endpoint 401 → signed_out; other non-2xx → error", async () => {
+    const mk = (status: number) =>
+      createPlanUsageFetcher(
+        oauthStub(() => Promise.resolve("tok")),
+        {
+          fetchImpl: vi
+            .fn()
+            .mockResolvedValue(
+              new Response("{}", { status }),
+            ) as unknown as typeof fetch,
+        },
+      );
+    expect((await mk(401)()).status).toBe("signed_out");
+    expect((await mk(429)()).status).toBe("error");
+    expect((await mk(500)()).status).toBe("error");
+  });
+
+  it("concurrent calls share one in-flight request", async () => {
+    let resolveFetch: (r: Response) => void = () => {};
+    const fetchImpl = vi.fn().mockReturnValue(
+      new Promise<Response>((resolve) => {
+        resolveFetch = resolve;
+      }),
+    );
+    const fetcher = createPlanUsageFetcher(
+      oauthStub(() => Promise.resolve("tok")),
+      { fetchImpl: fetchImpl as unknown as typeof fetch },
+    );
+    const [a, b] = [fetcher(), fetcher()];
+    resolveFetch(okResponse(FULL_BODY));
+    const [ra, rb] = await Promise.all([a, b]);
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    expect(ra.status).toBe("ok");
+    expect(rb.status).toBe("ok");
+  });
+});

packages/daemon/src/plan-usage.ts

@@ -0,0 +1,170 @@
+/**
+ * Plan-utilization fetcher for the menubar's "Claude Plan Usage" section.
+ *
+ * Data source: `GET https://api.anthropic.com/api/oauth/usage` — the same
+ * undocumented-but-de-facto-stable endpoint Claude Code's own `/status`
+ * command (and CodexBar / ccusage / claude-monitor) read. It reports
+ * QUOTA UTILIZATION (what % of the 5h / weekly windows is consumed right
+ * now + reset times) — a different metric from cumulative token stats.
+ *
+ * Auth rides the existing OAuthRefreshManager: `ensureFresh()` yields the
+ * keychain access token (refreshing if needed), so this module never
+ * touches credential storage itself and the token never crosses the
+ * daemon boundary — the menubar gets parsed numbers, not a Bearer.
+ *
+ * Failure surface is a closed result union (never throws): the menu
+ * renders each state directly — `signed_out` → "run claude /login" row,
+ * `error` → keep last-good / show unavailable.
+ */
+import {
+  OAuthRefreshError,
+  type OAuthRefreshManager,
+} from "./bridge/oauth-refresh.js";
+
+const USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+// REQUIRED beta cohort header — without it the endpoint 4xxes. Anthropic
+// has rolled the value at least once (claude-code#13770); if calls start
+// failing with 4xx, check the current claude-code CLI source for the
+// live value.
+const ANTHROPIC_BETA = "oauth-2025-04-20";
+// Client identity matching the bundled SDK's CLI lineage (2.1.x). Not
+// enforced today; third-party readers all send it as defensive cover.
+const USER_AGENT = "claude-code/2.1.170";
+
+// The endpoint is rate-limited (claude-code#31021) and the menu can be
+// flapped open repeatedly — serve from cache within this window.
+const CACHE_TTL_MS = 30_000;
+
+/** One rate window (5h / 7d / per-model). Absent upstream fields stay
+ *  undefined — enterprise/org accounts return partial data; treat as
+ *  "unavailable", never as 0%. */
+export interface PlanUsageWindow {
+  /** Percentage of the window's quota consumed, 0..100 — passed through
+   *  as the endpoint returns it (verified live 2026-06-11: `71`, not
+   *  `0.71`). Render with `Math.round(x)%`, never multiply by 100. */
+  utilization: number;
+  /** ISO-8601 next reset, when the endpoint provides it. */
+  resetsAt?: string;
+}
+
+export interface PlanUsage {
+  fiveHour?: PlanUsageWindow;
+  sevenDay?: PlanUsageWindow;
+  sevenDayOpus?: PlanUsageWindow;
+  sevenDaySonnet?: PlanUsageWindow;
+  /** Epoch ms when this snapshot was fetched (drives menu staleness). */
+  fetchedAt: number;
+}
+
+export type PlanUsageResult =
+  /** Fresh (or ≤TTL-cached) snapshot. */
+  | { status: "ok"; usage: PlanUsage }
+  /** No usable credentials — user needs `claude /login` on this Mac. */
+  | { status: "signed_out" }
+  /** Transient failure (network / 403 / 429 / 5xx). Caller decides
+   *  whether to keep showing a previous snapshot. */
+  | { status: "error"; message: string };
+
+/** Parse the endpoint's response body. Exported for tests. */
+export function parsePlanUsage(body: unknown, fetchedAt: number): PlanUsage {
+  const root = (body ?? {}) as Record<string, unknown>;
+  const window = (key: string): PlanUsageWindow | undefined => {
+    const w = root[key] as Record<string, unknown> | undefined;
+    if (w == null || typeof w.utilization !== "number") return undefined;
+    return {
+      utilization: w.utilization,
+      resetsAt: typeof w.resets_at === "string" ? w.resets_at : undefined,
+    };
+  };
+  return {
+    fiveHour: window("five_hour"),
+    sevenDay: window("seven_day"),
+    sevenDayOpus: window("seven_day_opus"),
+    sevenDaySonnet: window("seven_day_sonnet"),
+    fetchedAt,
+  };
+}
+
+export interface PlanUsageFetcherOptions {
+  /** `fetch` impl (test seam). Default = global fetch. */
+  fetchImpl?: typeof fetch;
+  /** Clock (test seam). Default = Date.now. */
+  now?: () => number;
+}
+
+/**
+ * Build the daemon-surface `fetchPlanUsage()` closure. Single-flight +
+ * TTL cache: concurrent menu opens share one request, and repeat opens
+ * within the TTL don't hit the endpoint at all.
+ */
+export function createPlanUsageFetcher(
+  oauth: OAuthRefreshManager,
+  options: PlanUsageFetcherOptions = {},
+): () => Promise<PlanUsageResult> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const now = options.now ?? Date.now;
+
+  let lastOk: PlanUsage | null = null;
+  let inFlight: Promise<PlanUsageResult> | null = null;
+
+  const fetchOnce = async (): Promise<PlanUsageResult> => {
+    let token: string;
+    try {
+      token = await oauth.ensureFresh();
+    } catch (err) {
+      if (err instanceof OAuthRefreshError && err.kind !== "network") {
+        return { status: "signed_out" };
+      }
+      return {
+        status: "error",
+        message: err instanceof Error ? err.message : String(err),
+      };
+    }
+
+    let res: Response;
+    try {
+      res = await fetchImpl(USAGE_URL, {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "anthropic-beta": ANTHROPIC_BETA,
+          "User-Agent": USER_AGENT,
+          Accept: "application/json",
+        },
+      });
+    } catch (err) {
+      return {
+        status: "error",
+        message: err instanceof Error ? err.message : String(err),
+      };
+    }
+
+    // 401 = the token itself is rejected (ensureFresh thought it was fine
+    // but the server disagrees) — actionable by re-login, same as having
+    // no credentials.
+    if (res.status === 401) return { status: "signed_out" };
+    if (!res.ok) {
+      return { status: "error", message: `usage endpoint HTTP ${res.status}` };
+    }
+
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      return { status: "error", message: "usage endpoint returned non-JSON" };
+    }
+    const usage = parsePlanUsage(body, now());
+    lastOk = usage;
+    return { status: "ok", usage };
+  };
+
+  return () => {
+    if (lastOk && now() - lastOk.fetchedAt < CACHE_TTL_MS) {
+      return Promise.resolve({ status: "ok", usage: lastOk });
+    }
+    if (inFlight) return inFlight;
+    inFlight = fetchOnce().finally(() => {
+      inFlight = null;
+    });
+    return inFlight;
+  };
+}