pi-usage-limits 0.1.1

package/README.md

@@ -0,0 +1,68 @@
+# pi-usage-limits
+
+[![npm](https://img.shields.io/npm/v/pi-usage-limits)](https://www.npmjs.com/package/pi-usage-limits)
+
+A [pi](https://github.com/earendil-works/pi) extension that shows your **Claude** and **Codex** subscription limits in pi's status line and updates them after every prompt.
+
+```
+5h: 12%, 7d: 25%
+```
+
+## Why use it
+
+- **Works with Claude through the Claude Agent SDK.** It reads limits with your existing Claude Code login, so it works when pi runs Claude models through the SDK, including `pi-claude-bridge`. You don't need a separate Anthropic login or API key in pi.
+- **Codex support, no CLI needed.** Reads 5-hour and weekly Codex limits over HTTPS with pi's own `openai-codex` login. pi refreshes the token; `~/.codex/auth.json` is never read or touched.
+- **Never slows pi down.** Usage is fetched in the background, and pi doesn't wait for it.
+- **Updates after each prompt.** It refreshes when a session starts, when you switch models, and once each prompt finishes, instead of on every turn or tool call.
+- **Fewer calls with several sessions.** Results are cached on disk for 60 seconds, and the cache is shared between all running pi sessions. A cached value is marked with `󰃨`.
+- **Doesn't replace your footer.** It adds one status entry, so pi's built-in footer and other extensions keep working.
+- **No tokens used.** Reading limits sends no prompt and doesn't touch your quota.
+- **Clear errors.** If a lookup fails, the status line shows the reason in red, such as the Claude CLI's own error.
+- **Small and readable.** A few hundred lines of plain TypeScript, with no build step.
+
+## Supported models
+
+| Active model | Source | Shows |
+|---|---|---|
+| Model id contains `claude` | Claude Agent SDK (Claude Code login) | 5-hour and 7-day utilization |
+| `openai-codex` provider, or model id contains `codex` | ChatGPT usage endpoint (pi's `openai-codex` login) | 5-hour and weekly usage |
+
+Other models show `<model> not supported yet`.
+
+## Requirements
+
+- pi
+- **For Claude:** `@anthropic-ai/claude-agent-sdk` installed alongside pi (for example as a `pi-claude-bridge` dependency), signed in to a Claude subscription. API-key logins have no subscription limits to show.
+- **For Codex:** signed in to pi's `openai-codex` provider (`/login` in pi) with a ChatGPT subscription.
+
+## Install
+
+```bash
+pi install npm:pi-usage-limits
+```
+
+Try it for a single session without installing:
+
+```bash
+pi -e npm:pi-usage-limits
+```
+
+## How it works
+
+| Event | Action |
+|---|---|
+| `session_start` | Show current usage |
+| `model_select` | Show usage for the new model |
+| `agent_settled` | Refresh after a prompt completes |
+
+The cache lives at `~/.pi/agent/cache/pi-usage-limits.json`. Writes are atomic and protected by a lockfile, so parallel sessions don't corrupt it.
+
+## Caveats
+
+- **Claude** limits come from an experimental Claude Agent SDK API, which may change in a future SDK release.
+- **Codex** limits come from an undocumented ChatGPT endpoint (`chatgpt.com/backend-api/wham/usage`, the same one the Codex CLI uses), which may change without notice.
+- Each uncached Claude lookup starts a short-lived `claude` process, which takes about a second. It runs in the background.
+
+## License
+
+MIT

package/claude_limits.ts

@@ -0,0 +1,54 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+export type ClaudeLimits = {
+  subscription: string;
+  available: boolean;
+  rate_limits: {
+    five_hour: {
+      utilization: number;
+    };
+    seven_day: {
+      utilization: number;
+    };
+  };
+};
+
+export const getLimits = async function (): Promise<ClaudeLimits> {
+  const log: string[] = [];
+  const q = query({
+    prompt: (async function* () {
+      await new Promise(() => {});
+    })(),
+    options: {
+      persistSession: false,
+      settingSources: [],
+      strictMcpConfig: true,
+      // CLI only explains a null usage result in its debug log
+      extraArgs: { "debug-to-stderr": null },
+      stderr: (s) => log.push(s),
+    },
+  });
+
+  let u;
+  try {
+    u = await q.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET({
+      skipBehaviors: true,
+    });
+  } finally {
+    q.close();
+  }
+
+  if (!u.rate_limits) {
+    const why = log
+      .join("")
+      .split("\n")
+      .findLast((l) => l.includes("[ERROR]"));
+    throw new Error(why?.replace(/^\S+ \[\w+\] /, "") ?? "no rate_limits");
+  }
+
+  return {
+    subscription: u.subscription_type,
+    available: u.rate_limits_available,
+    rate_limits: u.rate_limits,
+  } as ClaudeLimits;
+};

package/codex_limits.ts

@@ -0,0 +1,58 @@
+export type CodexWindow = {
+  usedPercent: number;
+  windowDurationMins: number | null;
+  resetsAt: number | null;
+};
+
+export type CodexLimits = {
+  primary: CodexWindow | null;
+  secondary: CodexWindow | null;
+};
+
+type WhamWindow = {
+  used_percent: number;
+  limit_window_seconds?: number | null;
+  reset_at?: number | null;
+} | null;
+
+// undocumented ChatGPT backend endpoint (same one the Codex CLI calls); may change without notice
+const USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+
+// Account id lives in the OAuth access token, as pi-ai reads it.
+export function accountId(token: string): string | undefined {
+  try {
+    const payload = JSON.parse(
+      Buffer.from(token.split(".")[1], "base64url").toString(),
+    );
+    return payload["https://api.openai.com/auth"]?.chatgpt_account_id;
+  } catch {
+    return undefined;
+  }
+}
+
+const toWindow = (w: WhamWindow | undefined): CodexWindow | null =>
+  w
+    ? {
+        usedPercent: w.used_percent,
+        windowDurationMins: w.limit_window_seconds
+          ? w.limit_window_seconds / 60
+          : null,
+        resetsAt: w.reset_at ?? null,
+      }
+    : null;
+
+export async function getCodexLimits(token: string): Promise<CodexLimits> {
+  const id = accountId(token);
+  if (!id) throw new Error("Codex token has no ChatGPT account id");
+  const res = await fetch(USAGE_URL, {
+    headers: { Authorization: `Bearer ${token}`, "ChatGPT-Account-Id": id },
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!res.ok)
+    throw new Error(`Codex usage request failed: HTTP ${res.status}`);
+  const body = await res.json();
+  return {
+    primary: toWindow(body?.rate_limit?.primary_window),
+    secondary: toWindow(body?.rate_limit?.secondary_window),
+  };
+}

package/index.ts

@@ -0,0 +1,22 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionEvent,
+} from "@earendil-works/pi-coding-agent";
+import { getUsage } from "./usage";
+
+// pi awaits handler promises, so awaiting here blocks the redraw.
+function refresh(_event: ExtensionEvent, ctx: ExtensionContext) {
+  if (!ctx.model) return;
+  getUsage(ctx.model, ctx.modelRegistry)
+    .then((usage) =>
+      ctx.ui.setStatus("model-usage", ctx.ui.theme.fg("dim", usage)),
+    )
+    .catch((e) => ctx.ui.setStatus("model-usage", ctx.ui.theme.fg("dim", e)));
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", refresh);
+  pi.on("model_select", refresh);
+  pi.on("agent_settled", refresh);
+}

package/lock.ts

@@ -0,0 +1,57 @@
+import { open, readFile, rename, unlink, writeFile } from "node:fs/promises";
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+const alive = (pid: number) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e: any) {
+    return e.code === "EPERM"; // exists, owned by another user
+  }
+};
+
+// O_EXCL lockfile + dead-PID stale detection. Ceilings: two waiters breaking the same
+// stale lock can race (one may delete the other's fresh lock); PID reuse can keep a stale lock alive
+// until timeout; a crash between create and PID write leaves an empty lock that never goes stale.
+export async function withLock<T>(
+  file: string,
+  fn: () => Promise<T>,
+  timeoutMs = 5000,
+): Promise<T> {
+  const lock = `${file}.lock`;
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      const fh = await open(lock, "wx"); // atomic create-if-absent
+      await fh.writeFile(String(process.pid));
+      await fh.close();
+      break;
+    } catch (e: any) {
+      if (e.code !== "EEXIST") throw e;
+      const pid = Number(await readFile(lock, "utf8").catch(() => ""));
+      if (pid && !alive(pid)) {
+        await unlink(lock).catch(() => {});
+        continue;
+      }
+      if (Date.now() > deadline)
+        throw new Error(`Timed out waiting for ${lock}`);
+      await sleep(10 + Math.random() * 20);
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    await unlink(lock).catch(() => {});
+  }
+}
+
+export const readJson = (file: string) =>
+  readFile(file, "utf8").then(JSON.parse, () => undefined);
+
+// Atomic replace: lock-free readers see the old or new file, never a torn one
+export async function writeJson(file: string, data: unknown) {
+  const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  await writeFile(tmp, JSON.stringify(data, null, 2));
+  await rename(tmp, file);
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "pi-usage-limits",
+  "version": "0.1.1",
+  "description": "",
+  "keywords": [
+    "pi-package",
+    "pi-extension"
+  ],
+  "author": "Anthony Ilinykh <anthonyilinykh@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "*.ts",
+    "!*.test.ts",
+    "README.md",
+    "VERSION"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@anthropic-ai/claude-agent-sdk": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3"
+  }
+}

package/state.ts

@@ -0,0 +1,27 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readJson, withLock, writeJson } from "./lock";
+import { ClaudeLimits } from "./claude_limits";
+import type { CodexLimits } from "./codex_limits";
+
+const dir = join(getAgentDir(), "cache");
+const file = join(dir, "pi-usage-limits.json");
+
+export type State = {
+  anthropic_last_api_call?: number;
+  anthropic_last_limits?: ClaudeLimits;
+  codex_last_api_call?: number;
+  codex_last_limits?: CodexLimits;
+};
+
+export async function saveState(state: State) {
+  await mkdir(dir, { recursive: true });
+  await withLock(file, async () =>
+    writeJson(file, { ...(await readJson(file)), ...state }),
+  );
+}
+
+export async function loadState(): Promise<State | undefined> {
+  return readJson(file);
+}

package/usage.ts

@@ -0,0 +1,96 @@
+import { getLimits, ClaudeLimits } from "./claude_limits";
+import { loadState, saveState } from "./state";
+import {
+  getCodexLimits,
+  type CodexLimits,
+  type CodexWindow,
+} from "./codex_limits";
+
+type TokenSource = {
+  getApiKeyForProvider(provider: string): Promise<string | undefined>;
+};
+
+export async function getUsage(
+  model: { id: string; provider?: string },
+  auth: TokenSource,
+): Promise<string> {
+  if (model.provider === "openai-codex" || model.id.includes("codex")) {
+    return getCodexUsage(auth);
+  }
+
+  if (model.id.includes("claude")) {
+    return getClaudeUsage();
+  }
+
+  return `${model.id} not supported yet`;
+}
+
+async function getClaudeUsage() {
+  const state = await loadState();
+
+  if (
+    state?.anthropic_last_limits &&
+    Date.now() - (state.anthropic_last_api_call ?? 0) < 60_000
+  ) {
+    return formatClaudeUsage(state.anthropic_last_limits) + " 󰃨";
+  }
+
+  const limits = await getLimits();
+
+  await saveState({
+    anthropic_last_api_call: Date.now(),
+    anthropic_last_limits: limits,
+  });
+
+  return formatClaudeUsage(limits);
+}
+
+async function getCodexUsage(auth: TokenSource): Promise<string> {
+  const state = await loadState();
+
+  if (
+    state?.codex_last_limits &&
+    Date.now() - (state.codex_last_api_call ?? 0) < 60_000
+  ) {
+    return formatCodexUsage(state.codex_last_limits) + " 󰃨";
+  }
+  // pi's own openai-codex login; pi refreshes the token, we never touch ~/.codex/auth.json
+  const token = await auth.getApiKeyForProvider("openai-codex");
+  if (!token) throw new Error("Codex: run /login openai-codex");
+  const limits = await getCodexLimits(token);
+
+  await saveState({
+    codex_last_api_call: Date.now(),
+    codex_last_limits: limits,
+  });
+
+  return formatCodexUsage(limits);
+}
+
+function formatCodexUsage(limits: CodexLimits): string {
+  const window = (value: CodexWindow | null, fallback: string) => {
+    if (!value) return undefined;
+    const minutes = value.windowDurationMins;
+    const label = !minutes
+      ? fallback
+      : minutes % 1440 === 0
+        ? `${minutes / 1440}d`
+        : minutes % 60 === 0
+          ? `${minutes / 60}h`
+          : `${minutes}m`;
+    return `${label}: ${value.usedPercent}%`;
+  };
+  return (
+    [window(limits.primary, "primary"), window(limits.secondary, "secondary")]
+      .filter(Boolean)
+      .join(", ") || "usage unavailable"
+  );
+}
+
+function formatClaudeUsage(limits: ClaudeLimits) {
+  // SDK returns null when its usage fetch fails (throttled/unavailable)
+  if (!limits.rate_limits) return "usage unavailable";
+  const h = limits.rate_limits.five_hour.utilization;
+  const w = limits.rate_limits.seven_day.utilization;
+  return `5h: ${h}%, 7d: ${w}%`;
+}