pi-codex-footer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# pi-codex-footer
+
+A publishable Pi package that adds a readable 2-line footer with live OpenAI Codex quota information.
+
+## What it shows
+
+Line 1:
+- current folder
+- git branch
+- provider + model
+- thinking level
+- context usage as `used/window`
+- total session cost
+
+Line 2:
+- tokens/sec for the last assistant response
+- real Codex 5h usage
+- real Codex 7d usage
+- real 5h reset countdown
+- real 7d reset countdown
+
+For OpenAI Codex, quota data comes from:
+
+- `https://chatgpt.com/backend-api/codex/usage`
+
+using your existing Pi OAuth auth from:
+
+- `~/.pi/agent/auth.json`
+
+## Privacy / secrets
+
+This package **does not bundle or publish any secrets**.
+
+It reads your existing local `openai-codex` OAuth token and account id from `~/.pi/agent/auth.json` at runtime, then makes a request to OpenAI's ChatGPT backend to fetch live quota data.
+
+It does **not**:
+- write your token into the package
+- store your token in the repo
+- print your token in UI output
+- require manual config edits
+
+## Install
+
+### From a local folder
+
+```bash
+pi install ./pi-codex-footer
+```
+
+### From npm
+
+```bash
+pi install npm:pi-codex-footer
+```
+
+### From git
+
+```bash
+pi install git:github.com/glnarayanan/pi-codex-footer
+```
+
+Then reload Pi:
+
+```text
+/reload
+```
+
+## Commands
+
+- `/codex-footer-on` — reload Pi and enable the footer
+- `/codex-footer-off` — restore Pi's default footer
+- `/codex-footer-status` — show whether live Codex quota data is available
+
+## Behavior
+
+- If the active provider is `openai-codex`, the footer shows live quota numbers.
+- If the active provider is something else, quota fields show `n/a`.
+- Quota data refreshes roughly once per minute.
+- Reset countdowns update every second.
+
+## Development
+
+Try it locally without publishing:
+
+```bash
+pi install ./pi-codex-footer
+```
+
+or:
+
+```bash
+pi -e ./pi-codex-footer/extensions/index.ts
+```
+
+## Publish to npm
+
+```bash
+cd pi-codex-footer
+npm publish --access public
+```
+
+## Publish from git
+
+Push this folder to a repo, then install with:
+
+```bash
+pi install git:github.com/glnarayanan/pi-codex-footer
+```

package/extensions/index.ts

@@ -0,0 +1,337 @@
+import { basename } from "node:path";
+import { homedir } from "node:os";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { request as httpsRequest } from "node:https";
+import type { AssistantMessage } from "@mariozechner/pi-ai";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { truncateToWidth } from "@mariozechner/pi-tui";
+
+const AUTH_PATH = join(homedir(), ".pi", "agent", "auth.json");
+const QUOTA_REFRESH_MS = 60 * 1000;
+const MAX_RESPONSE_BYTES = 64 * 1024; // 64 KB — plenty for the quota JSON
+
+interface OpenAICodexAuth {
+  type: "oauth";
+  access: string;
+  accountId: string;
+}
+
+interface CodexUsageWindow {
+  used_percent: number;
+  limit_window_seconds: number;
+  reset_after_seconds: number;
+  reset_at: number;
+}
+
+interface CodexUsageResponse {
+  plan_type?: string;
+  rate_limit?: {
+    allowed: boolean;
+    limit_reached: boolean;
+    primary_window?: CodexUsageWindow | null;
+    secondary_window?: CodexUsageWindow | null;
+  };
+}
+
+/** Distinguishes auth failures from other errors so callers can notify the user. */
+interface CodexFetchResult {
+  usage: CodexUsageResponse | null;
+  authExpired: boolean;
+}
+
+function fmtInt(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return `${Math.round(n)}`;
+}
+
+function fmtMoney(n: number): string {
+  return `$${n.toFixed(3)}`;
+}
+
+function fmtUsedOfTotal(used: number, total?: number): string {
+  if (!total || total <= 0) return fmtInt(used);
+  return `${fmtInt(used)}/${fmtInt(total)}`;
+}
+
+function fmtWindowUsage(window?: CodexUsageWindow | null): string {
+  if (!window) return "n/a";
+  const used = Math.max(0, window.used_percent);
+  const left = Math.max(0, 100 - used);
+  return `${used.toFixed(1)}% used / ${left.toFixed(1)}% left`;
+}
+
+function fmtDuration(ms: number): string {
+  if (ms <= 0) return "now";
+  const totalSeconds = Math.ceil(ms / 1000);
+  const days = Math.floor(totalSeconds / 86400);
+  const hours = Math.floor((totalSeconds % 86400) / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  if (days > 0) return `${days}d ${hours}h`;
+  if (hours > 0) return `${hours}h ${minutes}m`;
+  return `${minutes}m`;
+}
+
+function getAssistantMessages(ctx: Parameters<Parameters<ExtensionAPI["on"]>[1]>[1]) {
+  return ctx.sessionManager
+    .getBranch()
+    .filter((e): e is typeof e & { type: "message"; message: AssistantMessage } => e.type === "message" && e.message.role === "assistant")
+    .map((e) => e.message);
+}
+
+function readOpenAICodexAuth(): OpenAICodexAuth | null {
+  try {
+    if (!existsSync(AUTH_PATH)) return null;
+    const data = JSON.parse(readFileSync(AUTH_PATH, "utf8")) as Record<string, unknown>;
+    const cred = data["openai-codex"] as Partial<OpenAICodexAuth> | undefined;
+    if (!cred || cred.type !== "oauth" || !cred.access || !cred.accountId) return null;
+    return cred as OpenAICodexAuth;
+  } catch {
+    return null;
+  }
+}
+
+/** Validates that the parsed JSON structurally matches CodexUsageResponse. */
+function isValidCodexResponse(obj: unknown): obj is CodexUsageResponse {
+  if (!obj || typeof obj !== "object") return false;
+  const record = obj as Record<string, unknown>;
+  // rate_limit is the only field we actually consume — require it to be present and object-shaped
+  if (record.rate_limit !== undefined && (typeof record.rate_limit !== "object" || record.rate_limit === null)) {
+    return false;
+  }
+  return true;
+}
+
+async function fetchCodexUsage(): Promise<CodexFetchResult> {
+  const cred = readOpenAICodexAuth();
+  if (!cred) return { usage: null, authExpired: false };
+
+  return await new Promise<CodexFetchResult>((resolve) => {
+    let destroyed = false;
+    const req = httpsRequest(
+      "https://chatgpt.com/backend-api/codex/usage",
+      {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${cred.access}`,
+          "chatgpt-account-id": cred.accountId,
+          "OpenAI-Beta": "responses=experimental",
+          "User-Agent": "pi-codex-footer"
+        }
+      },
+      (res) => {
+        let body = "";
+        res.setEncoding("utf8");
+        res.on("data", (chunk) => {
+          body += chunk;
+          // Cap accumulated body to prevent memory exhaustion
+          if (body.length > MAX_RESPONSE_BYTES) {
+            destroyed = true;
+            req.destroy();
+            resolve({ usage: null, authExpired: false });
+          }
+        });
+        res.on("end", () => {
+          if (destroyed) return;
+          const status = res.statusCode ?? 500;
+
+          // Surface auth failures distinctly so the UI can notify the user
+          if (status === 401 || status === 403) {
+            resolve({ usage: null, authExpired: true });
+            return;
+          }
+          if (status < 200 || status >= 300) {
+            resolve({ usage: null, authExpired: false });
+            return;
+          }
+          try {
+            const parsed: unknown = JSON.parse(body);
+            if (isValidCodexResponse(parsed)) {
+              resolve({ usage: parsed, authExpired: false });
+            } else {
+              resolve({ usage: null, authExpired: false });
+            }
+          } catch {
+            resolve({ usage: null, authExpired: false });
+          }
+        });
+      }
+    );
+    req.on("error", () => resolve({ usage: null, authExpired: false }));
+    req.setTimeout(15000, () => {
+      req.destroy();
+      resolve({ usage: null, authExpired: false });
+    });
+    req.end();
+  });
+}
+
+export default function (pi: ExtensionAPI) {
+  let lastAssistantStart: number | null = null;
+  let lastTokensPerSecond: number | null = null;
+  let lastKnownCodexUsage: CodexUsageResponse | null = null;
+  let authExpiredNotified = false;
+
+  pi.on("message_start", async (event) => {
+    if (event.message.role === "assistant") lastAssistantStart = Date.now();
+  });
+
+  pi.on("message_end", async (event) => {
+    if (event.message.role !== "assistant") return;
+    const m = event.message as AssistantMessage;
+    if (lastAssistantStart) {
+      const elapsedSeconds = Math.max((Date.now() - lastAssistantStart) / 1000, 0.001);
+      lastTokensPerSecond = m.usage.output / elapsedSeconds;
+    }
+    lastAssistantStart = null;
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    let codexUsage: CodexUsageResponse | null = null;
+    let codexUsageFetchedAt = 0;
+    let codexUsageInFlight: Promise<void> | null = null;
+
+    const handleFetchResult = (result: CodexFetchResult) => {
+      codexUsage = result.usage;
+      lastKnownCodexUsage = result.usage;
+      codexUsageFetchedAt = Date.now();
+      if (result.authExpired && !authExpiredNotified) {
+        authExpiredNotified = true;
+        ctx.ui.notify("Codex quota: auth token expired or forbidden — re-authenticate with Pi to restore live quota data.", "warning");
+      } else if (!result.authExpired && result.usage) {
+        // Successful fetch clears the flag so a future expiry is reported again
+        authExpiredNotified = false;
+      }
+    };
+
+    const primeCodexUsage = async () => {
+      if (ctx.model?.provider !== "openai-codex") return;
+      if (codexUsageInFlight) return;
+      codexUsageInFlight = (async () => {
+        try {
+          handleFetchResult(await fetchCodexUsage());
+        } catch {
+          codexUsage = null;
+          lastKnownCodexUsage = null;
+          codexUsageFetchedAt = Date.now();
+        } finally {
+          codexUsageInFlight = null;
+        }
+      })();
+      await codexUsageInFlight;
+    };
+
+    void primeCodexUsage();
+
+    ctx.ui.setFooter((tui, theme, footerData) => {
+      const refreshCodexUsage = () => {
+        if (codexUsageInFlight) return;
+        codexUsageInFlight = (async () => {
+          try {
+            handleFetchResult(await fetchCodexUsage());
+          } catch {
+            codexUsage = null;
+            lastKnownCodexUsage = null;
+            codexUsageFetchedAt = Date.now();
+          } finally {
+            codexUsageInFlight = null;
+            tui.requestRender();
+          }
+        })();
+      };
+
+      const unsub = footerData.onBranchChange(() => tui.requestRender());
+      const interval = setInterval(() => tui.requestRender(), 1000);
+
+      return {
+        dispose: () => {
+          unsub();
+          clearInterval(interval);
+        },
+        invalidate() {},
+        render(width: number): string[] {
+          const now = Date.now();
+          const cwdName = basename(ctx.cwd) || ctx.cwd;
+          const branch = footerData.getGitBranch() || "no-git";
+          const provider = ctx.model?.provider || "no-provider";
+          const model = ctx.model?.id || "no-model";
+          const thinking = pi.getThinkingLevel();
+          const context = ctx.getContextUsage();
+          const isCodex = provider === "openai-codex";
+
+          if (isCodex && Date.now() - codexUsageFetchedAt > QUOTA_REFRESH_MS && !codexUsageInFlight) {
+            refreshCodexUsage();
+          }
+
+          const messages = getAssistantMessages(ctx);
+          const totalCost = messages.reduce((sum, m) => sum + (m.usage.cost.total || 0), 0);
+          const livePrimary = codexUsage?.rate_limit?.primary_window;
+          const liveSecondary = codexUsage?.rate_limit?.secondary_window;
+          const fiveHourResetText = isCodex && livePrimary
+            ? fmtDuration(Math.max(0, livePrimary.reset_at * 1000 - now))
+            : "n/a";
+          const weeklyResetText = isCodex && liveSecondary
+            ? fmtDuration(Math.max(0, liveSecondary.reset_at * 1000 - now))
+            : "n/a";
+
+          const sep = ` ${theme.fg("dim", "•")} `;
+          const line1 = [
+            `${theme.fg("dim", "📁")} ${cwdName}`,
+            `${theme.fg("dim", "")} ${branch}`,
+            `${theme.fg("dim", "🤖")} ${provider} - ${model}`,
+            `${theme.fg("dim", "🧠")} ${thinking}`,
+            `${theme.fg("dim", "◔")} ${context ? fmtUsedOfTotal(context.tokens || 0, context.contextWindow) : "n/a"}`,
+            `${theme.fg("dim", "💵")} ${fmtMoney(totalCost)}`
+          ].join(sep);
+
+          const line2 = [
+            `${theme.fg("dim", "⚡")} ${lastTokensPerSecond ? `${lastTokensPerSecond.toFixed(1)} tok/s` : "n/a"}`,
+            `${theme.fg("dim", "5h")} ${isCodex ? fmtWindowUsage(livePrimary) : "n/a"}`,
+            `${theme.fg("dim", "7d")} ${isCodex ? fmtWindowUsage(liveSecondary) : "n/a"}`,
+            `${theme.fg("dim", "↺5h")} ${fiveHourResetText}`,
+            `${theme.fg("dim", "↺7d")} ${weeklyResetText}`
+          ].join(sep);
+
+          return [truncateToWidth(line1, width), truncateToWidth(line2, width)];
+        }
+      };
+    });
+  });
+
+  pi.registerCommand("codex-footer-status", {
+    description: "Show live Codex footer quota status",
+    handler: async (_args, commandCtx) => {
+      const auth = readOpenAICodexAuth();
+      const result = await fetchCodexUsage();
+      const usage = result.usage ?? lastKnownCodexUsage;
+      const primary = usage?.rate_limit?.primary_window;
+      const secondary = usage?.rate_limit?.secondary_window;
+      const lines = [
+        `provider: ${commandCtx.model?.provider || "unknown"}`,
+        `auth: ${auth ? (result.authExpired ? "expired" : "found") : "missing"}`,
+        `plan: ${usage?.plan_type || "unknown"}`,
+        `5h: ${fmtWindowUsage(primary)}`,
+        `7d: ${fmtWindowUsage(secondary)}`,
+        `5h reset: ${primary ? fmtDuration(Math.max(0, primary.reset_at * 1000 - Date.now())) : "n/a"}`,
+        `7d reset: ${secondary ? fmtDuration(Math.max(0, secondary.reset_at * 1000 - Date.now())) : "n/a"}`
+      ];
+      commandCtx.ui.notify(lines.join("\n"), usage ? "info" : "warning");
+    }
+  });
+
+  pi.registerCommand("codex-footer-off", {
+    description: "Restore Pi's default footer",
+    handler: async (_args, ctx) => {
+      ctx.ui.setFooter(undefined);
+      ctx.ui.notify("Default footer restored", "info");
+    }
+  });
+
+  pi.registerCommand("codex-footer-on", {
+    description: "Enable the Codex quota footer",
+    handler: async (_args, ctx) => {
+      await ctx.reload();
+    }
+  });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "pi-codex-footer",
+  "version": "0.1.0",
+  "description": "Pi extension that adds a 2-line footer with live OpenAI Codex 5h/7d quota usage and reset timers.",
+  "type": "module",
+  "author": "glnarayanan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/glnarayanan/pi-codex-footer.git"
+  },
+  "homepage": "https://github.com/glnarayanan/pi-codex-footer#readme",
+  "bugs": {
+    "url": "https://github.com/glnarayanan/pi-codex-footer/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "openai",
+    "codex",
+    "chatgpt",
+    "footer"
+  ],
+  "license": "MIT",
+  "files": [
+    "README.md",
+    "LICENSE",
+    "extensions"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "scripts": {
+    "build": "echo 'nothing to build'",
+    "check": "echo 'load in pi with pi -e ./extensions/index.ts or pi install ./pi-codex-footer'"
+  }
+}