@kill-switch/agent-guard 0.1.6 → 0.1.7

package/README.md

@@ -115,8 +115,33 @@ scarce resource isn't dollars — it's your plan's rate-limit quota, in two roll
 - a **5-hour** window (burst protection), and
 - a **weekly** (7-day) window — the real lockout risk, "resets a couple times a month".
 
-Anthropic reports exactly where you stand on every response via `anthropic-ratelimit-unified-*`
-headers. Run Claude Code **through the proxy** and agent-guard reads them — no estimation:
+### Easiest: `agent-guard usage`
+
+Pull your **real** limits straight from Anthropic — the same data `/usage` shows — no proxy, no
+workflow change:
+
+```sh
+agent-guard usage     # → 5-hour, weekly, and per-model (Sonnet/Opus) weekly utilization + resets
+```
+
+It reads your Claude Code OAuth token from the OS credential store (macOS Keychain
+`Claude Code-credentials`, or `~/.claude/.credentials.json` on Linux — used only as a Bearer
+header, **never logged or stored**) and GETs the `/api/oauth/usage` endpoint. `status`
+auto-refreshes this (throttled to 120s). The endpoint is **undocumented**, so every call fails
+soft — if it's unavailable, agent-guard falls back to the proxy or "unknown".
+
+```
+🟢 Claude Code plan limits  ·  observed just now
+  [██░░░░░░░░░░░░░░░░░░]  5-hour limit 12% used, resets 9:19 AM
+  [███░░░░░░░░░░░░░░░░░]  weekly limit 17% used, resets Tue 7:59 PM
+  [░░░░░░░░░░░░░░░░░░░░]  weekly · Sonnet   1%
+```
+
+### Alternative: the proxy
+
+Anthropic also reports your standing on every response via `anthropic-ratelimit-unified-*`
+headers (5h + weekly only — no per-model). Run Claude Code **through the proxy** and agent-guard
+reads them in-flight:
 
 ```sh
 agent-guard proxy                                    # meters Anthropic + reads limit headers

package/dist/claude-usage.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Real subscription usage from Anthropic's OAuth usage endpoint.
+ *
+ * This is the authoritative, structured source for Claude Code Pro/Max limits —
+ * the same data the `/usage` command shows — without a proxy, a screen-scrape, or
+ * a (hopeless) local estimate. It's the endpoint the polished community status-
+ * line tools settled on. One caveat: it's **undocumented**, so Anthropic could
+ * change or gate it; every call here fails soft (returns null) and the caller
+ * falls back to the proxy / "unknown".
+ *
+ * Token handling: the OAuth access token is read from the OS credential store
+ * (macOS Keychain `Claude Code-credentials`, or `~/.claude/.credentials.json` on
+ * Linux), used only as a Bearer header on the GET, and **never logged or
+ * persisted** by us.
+ */
+import { type LimitSnapshot } from "./limits.js";
+/**
+ * Best-effort read of the Claude Code OAuth access token from the OS credential
+ * store. Returns null (never throws, never logs the token) if unavailable.
+ */
+export declare function readOAuthToken(): string | null;
+interface UsageWindow {
+    utilization?: number | null;
+    resets_at?: string | null;
+}
+export interface UsageResponse {
+    five_hour?: UsageWindow | null;
+    seven_day?: UsageWindow | null;
+    seven_day_sonnet?: UsageWindow | null;
+    seven_day_opus?: UsageWindow | null;
+    extra_usage?: {
+        is_enabled?: boolean;
+        monthly_limit?: number;
+        used_credits?: number;
+    } | null;
+}
+/** GET the usage endpoint with the given token. Returns null on any failure. */
+export declare function fetchUsage(token: string, timeoutMs?: number): Promise<UsageResponse | null>;
+/** Map the OAuth usage response into a {@link LimitSnapshot}. */
+export declare function usageToSnapshot(u: UsageResponse, now: number): LimitSnapshot;
+/**
+ * Fetch real usage and persist it as the live snapshot, throttled. Returns the
+ * fresh snapshot on a successful fetch, or null if we skipped (throttled) or
+ * couldn't fetch (no token / endpoint down — caller falls back gracefully).
+ */
+export declare function refreshUsage(now: number, opts?: {
+    force?: boolean;
+    throttleMs?: number;
+}): Promise<LimitSnapshot | null>;
+export {};

package/dist/claude-usage.js

@@ -0,0 +1,131 @@
+/**
+ * Real subscription usage from Anthropic's OAuth usage endpoint.
+ *
+ * This is the authoritative, structured source for Claude Code Pro/Max limits —
+ * the same data the `/usage` command shows — without a proxy, a screen-scrape, or
+ * a (hopeless) local estimate. It's the endpoint the polished community status-
+ * line tools settled on. One caveat: it's **undocumented**, so Anthropic could
+ * change or gate it; every call here fails soft (returns null) and the caller
+ * falls back to the proxy / "unknown".
+ *
+ * Token handling: the OAuth access token is read from the OS credential store
+ * (macOS Keychain `Claude Code-credentials`, or `~/.claude/.credentials.json` on
+ * Linux), used only as a Bearer header on the GET, and **never logged or
+ * persisted** by us.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import { loadLimitsState, saveLimitsState, parseReset, } from "./limits.js";
+const USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+const OAUTH_BETA = "oauth-2025-04-20";
+const DEFAULT_THROTTLE_MS = 120_000; // don't hammer the endpoint
+/**
+ * Best-effort read of the Claude Code OAuth access token from the OS credential
+ * store. Returns null (never throws, never logs the token) if unavailable.
+ */
+export function readOAuthToken() {
+    try {
+        let raw;
+        if (platform() === "darwin") {
+            raw = execFileSync("security", ["find-generic-password", "-s", "Claude Code-credentials", "-w"], {
+                encoding: "utf8",
+                timeout: 4000,
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+        }
+        else {
+            raw = readFileSync(join(homedir(), ".claude", ".credentials.json"), "utf8");
+        }
+        const j = JSON.parse(raw);
+        return j?.claudeAiOauth?.accessToken ?? j?.accessToken ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** GET the usage endpoint with the given token. Returns null on any failure. */
+export async function fetchUsage(token, timeoutMs = 8000) {
+    try {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), timeoutMs);
+        let res;
+        try {
+            res = await fetch(USAGE_URL, {
+                headers: {
+                    authorization: `Bearer ${token}`,
+                    "anthropic-beta": OAUTH_BETA,
+                    "content-type": "application/json",
+                },
+                signal: ctrl.signal,
+            });
+        }
+        finally {
+            clearTimeout(t);
+        }
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Convert one endpoint window to a {@link WindowState}. The endpoint's
+ * `utilization` is an integer **percent** (0–100) — including small values like
+ * 1 (= 1%), so we always divide by 100 (NOT the header parser's ambiguous
+ * >1.5 heuristic, which would read 1 as 100%).
+ */
+function toWindow(u, now) {
+    if (!u || typeof u.utilization !== "number")
+        return null;
+    return {
+        utilization: Math.max(0, Math.min(1, u.utilization / 100)),
+        resetAt: parseReset(u.resets_at ?? null, now),
+    };
+}
+/** Map the OAuth usage response into a {@link LimitSnapshot}. */
+export function usageToSnapshot(u, now) {
+    const extras = [];
+    const addExtra = (label, w) => {
+        const s = toWindow(w, now);
+        if (s)
+            extras.push({ label, utilization: s.utilization, resetAt: s.resetAt });
+    };
+    addExtra("weekly · Sonnet", u.seven_day_sonnet);
+    addExtra("weekly · Opus", u.seven_day_opus);
+    return {
+        fiveHour: toWindow(u.five_hour, now),
+        weekly: toWindow(u.seven_day, now),
+        status: "oauth-usage",
+        observedAt: now,
+        extras: extras.length ? extras : undefined,
+    };
+}
+/**
+ * Fetch real usage and persist it as the live snapshot, throttled. Returns the
+ * fresh snapshot on a successful fetch, or null if we skipped (throttled) or
+ * couldn't fetch (no token / endpoint down — caller falls back gracefully).
+ */
+export async function refreshUsage(now, opts = {}) {
+    const throttle = opts.throttleMs ?? DEFAULT_THROTTLE_MS;
+    const state = loadLimitsState();
+    if (!opts.force && state.lastFetchAt && now - state.lastFetchAt < throttle && state.snapshot) {
+        return null; // recent enough — use the cached snapshot
+    }
+    const token = readOAuthToken();
+    if (!token)
+        return null;
+    const usage = await fetchUsage(token);
+    if (!usage) {
+        // mark the attempt so we don't retry every call when the endpoint is down
+        saveLimitsState({ ...loadLimitsState(), lastFetchAt: now });
+        return null;
+    }
+    const snapshot = usageToSnapshot(usage, now);
+    const fresh = loadLimitsState();
+    saveLimitsState({ ...fresh, subscriptionDetected: true, snapshot, lastFetchAt: now });
+    return snapshot;
+}

package/dist/cli.js

@@ -19,6 +19,7 @@ import { evaluate } from "./budget.js";
 import { fmtUSD } from "./cost.js";
 import { installHook, setBudget, setLimits, resetLedger } from "./ops.js";
 import { buildStatusReport, formatLimitsLines } from "./report.js";
+import { refreshUsage } from "./claude-usage.js";
 const program = new Command();
 program
     .name("agent-guard")
@@ -59,9 +60,15 @@ program
 // ── status ───────────────────────────────────────────────────────────────────
 program
     .command("status")
-    .description("Show current session + daily spend against the budget")
+    .description("Show current session + daily spend, and real Claude Code plan limits")
     .option("--json", "Output as JSON")
-    .action((opts) => {
+    .action(async (opts) => {
+    try {
+        await refreshUsage(Date.now()); // throttled real-limits pull; never fails status
+    }
+    catch {
+        /* offline / no token */
+    }
     const cfg = loadConfig();
     const ledger = loadLedger();
     const now = Date.now();
@@ -119,6 +126,34 @@ program
             console.log(line);
     }
 });
+// ── usage (real Claude Code plan limits) ─────────────────────────────────────
+program
+    .command("usage")
+    .description("Fetch your REAL Claude Code plan limits (5h + weekly + per-model) from Anthropic")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    let snap;
+    try {
+        snap = await refreshUsage(Date.now(), { force: true });
+    }
+    catch {
+        snap = null;
+    }
+    const report = buildStatusReport();
+    if (opts.json) {
+        console.log(JSON.stringify({ fetched: !!snap, limits: report.limits }, null, 2));
+        return;
+    }
+    if (!snap && report.limits.source !== "headers") {
+        console.log("Couldn't fetch usage — need a logged-in Claude Code (token in the macOS Keychain or ~/.claude/.credentials.json).");
+        console.log("The /api/oauth/usage endpoint is undocumented and may be unavailable.");
+        return;
+    }
+    console.log("");
+    for (const line of formatLimitsLines(report.limits))
+        console.log(line);
+    console.log("");
+});
 // ── pause / resume (escape hatch) ────────────────────────────────────────────
 program
     .command("pause")

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export { startProxy, resolveUpstream, type ProxyOptions } from "./proxy.js";
 export { runHook } from "./hook.js";
 export { buildStatusReport, buildLimitsReport, formatLimitsLines, type StatusReport, type LimitsReport } from "./report.js";
 export { detectPlanTier, mapRateLimitTier, tierLabel, type SubscriptionTier } from "./claude-code.js";
-export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, unifiedHeaderDump, logUnifiedHeaders, WINDOW_MS, type LimitSnapshot, type WindowState, type LimitsState, type LimitWindow, type HeaderGetter, } from "./limits.js";
+export { readOAuthToken, fetchUsage, usageToSnapshot, refreshUsage, type UsageResponse } from "./claude-usage.js";
+export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, unifiedHeaderDump, logUnifiedHeaders, WINDOW_MS, type LimitSnapshot, type WindowState, type ExtraWindow, type LimitsState, type LimitWindow, type HeaderGetter, } from "./limits.js";
 export { assessWindow, assessSnapshot, worstLevel, type PacingAssessment, type PacingLevel, type PacingThresholds, } from "./pacing.js";
 export { installHook, setBudget, setLimits, resetLedger, type InstallOptions, type InstallResult, type BudgetPatch, type LimitsPatch, } from "./ops.js";

package/dist/index.js

@@ -18,6 +18,7 @@ export { startProxy, resolveUpstream } from "./proxy.js";
 export { runHook } from "./hook.js";
 export { buildStatusReport, buildLimitsReport, formatLimitsLines } from "./report.js";
 export { detectPlanTier, mapRateLimitTier, tierLabel } from "./claude-code.js";
+export { readOAuthToken, fetchUsage, usageToSnapshot, refreshUsage } from "./claude-usage.js";
 export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, unifiedHeaderDump, logUnifiedHeaders, WINDOW_MS, } from "./limits.js";
 export { assessWindow, assessSnapshot, worstLevel, } from "./pacing.js";
 export { installHook, setBudget, setLimits, resetLedger, } from "./ops.js";

package/dist/limits.d.ts

@@ -32,6 +32,12 @@ export interface WindowState {
     /** Raw per-window status string from Anthropic (e.g. "allowed" / "warning"), if any. */
     status?: string;
 }
+/** A labelled extra window (e.g. per-model weekly) — display-only, no pacing. */
+export interface ExtraWindow {
+    label: string;
+    utilization: number;
+    resetAt: number | null;
+}
 /** A point-in-time read of the account's subscription rate-limit standing. */
 export interface LimitSnapshot {
     fiveHour: WindowState | null;
@@ -40,6 +46,8 @@ export interface LimitSnapshot {
     status: string | null;
     /** Epoch ms when this snapshot was observed. */
     observedAt: number;
+    /** Extra windows from the OAuth usage endpoint (per-model weekly, etc.) — display only. */
+    extras?: ExtraWindow[];
 }
 /** Persisted global state (account-wide, not per-session). */
 export interface LimitsState {
@@ -51,6 +59,8 @@ export interface LimitsState {
     notified: Record<string, boolean>;
     /** Epoch ms we first logged the raw unified-* headers (write-once diagnostic). */
     headersLoggedAt?: number;
+    /** Epoch ms of the last OAuth usage-endpoint fetch (for throttling). */
+    lastFetchAt?: number;
 }
 /** Nominal window durations, used for pacing math when a reset time is unknown. */
 export declare const WINDOW_MS: Record<LimitWindow, number>;

package/dist/limits.js

@@ -42,6 +42,7 @@ export function loadLimitsState() {
                 snapshot: data.snapshot ?? null,
                 notified: data.notified ?? {},
                 headersLoggedAt: data.headersLoggedAt,
+                lastFetchAt: data.lastFetchAt,
             };
         }
     }

package/dist/report.d.ts

@@ -14,6 +14,7 @@
 import { type GuardConfig } from "./config.js";
 import { type SessionRecord, type Ledger } from "./ledger.js";
 import { type Budget, type VerdictLevel } from "./budget.js";
+import { type ExtraWindow } from "./limits.js";
 import { type PacingAssessment, type PacingLevel } from "./pacing.js";
 import { type SubscriptionTier } from "./claude-code.js";
 export interface LimitsReport {
@@ -30,6 +31,8 @@ export interface LimitsReport {
     observedAt: number | null;
     /** Real per-window pacing (only when source === "headers"). */
     windows: PacingAssessment[];
+    /** Extra display-only windows (per-model weekly) from the OAuth usage endpoint. */
+    extras: ExtraWindow[];
     level: PacingLevel;
     /** Absolute rolling cost (API-equivalent USD) — honest local signal, not a limit %. */
     cost: {

package/dist/report.js

@@ -65,6 +65,7 @@ export function buildLimitsReport(cfg, ledger, now) {
                 subscriptionDetected: state.subscriptionDetected,
                 observedAt: snap.observedAt,
                 windows,
+                extras: snap.extras ?? [],
                 level: worstLevel(windows),
                 cost,
             };
@@ -79,6 +80,7 @@ export function buildLimitsReport(cfg, ledger, now) {
         subscriptionDetected: state.subscriptionDetected,
         observedAt: null,
         windows: [],
+        extras: [],
         level: "ok",
         cost,
     };
@@ -109,6 +111,10 @@ export function formatLimitsLines(limits, now = Date.now()) {
         const lines = [`${icon} Claude Code plan limits  ·  observed ${limits.observedAt ? ageString(limits.observedAt, now) : "—"}`];
         for (const w of limits.windows)
             lines.push(`  ${bar(w.utilization)}  ${w.message}`);
+        for (const e of limits.extras) {
+            const pct = `${Math.round(e.utilization * 100)}%`.padStart(4);
+            lines.push(`  ${bar(e.utilization)}  ${e.label} ${pct}`);
+        }
         return lines;
     }
     // No live data: show what's honestly knowable — the tier and absolute cost,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kill-switch/agent-guard",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Kill Switch for coding agents — stop runaway Claude Code / Cursor / Aider sessions from racking up an LLM bill. Native hook + token-metering proxy with per-session and daily-rolling budgets.",
   "type": "module",
   "bin": {