agent-limit 0.3.0

package/README.md

@@ -0,0 +1,128 @@
+# agent-limit
+
+Terminal dashboard to monitor Claude Code, Codex, and Gemini CLI usage limits.
+
+## Install
+
+### Via npm (requires Bun)
+
+```bash
+npm install -g agent-limit
+```
+
+### Standalone Binary (no dependencies)
+
+Download from [GitHub Releases](https://github.com/AgentWorkforce/limit/releases):
+
+```bash
+# Apple Silicon
+curl -L https://github.com/AgentWorkforce/limit/releases/latest/download/agent-limit-darwin-arm64 -o /usr/local/bin/agent-limit
+chmod +x /usr/local/bin/agent-limit
+
+# Intel Mac
+curl -L https://github.com/AgentWorkforce/limit/releases/latest/download/agent-limit-darwin-x64 -o /usr/local/bin/agent-limit
+chmod +x /usr/local/bin/agent-limit
+```
+
+## Quick Start
+
+```bash
+agent-limit usage
+```
+
+## CLI
+
+| Command | Description |
+|---------|-------------|
+| `agent-limit usage` | Show usage dashboard |
+| `agent-limit help` | Show help message |
+
+## Dashboard Controls
+
+| Key | Action |
+|-----|--------|
+| `q` | Quit |
+| `r` | Refresh |
+
+## Features
+
+- Real-time usage tracking for Claude Code, Codex, and Gemini CLI
+- Trajectory markers showing if you're ahead or behind your usage pace
+- Auto-refresh every 60 seconds
+- Color-coded usage indicators
+
+## Supported Providers
+
+| Provider | Status | Data Source |
+|----------|--------|-------------|
+| Claude Code | Full support | macOS Keychain + Anthropic API |
+| Codex | Full support | `~/.codex/auth.json` + OpenAI API |
+| Gemini CLI | Static limits | `~/.gemini/settings.json` |
+
+## Development
+
+```bash
+git clone https://github.com/AgentWorkforce/limit.git
+cd monitor
+bun install
+```
+
+Run in development mode with hot reload:
+
+```bash
+bun run dev
+```
+
+Run directly:
+
+```bash
+bun run start
+```
+
+> **Note:** In dev mode, use `q` to quit cleanly. If you Ctrl-C and see garbled output, run `reset` to restore your terminal.
+
+### Building Standalone Binaries
+
+Build binaries that don't require Bun:
+
+```bash
+# Build for all macOS architectures
+bun run build
+
+# Build for specific architecture
+bun run build:arm64   # Apple Silicon
+bun run build:x64     # Intel
+```
+
+Binaries are output to `dist/`.
+
+## How It Works
+
+agent-limit reads credentials from standard locations:
+
+- **Claude Code**: macOS Keychain (`Claude Code-credentials`)
+- **Codex**: `~/.codex/auth.json`
+- **Gemini**: `~/.gemini/settings.json`
+
+It then fetches usage data from each provider's API and displays it in a unified dashboard.
+
+### Trajectory Indicator
+
+Each progress bar shows a `|` marker indicating where your usage "should be" based on time elapsed in the reset period:
+
+```
+[███████░░░░|░░░░░░░░░] 30% ↓12%
+            ^ you should be at 42%, but you're at 30% (12% under pace)
+```
+
+- `↓X%` (green) = under pace, you have headroom
+- `↑X%` (red) = over pace, might hit limits early
+
+## Requirements
+
+- macOS (uses Keychain for credential storage)
+- Active CLI authentication for providers you want to monitor
+
+## License
+
+MIT

package/bin/cli.tsx

@@ -0,0 +1,61 @@
+#!/usr/bin/env bun
+/** @jsxImportSource @opentui/react */
+
+import { createRoot } from "@opentui/react";
+import { App } from "../src/App";
+
+function resetTerminal() {
+  process.stdout.write("\x1b[?1049l");
+  process.stdout.write("\x1b[?25h");
+  process.stdout.write("\x1b[0m");
+  process.stdout.write("\x1b[?1000l");
+  process.stdout.write("\x1b[?1002l");
+  process.stdout.write("\x1b[?1003l");
+  process.stdout.write("\x1b[?1006l");
+  process.stdout.write("\x1b[?2004l");
+}
+
+const command = process.argv[2];
+
+if (command === "usage") {
+  let root: ReturnType<typeof createRoot> | null = null;
+  
+  const cleanup = () => {
+    if (root) {
+      root.unmount();
+    }
+    resetTerminal();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+  process.on("exit", resetTerminal);
+  
+  root = createRoot(process.stdout, { hideCursor: true });
+  root.render(<App onExit={cleanup} />);
+} else if (command === "help" || command === "--help" || command === "-h" || !command) {
+  console.log(`
+agent-monitor
+
+Monitor AI agent CLI usage limits in real-time.
+
+Install:
+  npm install -g agent-monitor
+
+Quick Start:
+  agent-monitor usage
+
+CLI:
+  agent-monitor usage    Show usage dashboard
+  agent-monitor help     Show this help message
+
+Dashboard Controls:
+  q    Quit
+  r    Refresh
+`);
+} else {
+  console.error(`Unknown command: ${command}`);
+  console.error(`Run 'agent-monitor help' for usage.`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "agent-limit",
+  "version": "0.3.0",
+  "description": "Terminal dashboard to monitor Claude Code, Codex, and other agent usage limits",
+  "type": "module",
+  "main": "src/index.tsx",
+  "bin": {
+    "agent-limit": "./bin/cli.tsx"
+  },
+  "scripts": {
+    "start": "bun run src/index.tsx",
+    "dev": "bun --watch run src/index.tsx",
+    "build": "bun build --compile --target=bun-darwin-arm64 ./bin/cli.tsx --outfile=dist/agent-limit-darwin-arm64 && bun build --compile --target=bun-darwin-x64 ./bin/cli.tsx --outfile=dist/agent-limit-darwin-x64",
+    "build:arm64": "bun build --compile --target=bun-darwin-arm64 ./bin/cli.tsx --outfile=dist/agent-limit-darwin-arm64",
+    "build:x64": "bun build --compile --target=bun-darwin-x64 ./bin/cli.tsx --outfile=dist/agent-limit-darwin-x64"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "keywords": [
+    "cli",
+    "terminal",
+    "dashboard",
+    "claude",
+    "codex",
+    "gemini",
+    "ai",
+    "agent",
+    "usage",
+    "limits",
+    "monitor",
+    "tui"
+  ],
+  "author": "Will Washburn",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentWorkforce/limit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AgentWorkforce/limit/issues"
+  },
+  "homepage": "https://github.com/AgentWorkforce/limit",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "os": [
+    "darwin"
+  ],
+  "dependencies": {
+    "@opentui/core": "^0.1.67",
+    "@opentui/react": "^0.1.63",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/App.tsx

@@ -0,0 +1,64 @@
+import { useEffect, useState, useCallback } from "react";
+import { useKeyboard } from "@opentui/react";
+import { Header, Footer, Dashboard } from "./components";
+import { fetchAllProviders, type ProviderStatus } from "./providers";
+
+const REFRESH_INTERVAL = 60000;
+
+interface AppProps {
+  onExit?: () => void;
+}
+
+export function App({ onExit }: AppProps) {
+  const [providers, setProviders] = useState<ProviderStatus[]>([
+    { provider: "claude", status: "loading", metrics: [] },
+    { provider: "codex", status: "loading", metrics: [] },
+    { provider: "gemini", status: "loading", metrics: [] },
+  ]);
+  const [lastRefresh, setLastRefresh] = useState<Date | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+
+  const refresh = useCallback(async () => {
+    setIsLoading(true);
+    try {
+      const results = await fetchAllProviders();
+      setProviders(results);
+      setLastRefresh(new Date());
+    } catch (err) {
+      console.error("Failed to fetch providers:", err);
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    refresh();
+    const interval = setInterval(refresh, REFRESH_INTERVAL);
+    return () => clearInterval(interval);
+  }, [refresh]);
+
+  useKeyboard((key) => {
+    if (key.name === "q" || (key.ctrl && key.name === "c")) {
+      onExit?.();
+    }
+
+    if (key.name === "r") {
+      refresh();
+    }
+  });
+
+  return (
+    <box
+      style={{
+        width: "100%",
+        height: "100%",
+        flexDirection: "column",
+        backgroundColor: "#0a0a0f",
+      }}
+    >
+      <Header lastRefresh={lastRefresh} isLoading={isLoading} />
+      <Dashboard providers={providers} />
+      <Footer />
+    </box>
+  );
+}

package/src/components/Dashboard.tsx

@@ -0,0 +1,23 @@
+import type { ProviderStatus } from "../providers/types";
+import { ProviderCard } from "./ProviderCard";
+
+interface DashboardProps {
+  providers: ProviderStatus[];
+}
+
+export function Dashboard({ providers }: DashboardProps) {
+  return (
+    <box
+      style={{
+        flexGrow: 1,
+        flexDirection: "row",
+        gap: 1,
+        padding: 1,
+      }}
+    >
+      {providers.map((provider) => (
+        <ProviderCard key={provider.provider} data={provider} />
+      ))}
+    </box>
+  );
+}

package/src/components/Footer.tsx

@@ -0,0 +1,19 @@
+export function Footer() {
+  return (
+    <box
+      style={{
+        width: "100%",
+        height: 1,
+        flexDirection: "row",
+        paddingLeft: 2,
+        paddingRight: 2,
+      }}
+    >
+      <text fg="#6b7280">
+        <span fg="#9ca3af">q</span>: quit{"  "}
+        <span fg="#9ca3af">r</span>: refresh{"  "}
+        <span fg="#9ca3af">?</span>: help
+      </text>
+    </box>
+  );
+}

package/src/components/Header.tsx

@@ -0,0 +1,41 @@
+interface HeaderProps {
+  lastRefresh: Date | null;
+  isLoading: boolean;
+}
+
+function formatTime(date: Date): string {
+  return date.toLocaleTimeString("en-US", {
+    hour: "numeric",
+    minute: "2-digit",
+    hour12: true,
+  });
+}
+
+export function Header({ lastRefresh, isLoading }: HeaderProps) {
+  const refreshText = isLoading
+    ? "Refreshing..."
+    : lastRefresh
+      ? `Last refresh: ${formatTime(lastRefresh)}`
+      : "Loading...";
+
+  return (
+    <box
+      style={{
+        width: "100%",
+        height: 3,
+        flexDirection: "row",
+        justifyContent: "space-between",
+        alignItems: "center",
+        paddingLeft: 2,
+        paddingRight: 2,
+        borderStyle: "single",
+        borderColor: "#0f3460",
+      }}
+    >
+      <text fg="#e5e5e5">
+        <span fg="#3b82f6">AI Limits Monitor</span>
+      </text>
+      <text fg="#6b7280">{refreshText}</text>
+    </box>
+  );
+}

package/src/components/ProgressBar.tsx

@@ -0,0 +1,81 @@
+import { getUsageColor } from "../utils/colors";
+
+interface ProgressBarProps {
+  percentage: number;
+  width?: number;
+  showLabel?: boolean;
+  periodSeconds?: number;
+  resetsAt?: string | null;
+}
+
+function calculateTrajectory(periodSeconds: number, resetsAt: string): number {
+  const resetTime = new Date(resetsAt).getTime();
+  const now = Date.now();
+  const secondsRemaining = Math.max(0, (resetTime - now) / 1000);
+  const elapsedSeconds = periodSeconds - secondsRemaining;
+  return Math.min(100, Math.max(0, (elapsedSeconds / periodSeconds) * 100));
+}
+
+export function ProgressBar({ 
+  percentage, 
+  width = 10, 
+  showLabel = true,
+  periodSeconds,
+  resetsAt,
+}: ProgressBarProps) {
+  if (percentage < 0) {
+    return <text fg="#6b7280">N/A</text>;
+  }
+
+  const color = getUsageColor(percentage);
+  const filledCount = Math.round((percentage / 100) * width);
+  
+  const canShowTrajectory = periodSeconds && resetsAt;
+  const trajectoryPercent = canShowTrajectory 
+    ? calculateTrajectory(periodSeconds, resetsAt) 
+    : null;
+  const trajectoryPos = trajectoryPercent !== null 
+    ? Math.round((trajectoryPercent / 100) * width) 
+    : null;
+
+  const delta = trajectoryPercent !== null ? percentage - trajectoryPercent : null;
+  
+  let deltaText = "";
+  let deltaColor = "#6b7280";
+  if (delta !== null) {
+    const absDelta = Math.abs(Math.round(delta));
+    if (delta < -1) {
+      deltaText = ` ↓${absDelta}%`;
+      deltaColor = "#22c55e";
+    } else if (delta > 1) {
+      deltaText = ` ↑${absDelta}%`;
+      deltaColor = "#ef4444";
+    } else {
+      deltaText = ` ±0%`;
+      deltaColor = "#6b7280";
+    }
+  }
+
+  const barChars: Array<{ char: string; color: string }> = [];
+  for (let i = 0; i < width; i++) {
+    if (trajectoryPos !== null && i === trajectoryPos) {
+      barChars.push({ char: "|", color: "#6b7280" });
+    } else if (i < filledCount) {
+      barChars.push({ char: "█", color });
+    } else {
+      barChars.push({ char: "░", color: "#4b5563" });
+    }
+  }
+
+  const label = showLabel ? ` ${Math.round(percentage)}%` : "";
+
+  return (
+    <text>
+      {barChars.map((c, i) => (
+        <span key={i} fg={c.color}>{c.char}</span>
+      ))}
+      <span fg={color}>{label}</span>
+      <span fg={deltaColor}>{deltaText}</span>
+    </text>
+  );
+}

package/src/components/ProviderCard.tsx

@@ -0,0 +1,82 @@
+import type { ProviderStatus } from "../providers/types";
+import { PROVIDER_COLORS, getStatusColor } from "../utils/colors";
+import { ProgressBar } from "./ProgressBar";
+
+interface ProviderCardProps {
+  data: ProviderStatus;
+}
+
+function getProviderDisplayName(provider: string): string {
+  switch (provider) {
+    case "claude": return "CLAUDE CODE";
+    case "codex": return "CODEX";
+    case "gemini": return "GEMINI CLI";
+    default: return provider.toUpperCase();
+  }
+}
+
+export function ProviderCard({ data }: ProviderCardProps) {
+  const providerColor = PROVIDER_COLORS[data.provider] || "#9ca3af";
+  const statusColor = getStatusColor(data.status);
+
+  return (
+    <box
+      style={{
+        flexGrow: 1,
+        flexBasis: 0,
+        minWidth: 20,
+        border: true,
+        borderStyle: "single",
+        borderColor: "#0f3460",
+        padding: 1,
+        flexDirection: "column",
+        gap: 1,
+      }}
+    >
+      <box style={{ flexDirection: "row", justifyContent: "space-between" }}>
+        <text fg={providerColor}>
+          <strong>{getProviderDisplayName(data.provider)}</strong>
+        </text>
+        {data.plan && <text fg="#6b7280">{data.plan}</text>}
+      </box>
+
+      {data.status === "unavailable" || data.status === "error" ? (
+        <box style={{ flexDirection: "column", gap: 1, marginTop: 1 }}>
+          {data.error && <text fg="#ef4444">{data.error}</text>}
+          {data.message && <text fg="#6b7280">{data.message}</text>}
+        </box>
+      ) : data.status === "limited" ? (
+        <box style={{ flexDirection: "column", gap: 1, marginTop: 1 }}>
+          {data.metrics.map((metric, i) => (
+            <box key={i} style={{ flexDirection: "column" }}>
+              <text fg="#9ca3af">{metric.name}</text>
+              <text fg="#e5e5e5">{metric.resetsIn}</text>
+            </box>
+          ))}
+          {data.message && (
+            <text fg="#6b7280" style={{ marginTop: 1 }}>
+              {data.message}
+            </text>
+          )}
+        </box>
+      ) : (
+        <box style={{ flexDirection: "column", gap: 1, marginTop: 1 }}>
+          {data.metrics.map((metric, i) => (
+            <box key={i} style={{ flexDirection: "column" }}>
+              <text fg="#9ca3af">{metric.name}</text>
+              <box style={{ flexDirection: "row", alignItems: "center", gap: 1 }}>
+                <ProgressBar 
+                  percentage={metric.percentage} 
+                  width={12} 
+                  periodSeconds={metric.periodSeconds}
+                  resetsAt={metric.resetsAt}
+                />
+              </box>
+              <text fg="#6b7280">Resets: {metric.resetsIn}</text>
+            </box>
+          ))}
+        </box>
+      )}
+    </box>
+  );
+}

package/src/components/index.ts

@@ -0,0 +1,5 @@
+export { Header } from "./Header";
+export { Footer } from "./Footer";
+export { Dashboard } from "./Dashboard";
+export { ProviderCard } from "./ProviderCard";
+export { ProgressBar } from "./ProgressBar";

package/src/index.tsx

@@ -0,0 +1,41 @@
+import { createCliRenderer } from "@opentui/core";
+import { createRoot } from "@opentui/react";
+import { App } from "./App";
+
+function resetTerminal() {
+  process.stdout.write("\x1b[?1049l");
+  process.stdout.write("\x1b[?25h");
+  process.stdout.write("\x1b[0m");
+  process.stdout.write("\x1b[?1000l");
+  process.stdout.write("\x1b[?1002l");
+  process.stdout.write("\x1b[?1003l");
+  process.stdout.write("\x1b[?1006l");
+  process.stdout.write("\x1b[?2004l");
+}
+
+async function main() {
+  const renderer = await createCliRenderer({
+    exitOnCtrlC: false,
+  });
+
+  const root = createRoot(renderer);
+  
+  const cleanup = () => {
+    root.unmount();
+    renderer.stop();
+    resetTerminal();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+  process.on("exit", resetTerminal);
+
+  root.render(<App onExit={cleanup} />);
+  renderer.start();
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/src/providers/claude.ts

@@ -0,0 +1,102 @@
+import { getClaudeCredentials } from "../utils/keychain";
+import { timeUntil } from "../utils/time";
+import type { ProviderStatus } from "./types";
+
+interface ClaudeUsageResponse {
+  five_hour: { utilization: number; resets_at: string | null } | null;
+  seven_day: { utilization: number; resets_at: string | null } | null;
+  seven_day_opus: { utilization: number; resets_at: string | null } | null;
+}
+
+export async function fetchClaudeUsage(): Promise<ProviderStatus> {
+  const credentials = await getClaudeCredentials();
+
+  if (!credentials) {
+    return {
+      provider: "claude",
+      status: "unavailable",
+      metrics: [],
+      message: "Not logged in. Run 'claude' to authenticate.",
+    };
+  }
+
+  try {
+    const response = await fetch("https://api.anthropic.com/api/oauth/usage", {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        "User-Agent": "monitor/1.0.0",
+        Authorization: `Bearer ${credentials.accessToken}`,
+        "anthropic-beta": "oauth-2025-04-20",
+      },
+    });
+
+    if (!response.ok) {
+      if (response.status === 401) {
+        return {
+          provider: "claude",
+          status: "error",
+          metrics: [],
+          error: "Token expired. Run 'claude' to re-authenticate.",
+        };
+      }
+      return {
+        provider: "claude",
+        status: "error",
+        metrics: [],
+        error: `API error: ${response.status}`,
+      };
+    }
+
+    const data: ClaudeUsageResponse = await response.json();
+    const metrics = [];
+
+    if (data.five_hour) {
+      metrics.push({
+        name: "5-Hour",
+        percentage: data.five_hour.utilization,
+        resetsAt: data.five_hour.resets_at,
+        resetsIn: timeUntil(data.five_hour.resets_at),
+        periodSeconds: 5 * 3600,
+      });
+    }
+
+    if (data.seven_day) {
+      metrics.push({
+        name: "Weekly",
+        percentage: data.seven_day.utilization,
+        resetsAt: data.seven_day.resets_at,
+        resetsIn: timeUntil(data.seven_day.resets_at),
+        periodSeconds: 7 * 24 * 3600,
+      });
+    }
+
+    if (data.seven_day_opus && data.seven_day_opus.utilization > 0) {
+      metrics.push({
+        name: "Opus",
+        percentage: data.seven_day_opus.utilization,
+        resetsAt: data.seven_day_opus.resets_at,
+        resetsIn: timeUntil(data.seven_day_opus.resets_at),
+        periodSeconds: 7 * 24 * 3600,
+      });
+    }
+
+    const maxUsage = Math.max(...metrics.map((m) => m.percentage), 0);
+    const status = maxUsage >= 80 ? "warning" : "ok";
+
+    return {
+      provider: "claude",
+      status,
+      plan: credentials.subscriptionType || "Pro",
+      metrics,
+    };
+  } catch (err) {
+    return {
+      provider: "claude",
+      status: "error",
+      metrics: [],
+      error: err instanceof Error ? err.message : "Unknown error",
+    };
+  }
+}

package/src/providers/codex.ts

@@ -0,0 +1,113 @@
+import { getCodexCredentials } from "../utils/keychain";
+import { formatDuration } from "../utils/time";
+import type { ProviderStatus } from "./types";
+
+interface RateLimitWindow {
+  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?: RateLimitWindow;
+    secondary_window?: RateLimitWindow;
+  };
+}
+
+export async function fetchCodexUsage(): Promise<ProviderStatus> {
+  const credentials = await getCodexCredentials();
+
+  if (!credentials) {
+    return {
+      provider: "codex",
+      status: "unavailable",
+      metrics: [],
+      message: "Not logged in. Run 'codex' to authenticate.",
+    };
+  }
+
+  try {
+    const response = await fetch(
+      "https://chatgpt.com/backend-api/wham/usage",
+      {
+        headers: {
+          Authorization: `Bearer ${credentials.accessToken}`,
+          "ChatGPT-Account-Id": credentials.accountId,
+          "originator": "codex_cli_rs",
+          "User-Agent": "codex_cli_rs/0.77.0",
+        },
+      }
+    );
+
+    if (!response.ok) {
+      if (response.status === 401) {
+        return {
+          provider: "codex",
+          status: "error",
+          metrics: [],
+          message: "Token expired. Run 'codex' to re-authenticate.",
+        };
+      }
+      return {
+        provider: "codex",
+        status: "error",
+        metrics: [],
+        message: `API error: ${response.status}`,
+      };
+    }
+
+    const data: CodexUsageResponse = await response.json();
+    const metrics = [];
+
+    if (data.rate_limit?.primary_window) {
+      const primary = data.rate_limit.primary_window;
+      const windowHours = Math.round(primary.limit_window_seconds / 3600);
+      const resetMs = primary.reset_after_seconds * 1000;
+      metrics.push({
+        name: `${windowHours}h Usage`,
+        percentage: primary.used_percent,
+        resetsAt: new Date(primary.reset_at * 1000).toISOString(),
+        resetsIn: formatDuration(resetMs),
+        periodSeconds: primary.limit_window_seconds,
+      });
+    }
+
+    if (data.rate_limit?.secondary_window) {
+      const secondary = data.rate_limit.secondary_window;
+      const windowDays = Math.round(secondary.limit_window_seconds / 86400);
+      const resetMs = secondary.reset_after_seconds * 1000;
+      metrics.push({
+        name: windowDays >= 7 ? "Weekly" : `${windowDays}d Usage`,
+        percentage: secondary.used_percent,
+        resetsAt: new Date(secondary.reset_at * 1000).toISOString(),
+        resetsIn: formatDuration(resetMs),
+        periodSeconds: secondary.limit_window_seconds,
+      });
+    }
+
+    const planLabel = data.plan_type
+      ? data.plan_type.charAt(0).toUpperCase() + data.plan_type.slice(1)
+      : "Unknown";
+
+    const maxUsage = Math.max(...metrics.map((m) => m.percentage), 0);
+
+    return {
+      provider: "codex",
+      status: data.rate_limit?.limit_reached || maxUsage >= 80 ? "warning" : "ok",
+      metrics,
+      plan: planLabel,
+    };
+  } catch (error) {
+    return {
+      provider: "codex",
+      status: "error",
+      metrics: [],
+      message: error instanceof Error ? error.message : "Failed to fetch usage",
+    };
+  }
+}

package/src/providers/gemini.ts

@@ -0,0 +1,63 @@
+import { getGeminiSettings } from "../utils/keychain";
+import type { ProviderStatus, UsageMetric } from "./types";
+
+interface GeminiLimits {
+  requestsPerDay: number;
+  requestsPerMinute: number;
+  plan: string;
+}
+
+function getLimitsForAuthType(authType?: string): GeminiLimits {
+  switch (authType) {
+    case "google":
+      return { requestsPerDay: 1000, requestsPerMinute: 60, plan: "Google (Free)" };
+    case "api_key":
+      return { requestsPerDay: 250, requestsPerMinute: 10, plan: "API Key (Free)" };
+    case "vertex":
+      return { requestsPerDay: -1, requestsPerMinute: -1, plan: "Vertex AI" };
+    default:
+      return { requestsPerDay: 1000, requestsPerMinute: 60, plan: "Unknown" };
+  }
+}
+
+export async function fetchGeminiUsage(): Promise<ProviderStatus> {
+  const settings = await getGeminiSettings();
+
+  if (!settings) {
+    return {
+      provider: "gemini",
+      status: "unavailable",
+      metrics: [],
+      message: "Not configured. Run 'gemini' to set up.",
+    };
+  }
+
+  const limits = getLimitsForAuthType(settings.authType);
+  const metrics: UsageMetric[] = [];
+
+  if (limits.requestsPerDay > 0) {
+    metrics.push({
+      name: "Daily Limit",
+      percentage: -1,
+      resetsAt: null,
+      resetsIn: `${limits.requestsPerDay} req/day`,
+    });
+  }
+
+  if (limits.requestsPerMinute > 0) {
+    metrics.push({
+      name: "Per-Minute",
+      percentage: -1,
+      resetsAt: null,
+      resetsIn: `${limits.requestsPerMinute} req/min`,
+    });
+  }
+
+  return {
+    provider: "gemini",
+    status: "limited",
+    plan: limits.plan,
+    metrics,
+    message: "Live usage not available. Run /stats in Gemini CLI.",
+  };
+}

package/src/providers/index.ts

@@ -0,0 +1,19 @@
+export * from "./types";
+export { fetchClaudeUsage } from "./claude";
+export { fetchCodexUsage } from "./codex";
+export { fetchGeminiUsage } from "./gemini";
+
+import { fetchClaudeUsage } from "./claude";
+import { fetchCodexUsage } from "./codex";
+import { fetchGeminiUsage } from "./gemini";
+import type { ProviderStatus } from "./types";
+
+export async function fetchAllProviders(): Promise<ProviderStatus[]> {
+  const [claude, codex, gemini] = await Promise.all([
+    fetchClaudeUsage(),
+    fetchCodexUsage(),
+    fetchGeminiUsage(),
+  ]);
+
+  return [claude, codex, gemini];
+}

package/src/providers/types.ts

@@ -0,0 +1,24 @@
+export type ProviderName = "claude" | "codex" | "gemini";
+
+export type ProviderStatusType = "ok" | "warning" | "error" | "unavailable" | "loading" | "limited";
+
+export interface UsageMetric {
+  name: string;
+  percentage: number;
+  resetsAt: string | null;
+  resetsIn: string;
+  periodSeconds?: number; // Total window duration for trajectory calculation
+}
+
+export interface ProviderStatus {
+  provider: ProviderName;
+  status: ProviderStatusType;
+  plan?: string;
+  metrics: UsageMetric[];
+  message?: string;
+  error?: string;
+}
+
+export interface ProviderFetcher {
+  fetch(): Promise<ProviderStatus>;
+}

package/src/utils/colors.ts

@@ -0,0 +1,31 @@
+export function getUsageColor(percentage: number): string {
+  if (percentage < 50) return "#22c55e";
+  if (percentage < 80) return "#eab308";
+  return "#ef4444";
+}
+
+export function getStatusColor(status: string): string {
+  switch (status) {
+    case "ok": return "#22c55e";
+    case "warning": return "#eab308";
+    case "error": return "#ef4444";
+    case "unavailable": return "#6b7280";
+    case "limited": return "#3b82f6";
+    default: return "#9ca3af";
+  }
+}
+
+export const PROVIDER_COLORS = {
+  claude: "#d97706",
+  codex: "#10b981",
+  gemini: "#3b82f6",
+} as const;
+
+export const UI_COLORS = {
+  background: "#1a1a2e",
+  surface: "#16213e",
+  border: "#0f3460",
+  text: "#e5e5e5",
+  textMuted: "#9ca3af",
+  textDim: "#6b7280",
+} as const;

package/src/utils/keychain.ts

@@ -0,0 +1,106 @@
+import { $ } from "bun";
+
+export async function getKeychainCredentials(service: string): Promise<string | null> {
+  try {
+    const result = await $`security find-generic-password -s ${service} -w`
+      .quiet()
+      .text();
+    return result.trim();
+  } catch {
+    return null;
+  }
+}
+
+export interface ClaudeCredentials {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+  scopes: string[];
+  subscriptionType: string;
+}
+
+export async function getClaudeCredentials(): Promise<ClaudeCredentials | null> {
+  try {
+    const raw = await getKeychainCredentials("Claude Code-credentials");
+    if (!raw) return null;
+
+    const parsed = JSON.parse(raw);
+    return parsed.claudeAiOauth || null;
+  } catch {
+    return null;
+  }
+}
+
+export interface CodexCredentials {
+  accessToken: string;
+  accountId: string;
+  planType?: string;
+}
+
+function decodeJwtPayload(token: string): Record<string, unknown> | null {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) return null;
+    const payload = Buffer.from(parts[1], "base64").toString("utf-8");
+    return JSON.parse(payload);
+  } catch {
+    return null;
+  }
+}
+
+export async function getCodexCredentials(): Promise<CodexCredentials | null> {
+  try {
+    const homedir = process.env.HOME || "~";
+    const file = Bun.file(`${homedir}/.codex/auth.json`);
+    
+    if (!(await file.exists())) {
+      return null;
+    }
+
+    const content = await file.json();
+    const tokens = content.tokens;
+    
+    if (!tokens?.access_token || !tokens?.account_id) {
+      return null;
+    }
+
+    let planType: string | undefined;
+    const payload = decodeJwtPayload(tokens.access_token);
+    if (payload) {
+      const auth = payload["https://api.openai.com/auth"] as Record<string, unknown> | undefined;
+      if (auth?.chatgpt_plan_type) {
+        planType = String(auth.chatgpt_plan_type);
+      }
+    }
+
+    return {
+      accessToken: tokens.access_token,
+      accountId: tokens.account_id,
+      planType,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export interface GeminiSettings {
+  authType?: "google" | "api_key" | "vertex";
+  apiKey?: string;
+  project?: string;
+}
+
+export async function getGeminiSettings(): Promise<GeminiSettings | null> {
+  try {
+    const homedir = process.env.HOME || "~";
+    const file = Bun.file(`${homedir}/.gemini/settings.json`);
+    
+    if (!(await file.exists())) {
+      return null;
+    }
+
+    const content = await file.json();
+    return content;
+  } catch {
+    return null;
+  }
+}

package/src/utils/time.ts

@@ -0,0 +1,94 @@
+export function formatDuration(ms: number): string {
+  if (ms < 0) return "now";
+
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) {
+    const remainingHours = hours % 24;
+    if (remainingHours > 0) {
+      return `${days}d ${remainingHours}h`;
+    }
+    return `${days}d`;
+  }
+
+  if (hours > 0) {
+    const remainingMinutes = minutes % 60;
+    if (remainingMinutes > 0) {
+      return `${hours}h ${remainingMinutes}m`;
+    }
+    return `${hours}h`;
+  }
+
+  if (minutes > 0) {
+    return `${minutes}m`;
+  }
+
+  return `${seconds}s`;
+}
+
+export function timeUntil(isoDate: string | null): string {
+  if (!isoDate) return "unknown";
+
+  try {
+    const target = new Date(isoDate).getTime();
+    const now = Date.now();
+    const diff = target - now;
+
+    if (diff <= 0) return "now";
+    return formatDuration(diff);
+  } catch {
+    return "unknown";
+  }
+}
+
+export function formatDate(isoDate: string | null): string {
+  if (!isoDate) return "unknown";
+
+  try {
+    const date = new Date(isoDate);
+    const now = new Date();
+
+    const isSameDay = date.toDateString() === now.toDateString();
+    if (isSameDay) {
+      return date.toLocaleTimeString("en-US", {
+        hour: "numeric",
+        minute: "2-digit",
+        hour12: true,
+      });
+    }
+
+    const daysDiff = Math.floor((date.getTime() - now.getTime()) / (1000 * 60 * 60 * 24));
+    const isWithinWeek = daysDiff >= 0 && daysDiff < 7;
+    if (isWithinWeek) {
+      return date.toLocaleDateString("en-US", {
+        weekday: "short",
+        hour: "numeric",
+        minute: "2-digit",
+        hour12: true,
+      });
+    }
+
+    return date.toLocaleDateString("en-US", {
+      month: "short",
+      day: "numeric",
+      hour: "numeric",
+      minute: "2-digit",
+    });
+  } catch {
+    return "unknown";
+  }
+}
+
+export function timeAgo(date: Date): string {
+  const now = Date.now();
+  const diff = now - date.getTime();
+
+  if (diff < 1000) return "just now";
+  if (diff < 60000) return `${Math.floor(diff / 1000)}s ago`;
+  if (diff < 3600000) return `${Math.floor(diff / 60000)}m ago`;
+  if (diff < 86400000) return `${Math.floor(diff / 3600000)}h ago`;
+  return `${Math.floor(diff / 86400000)}d ago`;
+}