opencode-codex-usage-tui 1.3.2

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,103 @@
+# opencode-codex-usage
+
+OpenCode TUI plugin that shows remaining ChatGPT Codex usage limits in the sidebar.
+
+It reads the same internal Codex usage data shown by the ChatGPT Codex usage dashboard and renders remaining limit percentages, reset timers, credits, and banked reset credits.
+
+## Features
+
+- Shows remaining Codex limits, not used percentage
+- Displays the shortest window first, typically the shared 5-hour Plus limit
+- Displays reset timers below each usage row and aligned to the right
+- Shows the ChatGPT plan in uppercase, for example `PLUS`
+- Supports collapsed and expanded sidebar display
+- Automatically reads trusted Codex CLI auth from `~/.codex/auth.json`
+- Continuously refreshes usage in the background
+- Updates reset countdowns in realtime between API refreshes
+- Supports disabling requests with `OPENCODE_CODEX_USAGE_DISABLED=true`
+
+## Install
+
+Add the published package to OpenCode's TUI configuration:
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["opencode-codex-usage-tui@1.3.2"]
+}
+```
+
+OpenCode resolves the npm package and loads its `./tui` entry point directly. No files are copied into the OpenCode configuration directory. Pin the version for reproducible setups, or omit the version when you want OpenCode to resolve the latest release.
+
+For local development, build and pack the project:
+
+```powershell
+npm install
+npm run check
+npm pack
+```
+
+Then reference the generated tarball in `tui.json` using the local package spec supported by your OpenCode installation. Restart OpenCode after editing `tui.json`; TUI plugins are loaded at startup.
+
+For example, a local file URL can be used when supported:
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["file:///absolute/path/to/opencode-codex-usage-tui-1.3.2.tgz"]
+}
+```
+
+## Configure Auth
+
+Default flow:
+
+```powershell
+codex login
+```
+
+The plugin reads the Codex CLI token from:
+
+```text
+~/.codex/auth.json
+```
+
+The file must be the regular, non-linked file created by the Codex CLI. The plugin does not support environment-token overrides, custom Codex homes, or a separate OpenCode credential file.
+
+To disable the usage request entirely for a shell session:
+
+```powershell
+$env:OPENCODE_CODEX_USAGE_DISABLED = "true"
+```
+
+The section starts collapsed but begins fetching immediately. Reset countdowns render live, while usage data refreshes at most once per minute to avoid rate limits.
+
+## Getting A Codex Token
+
+After logging in with Codex CLI, credentials are normally stored in:
+
+```text
+~/.codex/auth.json
+```
+
+The plugin reads `tokens.access_token` (or `tokens.accessToken`) and an optional account ID from the token object. If the token expires, run `codex login` again and restart OpenCode if needed.
+
+Do not commit or share `auth.json` or access tokens.
+
+## Endpoint
+
+This plugin calls an internal ChatGPT endpoint:
+
+```text
+https://chatgpt.com/backend-api/wham/usage
+```
+
+Because this endpoint is not a public stable API, the plugin is defensive and falls back to a short error plus the official dashboard URL if the payload changes:
+
+```text
+https://chatgpt.com/codex/settings/usage
+```
+
+## License
+
+MIT

package/dist/core.js

@@ -0,0 +1,142 @@
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+const DEFAULT_CODEX_AUTH_FILE = join(homedir(), ".codex", "auth.json");
+const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const CODEX_USAGE_TIMEOUT_MS = 15e3;
+const DASHBOARD_URL = "https://chatgpt.com/codex/settings/usage";
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isTrustedCodexAuthFile(path) {
+  if (path !== DEFAULT_CODEX_AUTH_FILE) return false;
+  const directory = dirname(path);
+  try {
+    const directoryStats = lstatSync(directory);
+    const fileStats = lstatSync(path);
+    if (directoryStats.isSymbolicLink() || !directoryStats.isDirectory() || fileStats.isSymbolicLink() || !fileStats.isFile() || fileStats.nlink > 1) return false;
+    const compare = (value) => process.platform === "win32" ? value.toLowerCase() : value;
+    if (compare(resolve(directory)) !== compare(resolve(realpathSync(directory))) || compare(resolve(path)) !== compare(resolve(realpathSync(path)))) return false;
+    return process.platform === "win32" || (fileStats.mode & 63) === 0;
+  } catch {
+    return false;
+  }
+}
+function toNumber(value) {
+  if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+  if (typeof value !== "string" || !value.trim()) return void 0;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function toStringValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function firstString(...values) {
+  for (const value of values) {
+    const result = toStringValue(value);
+    if (result) return result;
+  }
+  return void 0;
+}
+function loadConfig(readFile = (path) => readFileSync(path, "utf8"), isTrustedFile = isTrustedCodexAuthFile) {
+  try {
+    if (!isTrustedFile(DEFAULT_CODEX_AUTH_FILE)) return null;
+    const parsed = JSON.parse(readFile(DEFAULT_CODEX_AUTH_FILE, "utf8"));
+    if (!isRecord(parsed) || !isRecord(parsed.tokens)) return null;
+    const accessToken = firstString(parsed.tokens.access_token, parsed.tokens.accessToken);
+    if (!accessToken) return null;
+    const accountId = firstString(parsed.tokens.account_id, parsed.tokens.accountId);
+    return accountId ? { accessToken, accountId, source: "codex" } : { accessToken, source: "codex" };
+  } catch {
+    return null;
+  }
+}
+function isUsageDisabled(env = process.env) {
+  return env.OPENCODE_CODEX_USAGE_DISABLED?.trim().toLowerCase() === "true";
+}
+async function fetchUsage(options = {}) {
+  if (options.disabled ?? isUsageDisabled()) return { ok: false, reason: "disabled" };
+  let config;
+  try {
+    config = (options.readConfig ?? (() => loadConfig()))();
+  } catch {
+    return { ok: false, reason: "no-config" };
+  }
+  if (!config) return { ok: false, reason: "no-config" };
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch?.bind(globalThis);
+  if (!fetchImpl) return { ok: false, reason: "request-failed" };
+  const headers = { Accept: "application/json", Authorization: `Bearer ${config.accessToken}`, Referer: DASHBOARD_URL, "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" };
+  if (config.accountId) headers["ChatGPT-Account-ID"] = config.accountId;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? CODEX_USAGE_TIMEOUT_MS);
+  try {
+    const response = await fetchImpl(CODEX_USAGE_URL, { headers, signal: controller.signal, redirect: "error" });
+    if (response.status === 401 || response.status === 403) return { ok: false, reason: "unauthorized", status: response.status };
+    if (response.status === 429) return { ok: false, reason: "rate-limited", status: response.status };
+    if (!response.ok) return { ok: false, reason: "http-error", status: response.status };
+    if (!(response.headers.get("content-type") ?? "").includes("application/json")) return { ok: false, reason: "unexpected-response" };
+    let raw;
+    try {
+      raw = await response.json();
+    } catch {
+      return { ok: false, reason: "unexpected-response" };
+    }
+    return isRecord(raw) ? { ok: true, payload: raw } : { ok: false, reason: "unexpected-response" };
+  } catch {
+    return { ok: false, reason: controller.signal.aborted ? "timeout" : "request-failed" };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function resetInSeconds(window) {
+  const resetAfter = toNumber(window.reset_after_seconds);
+  if (resetAfter !== void 0) return Math.max(0, Math.floor(resetAfter));
+  const resetAt = toNumber(window.reset_at);
+  if (resetAt === void 0) return 0;
+  const resetAtMs = resetAt > 1e12 ? resetAt : resetAt * 1e3;
+  return Math.max(0, Math.floor((resetAtMs - Date.now()) / 1e3));
+}
+function labelForWindow(seconds, fallback) {
+  if (seconds <= 6 * 3600) return "5h";
+  if (seconds >= 6 * 86400 && seconds <= 8 * 86400) return "Weekly";
+  if (seconds >= 27 * 86400 && seconds <= 32 * 86400) return "Monthly";
+  if (seconds >= 86400) return `${Math.round(seconds / 86400)}d`;
+  return fallback;
+}
+function normalizeWindow(label, window, limitReached) {
+  if (!isRecord(window)) return null;
+  const usedPercent = toNumber(window.used_percent);
+  const windowSeconds = toNumber(window.limit_window_seconds);
+  if (usedPercent === void 0 || windowSeconds === void 0 || windowSeconds < 0) return null;
+  return { label: labelForWindow(windowSeconds, label), usedPercent: Math.max(0, Math.min(100, usedPercent)), windowSeconds, resetInSec: resetInSeconds(window), limitReached };
+}
+function normalizeRateLimit(label, rateLimit) {
+  if (!isRecord(rateLimit)) return [];
+  const limitReached = rateLimit.limit_reached === true;
+  return [normalizeWindow(label, rateLimit.primary_window, limitReached), normalizeWindow(label, rateLimit.secondary_window, limitReached)].filter((item) => Boolean(item));
+}
+function normalizePayload(payload) {
+  const windows = normalizeRateLimit("Usage", payload.rate_limit);
+  if (Array.isArray(payload.additional_rate_limits)) for (const item of payload.additional_rate_limits) {
+    if (!isRecord(item)) continue;
+    const name = toStringValue(item.limit_name) ?? toStringValue(item.metered_feature) ?? "Extra";
+    for (const window of normalizeRateLimit(name, item.rate_limit)) windows.push({ ...window, label: window.label === "5h" || window.label === "Weekly" ? name : window.label });
+  }
+  windows.sort((a, b) => a.windowSeconds - b.windowSeconds);
+  if (!windows.length) return { windows, error: isRecord(payload.rate_limit) ? "usage windows missing" : "rate_limit missing" };
+  const creditsPayload = isRecord(payload.credits) ? payload.credits : void 0;
+  const credits = creditsPayload ? { hasCredits: creditsPayload.has_credits === true, unlimited: creditsPayload.unlimited === true, balance: toStringValue(creditsPayload.balance) ?? "0" } : void 0;
+  const resetCreditsPayload = isRecord(payload.rate_limit_reset_credits) ? payload.rate_limit_reset_credits : void 0;
+  return { plan: toStringValue(payload.plan_type) ?? "Unknown", windows, credits, resetCredits: toNumber(resetCreditsPayload?.available_count) };
+}
+export {
+  CODEX_USAGE_TIMEOUT_MS,
+  CODEX_USAGE_URL,
+  DEFAULT_CODEX_AUTH_FILE,
+  fetchUsage,
+  isRecord,
+  isUsageDisabled,
+  loadConfig,
+  normalizePayload,
+  toNumber
+};

package/dist/tui.js

@@ -0,0 +1,238 @@
+import { createElement, insert, setProp } from "@opentui/solid";
+import { fetchUsage, normalizePayload } from "./core.js";
+const DASHBOARD_URL = "https://chatgpt.com/codex/settings/usage";
+const REFRESH_MS = 6e4;
+const RENDER_MS = 1e3;
+const COLLAPSED_KV_KEY = "codex-usage.collapsed";
+let state = { status: "loading", windows: [], lastFetch: 0 };
+let inflight = false;
+let fetchRequested = true;
+let collapsed = true;
+let collapsedInitialized = false;
+async function fetchOnce() {
+  if (!fetchRequested || inflight) return;
+  inflight = true;
+  state = { ...state, status: "loading", message: void 0 };
+  try {
+    const result = await fetchUsage();
+    if (!result.ok) {
+      const status = result.reason === "disabled" ? "disabled" : result.reason === "no-config" ? "no-config" : "error";
+      state = { ...state, status, message: failureMessage(result.reason, result.status), lastFetch: Date.now() };
+      return;
+    }
+    const normalized = normalizePayload(result.payload);
+    if (normalized.windows.length === 0) {
+      state = { ...state, status: "error", message: normalized.error ?? "usage windows missing", lastFetch: Date.now() };
+      return;
+    }
+    state = { status: "ok", lastFetch: Date.now(), ...normalized };
+  } catch {
+    state = { ...state, status: "error", message: "request failed", lastFetch: Date.now() };
+  } finally {
+    inflight = false;
+  }
+}
+function failureMessage(reason, status) {
+  switch (reason) {
+    case "disabled":
+      return "disabled by OPENCODE_CODEX_USAGE_DISABLED";
+    case "no-config":
+      return "auth file unavailable or invalid";
+    case "unauthorized":
+      return "token expired or unauthorized";
+    case "rate-limited":
+      return "rate limited";
+    case "http-error":
+      return `HTTP ${status ?? "error"}`;
+    case "unexpected-response":
+      return "unexpected response";
+    case "timeout":
+      return "request timed out";
+    case "request-failed":
+      return "request failed";
+  }
+}
+function fmtReset(resetSec) {
+  if (!resetSec || resetSec < 0) return "";
+  const days = Math.floor(resetSec / 86400);
+  const hours = Math.floor(resetSec % 86400 / 3600);
+  const mins = Math.floor(resetSec % 3600 / 60);
+  if (days > 0) return `${days}d ${hours}h`;
+  if (hours > 0) return `${hours}h ${mins}m`;
+  return `${mins}m`;
+}
+function fmtPct(pct) {
+  return `${pct.toFixed(1).padStart(5)}%`;
+}
+function liveResetSeconds(usage) {
+  if (!state.lastFetch) return usage.resetInSec;
+  return Math.max(0, usage.resetInSec - Math.floor((Date.now() - state.lastFetch) / 1e3));
+}
+function remainingPercent(usedPercent) {
+  return Math.max(0, Math.min(100, 100 - usedPercent));
+}
+function summaryText() {
+  const first = state.windows[0];
+  if (state.status === "ok" && first) return `(${first.label} ${remainingPercent(first.usedPercent).toFixed(1)}% left)`;
+  if (state.status === "no-config") return "(no config)";
+  if (state.status === "disabled") return "(disabled)";
+  if (state.status === "error") return `(${state.message ?? "error"})`;
+  return "(...)";
+}
+function setNodeText(node, text) {
+  insert(node, null);
+  insert(node, [text]);
+}
+function el(tag, props, children = []) {
+  const node = createElement(tag);
+  for (const [key, value] of Object.entries(props)) {
+    if (value !== void 0) setProp(node, key, value);
+  }
+  for (const child of children) {
+    if (child !== null && child !== void 0 && child !== false) insert(node, child);
+  }
+  return node;
+}
+function txt(props, children = []) {
+  return el("text", props, children);
+}
+function box(props, children = []) {
+  return el("box", props, children);
+}
+function valNode(style) {
+  return txt(style, [""]);
+}
+const tui = async (api) => {
+  if (!collapsedInitialized) {
+    collapsed = Boolean(api.kv.get(COLLAPSED_KV_KEY, true));
+    fetchRequested = true;
+    collapsedInitialized = true;
+  }
+  api.slots.register({
+    order: 160,
+    slots: {
+      sidebar_content() {
+        const theme = api.theme.current;
+        const muted = theme.textMuted;
+        const normal = theme.text;
+        const valStyle = { fg: muted };
+        const headerTitle = valNode({ bold: true, fg: normal });
+        const headerSummary = valNode(valStyle);
+        const planVal = valNode(valStyle);
+        const creditsVal = valNode(valStyle);
+        const resetsVal = valNode(valStyle);
+        const statusVal = valNode(valStyle);
+        function usageBlock() {
+          const label = valNode({ fg: muted });
+          const pct = valNode(valStyle);
+          const reset = valNode(valStyle);
+          const block = box({ flexDirection: "column", width: "100%" }, [
+            box({ flexDirection: "row", width: "100%", justifyContent: "space-between" }, [label, pct]),
+            box({ flexDirection: "row", width: "100%", justifyContent: "flex-end" }, [reset])
+          ]);
+          return { block, label, pct, reset };
+        }
+        const primary = usageBlock();
+        const secondary = usageBlock();
+        const extraOne = usageBlock();
+        const extraTwo = usageBlock();
+        function setUsageWindow(view, usage) {
+          setProp(view.block, "visible", Boolean(usage));
+          if (!usage) {
+            setNodeText(view.label, "");
+            setNodeText(view.pct, "");
+            setNodeText(view.reset, "");
+            return;
+          }
+          const reset = fmtReset(liveResetSeconds(usage));
+          setNodeText(view.label, usage.label);
+          setNodeText(view.pct, `${fmtPct(remainingPercent(usage.usedPercent))} left${usage.limitReached ? " exhausted" : ""}`);
+          setNodeText(view.reset, reset ? `reset ${reset}` : "");
+        }
+        function clearWindows() {
+          setUsageWindow(primary, void 0);
+          setUsageWindow(secondary, void 0);
+          setUsageWindow(extraOne, void 0);
+          setUsageWindow(extraTwo, void 0);
+        }
+        function update() {
+          const now = Date.now();
+          if (fetchRequested && (state.lastFetch === 0 || now - state.lastFetch > REFRESH_MS)) fetchOnce();
+          setNodeText(headerTitle, collapsed ? "\u25B6 Codex Usage" : "\u25BC Codex Usage");
+          setNodeText(headerSummary, collapsed ? ` ${summaryText()}` : "");
+          setProp(headerSummary, "visible", collapsed);
+          if (state.status === "ok") {
+            const windows = state.windows;
+            setNodeText(planVal, (state.plan ?? "Unknown").toUpperCase());
+            setUsageWindow(primary, windows[0]);
+            setUsageWindow(secondary, windows[1]);
+            setUsageWindow(extraOne, windows[2]);
+            setUsageWindow(extraTwo, windows[3]);
+            setNodeText(
+              creditsVal,
+              state.credits ? state.credits.hasCredits ? state.credits.unlimited ? "unlimited" : state.credits.balance : "none" : ""
+            );
+            setNodeText(resetsVal, state.resetCredits === void 0 ? "" : `${state.resetCredits} available`);
+            setNodeText(statusVal, "");
+          } else if (state.status === "no-config") {
+            setNodeText(planVal, "");
+            clearWindows();
+            setNodeText(creditsVal, "");
+            setNodeText(resetsVal, "");
+            setNodeText(statusVal, "run codex login to create ~/.codex/auth.json, then restart OpenCode");
+          } else if (state.status === "disabled") {
+            setNodeText(planVal, "");
+            clearWindows();
+            setNodeText(creditsVal, "");
+            setNodeText(resetsVal, "");
+            setNodeText(statusVal, state.message ?? "disabled");
+          } else if (state.status === "error") {
+            setNodeText(planVal, "");
+            clearWindows();
+            setNodeText(creditsVal, "");
+            setNodeText(resetsVal, "");
+            setNodeText(statusVal, `${state.message ?? "error"}
+${DASHBOARD_URL}`);
+          } else {
+            setNodeText(planVal, "");
+            clearWindows();
+            setNodeText(creditsVal, "");
+            setNodeText(resetsVal, "");
+            setNodeText(statusVal, "loading");
+          }
+        }
+        function toggle() {
+          collapsed = !collapsed;
+          api.kv.set(COLLAPSED_KV_KEY, collapsed);
+          if (!collapsed) fetchRequested = true;
+          setProp(body, "visible", !collapsed);
+          update();
+        }
+        const header = box({ flexDirection: "row", width: "100%", onMouseUp: () => toggle() }, [headerTitle, headerSummary]);
+        const body = box({ flexDirection: "column", width: "100%", visible: !collapsed }, [
+          box({ flexDirection: "row", width: "100%", justifyContent: "space-between" }, [txt({ fg: muted }, ["Plan"]), planVal]),
+          primary.block,
+          secondary.block,
+          extraOne.block,
+          extraTwo.block,
+          box({ flexDirection: "row", width: "100%", justifyContent: "space-between" }, [txt({ fg: muted }, ["Credits"]), creditsVal]),
+          box({ flexDirection: "row", width: "100%", justifyContent: "space-between" }, [txt({ fg: muted }, ["Resets"]), resetsVal]),
+          statusVal
+        ]);
+        const root = box({ flexDirection: "column", width: "100%" }, [header, body]);
+        update();
+        const timer = setInterval(update, RENDER_MS);
+        api.lifecycle.onDispose(() => clearInterval(timer));
+        return root;
+      }
+    }
+  });
+};
+const plugin = {
+  id: "codex-usage",
+  tui
+};
+var tui_default = plugin;
+export {
+  tui_default as default
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "opencode-codex-usage-tui",
+  "version": "1.3.2",
+  "description": "OpenCode TUI plugin that shows remaining ChatGPT Codex usage limits in the sidebar",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "esbuild src/tui.ts src/core.ts --outdir=dist --format=esm --platform=node --packages=external",
+    "check": "npm run build && node --check dist/tui.js && node --check dist/core.js",
+    "prepack": "npm run build"
+  },
+  "exports": {
+    "./tui": "./dist/tui.js"
+  },
+  "engines": {
+    "opencode": ">=1.14.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "devDependencies": {
+    "esbuild": "^0.25.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.14.0",
+    "@opentui/core": ">=0.2.6",
+    "@opentui/keymap": ">=0.2.6",
+    "@opentui/solid": ">=0.2.6"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": { "optional": true },
+    "@opentui/keymap": { "optional": true },
+    "@opentui/solid": { "optional": true }
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "codex",
+    "chatgpt",
+    "usage",
+    "limits",
+    "sidebar"
+  ],
+  "homepage": "https://github.com/ahmadmcer/opencode-codex-usage",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ahmadmcer/opencode-codex-usage.git"
+  }
+}