gusage 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdellah Hariti
+
+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,69 @@
+# gusage
+
+A standalone, sub-second CLI to export and monitor Gemini CLI quota and usage statistics.
+
+<p align="center">
+    <img src="assets/demo.png" width="500" />
+</p>
+
+This tool reverse-engineers the internal API handshakes used by the main Gemini CLI to fetch usage statistics.
+
+## Features
+
+- **Live Monitoring:** Real-time quota updates using the `--watch` flag.
+- **Machine Readable:** Supports JSON output for easy integration with other tools.
+- **Fast:** Returns results in sub-second time.
+- **Smart Sorting:** Automatically sorts models to highlight the ones you care about.
+- **Beautiful TUI**
+
+## Installation
+
+You can run it directly without installation using `npx` or `bunx`:
+
+```bash
+bunx gusage
+# or
+npx gusage
+```
+
+Or install it globally:
+
+```bash
+bun add -g gusage
+# or
+npm install -g gusage
+```
+
+## Usage
+
+```bash
+# Display quota in a beautiful table (default)
+gusage
+
+# Monitor quota live every 10 seconds
+gusage --watch
+
+# Monitor quota every 1 minute and 20 seconds
+gusage --watch 1m20s
+
+# Output raw JSON for scripting
+gusage -o json
+
+# Disable colors
+gusage --no-color
+```
+
+## Options
+
+- `-h, --help`: Show help message.
+- `-w, --watch [interval]`: Update live every interval (default: 10s). Supports units like `20s`, `5m`, `1m20s`.
+- `-o, --output-format <fmt>`: Set output format to `table` (default) or `json`.
+- `--no-color`: Disable color output (also respects `NO_COLOR` env var).
+
+## Requirements
+
+- **Authentication:** You must have already authenticated via the official Gemini CLI (`gemini login`).
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,378 @@
+#!/usr/bin/env bun
+// @bun
+
+// index.ts
+import fs from "fs";
+import path from "path";
+import os from "os";
+import crypto from "crypto";
+import { parseArgs } from "util";
+var OAUTH_CLIENT_ID = "681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com";
+var OAUTH_CLIENT_SECRET = "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";
+var CODE_ASSIST_ENDPOINT = "https://cloudcode-pa.googleapis.com";
+var CODE_ASSIST_API_VERSION = "v1internal";
+var GEMINI_DIR = ".gemini";
+var MAIN_ACCOUNT_KEY = "main-account";
+var ENCRYPTED_FILE_NAME = "mcp-oauth-tokens-v2.json";
+var LEGACY_OAUTH_FILE = "oauth_creds.json";
+var VALID_GEMINI_MODELS = new Set([
+  "gemini-3-pro-preview",
+  "gemini-3-flash-preview",
+  "gemini-2.5-pro",
+  "gemini-2.5-flash",
+  "gemini-2.5-flash-lite"
+]);
+var SEONDARY_MODELS = ["gemini-2.5-flash", "gemini-2.5-flash-lite"];
+function formatRelativeTime(dateString) {
+  const now = new Date;
+  const resetTime = new Date(dateString);
+  const diffMs = resetTime.getTime() - now.getTime();
+  if (diffMs <= 0)
+    return "Resetting...";
+  const diffMins = Math.floor(diffMs / 60000);
+  const h = Math.floor(diffMins / 60);
+  const m = diffMins % 60;
+  if (h > 0)
+    return `${h}h ${m}m`;
+  return `${m}m`;
+}
+function parseVersion(modelId) {
+  const match = modelId.match(/gemini-(\d+)(?:\.(\d+))?-(.*)/);
+  if (match) {
+    return {
+      major: parseInt(match[1], 10),
+      minor: match[2] ? parseInt(match[2], 10) : 0,
+      suffix: match[3] || ""
+    };
+  }
+  return { major: 0, minor: 0, suffix: modelId };
+}
+function renderProgressBar(fraction, width, useColor, isMuted = false) {
+  const BLOCKS = ["", "\u258F", "\u258E", "\u258D", "\u258C", "\u258B", "\u258A", "\u2589"];
+  const units = Math.round(Math.max(0, Math.min(1, fraction)) * width * 8);
+  const full = Math.floor(units / 8);
+  const rem = units % 8;
+  if (!useColor) {
+    let bar2 = "\u2588".repeat(full);
+    if (full < width) {
+      bar2 += BLOCKS[rem] || "";
+    }
+    const remaining = width - visualLength(bar2);
+    if (remaining > 0) {
+      bar2 += "\u2591".repeat(remaining);
+    }
+    return bar2;
+  }
+  const fillCol = fraction < 0.2 ? 160 : isMuted ? 244 : 15;
+  const trackCol = 237;
+  const fg = (n) => `\x1B[38;5;${n}m`;
+  const bg = (n) => `\x1B[48;5;${n}m`;
+  const reset = `\x1B[0m`;
+  let bar = bg(trackCol);
+  for (let i = 0;i < width; i++) {
+    if (i < full) {
+      bar += fg(fillCol) + "\u2588";
+    } else if (i === full && rem > 0) {
+      bar += fg(fillCol) + BLOCKS[rem];
+    } else {
+      bar += fg(trackCol) + "\u2588";
+    }
+  }
+  return bar + reset;
+}
+function visualLength(str) {
+  return str.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+function padVisual(str, width, side = "right") {
+  const len = visualLength(str);
+  const pad = " ".repeat(Math.max(0, width - len));
+  return side === "right" ? str + pad : pad + str;
+}
+async function main() {
+  const args = Bun.argv.slice(2);
+  const watchIdx = args.findIndex((a) => a === "--watch" || a === "-w");
+  if (watchIdx !== -1 && (watchIdx === args.length - 1 || args[watchIdx + 1].startsWith("-"))) {
+    args.splice(watchIdx + 1, 0, "10s");
+  }
+  const { values } = parseArgs({
+    args,
+    options: {
+      help: { type: "boolean", short: "h" },
+      "output-format": { type: "string", short: "o", default: "table" },
+      "no-color": { type: "boolean" },
+      watch: { type: "string", short: "w" }
+    },
+    strict: true
+  });
+  if (values.help) {
+    console.log(`
+Usage: gusage [options]
+
+Options:
+  -h, --help                Show this help message
+  -w, --watch [interval]    Update live every interval (default: 10s).
+                            Supports combined units: 20s, 5m, 1m20s.
+  -o, --output-format <fmt> Output format: table (default), json
+  --no-color                Disable color output
+    `);
+    return;
+  }
+  const outputFormat = values["output-format"];
+  if (outputFormat !== "json" && outputFormat !== "table") {
+    console.error(`Error: Unsupported output format "${outputFormat}". Use "table" or "json".`);
+    process.exit(1);
+  }
+  const isWatching = values.watch !== undefined;
+  let intervalMs = 1e4;
+  let intervalStr = "10s";
+  if (values.watch) {
+    let totalMs = 0;
+    const matches = values.watch.matchAll(/(\d+)(h|m|s)?/g);
+    let found = false;
+    for (const match of matches) {
+      found = true;
+      const val = parseInt(match[1], 10);
+      const unit = match[2] || "s";
+      if (unit === "s")
+        totalMs += val * 1000;
+      else if (unit === "m")
+        totalMs += val * 60000;
+      else if (unit === "h")
+        totalMs += val * 3600000;
+    }
+    if (found) {
+      intervalMs = totalMs;
+      intervalStr = values.watch;
+    }
+  }
+  const useColor = !values["no-color"] && !process.env.NO_COLOR && process.stdout.isTTY;
+  const colors = {
+    reset: useColor ? "\x1B[0m" : "",
+    dim: useColor ? "\x1B[2m" : "",
+    cyan: useColor ? "\x1B[36m" : "",
+    green: useColor ? "\x1B[32m" : "",
+    yellow: useColor ? "\x1B[33m" : "",
+    red: useColor ? "\x1B[31m" : "",
+    clear: useColor ? "\x1B[2J\x1B[H" : "",
+    hideCursor: useColor ? "\x1B[?25l" : "",
+    showCursor: useColor ? "\x1B[?25h" : ""
+  };
+  const cleanup = () => {
+    if (isWatching && process.stdin.isTTY) {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+    }
+    process.stdout.write(colors.showCursor);
+  };
+  const CTRL_C = "\x03";
+  const CTRL_D = "\x04";
+  if (isWatching && process.stdin.isTTY) {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on("data", (data) => {
+      const key = data.toString();
+      if (key === "q" || key === CTRL_C || key === CTRL_D) {
+        cleanup();
+        process.exit(0);
+      }
+    });
+    process.stdout.write(colors.hideCursor);
+  }
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+  const run = async () => {
+    const creds = loadLocalCredentials();
+    if (!creds) {
+      console.error('Error: No credentials found. Please run "gemini login" first.');
+      process.exit(1);
+    }
+    let token = creds.access_token;
+    const isExpired = creds.expiry_date && Date.now() > creds.expiry_date - 60000;
+    if (isExpired && creds.refresh_token) {
+      try {
+        const refreshed = await refreshAccessToken(creds.refresh_token);
+        token = refreshed.access_token;
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        console.error("Error: Failed to refresh access token.", message);
+      }
+    }
+    const baseUrl = `${CODE_ASSIST_ENDPOINT}/${CODE_ASSIST_API_VERSION}`;
+    const authHeader = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
+    const loadResponse = await fetch(`${baseUrl}:loadCodeAssist`, {
+      method: "POST",
+      headers: authHeader,
+      body: JSON.stringify({
+        metadata: { ideType: "GEMINI_CLI", platform: "PLATFORM_UNSPECIFIED", pluginType: "GEMINI" }
+      })
+    });
+    if (!loadResponse.ok) {
+      console.error(`Error: loadCodeAssist failed (${loadResponse.status})`);
+      process.exit(1);
+    }
+    const loadData = await loadResponse.json();
+    const projectId = loadData.cloudaicompanionProject || process.env["GOOGLE_CLOUD_PROJECT"];
+    if (!projectId) {
+      console.error("Error: Could not determine Project ID.");
+      process.exit(1);
+    }
+    const quotaResponse = await fetch(`${baseUrl}:retrieveUserQuota`, {
+      method: "POST",
+      headers: authHeader,
+      body: JSON.stringify({ project: projectId })
+    });
+    if (!quotaResponse.ok) {
+      console.error(`Error: retrieveUserQuota failed (${quotaResponse.status})`);
+      process.exit(1);
+    }
+    const quotaData = await quotaResponse.json();
+    if (quotaData.buckets) {
+      quotaData.buckets = quotaData.buckets.filter((b) => b.modelId && VALID_GEMINI_MODELS.has(b.modelId)).sort((a, b) => {
+        const vA = parseVersion(a.modelId);
+        const vB = parseVersion(b.modelId);
+        if (vA.major !== vB.major)
+          return vB.major - vA.major;
+        if (vA.minor !== vB.minor)
+          return vB.minor - vA.minor;
+        return vB.suffix.localeCompare(vA.suffix);
+      });
+    }
+    if (isWatching)
+      process.stdout.write(colors.clear);
+    if (outputFormat === "json") {
+      console.log(JSON.stringify(quotaData.buckets || [], null, 2));
+    } else {
+      if (!quotaData.buckets || quotaData.buckets.length === 0) {
+        console.log("No quota data available.");
+        return;
+      }
+      const headers = ["Gemini Model", "Remaining %", "Reset Time"];
+      const BAR_WIDTH = 20;
+      const terminalWidth = process.stdout.columns || 80;
+      const showBar = terminalWidth > 60;
+      const tableData = quotaData.buckets.map((b) => {
+        const fraction = b.remainingFraction ?? 0;
+        const isMuted = SEONDARY_MODELS.includes(b.modelId);
+        const model = b.modelId.replace("gemini-", "");
+        const bar = showBar ? renderProgressBar(fraction, BAR_WIDTH, useColor, isMuted) : "";
+        const pct = `${Math.round(fraction * 100)}%`.padStart(4);
+        const reset = b.resetTime ? formatRelativeTime(b.resetTime) : "N/A";
+        return { model, bar, pct, reset, isMuted };
+      });
+      const modelWidth = Math.max(headers[0].length, ...tableData.map((d) => d.model.length));
+      const remainingWidth = Math.max(headers[1].length, showBar ? BAR_WIDTH + 1 + 4 : 4);
+      const resetWidth = Math.max(headers[2].length, ...tableData.map((d) => d.reset.length));
+      const h0 = headers[0].padEnd(modelWidth);
+      const h1 = headers[1].padEnd(remainingWidth);
+      const h2 = headers[2].padEnd(resetWidth);
+      const headerRow = `${h0}    ${h1}    ${h2}`;
+      console.log(headerRow);
+      console.log(`${colors.dim}${"\u2500".repeat(visualLength(headerRow))}${colors.reset}`);
+      tableData.forEach((d, idx) => {
+        const modelLabel = d.isMuted ? `${colors.dim}${d.model}${colors.reset}` : d.model;
+        const m = padVisual(modelLabel, modelWidth);
+        const r_content = showBar ? `${d.bar} ${colors.dim}${d.pct}${colors.reset}` : `${colors.dim}${d.pct}${colors.reset}`;
+        const r = padVisual(r_content, remainingWidth);
+        const resetLabel = d.isMuted ? `${colors.dim}${d.reset}${colors.reset}` : d.reset;
+        const t = padVisual(resetLabel, resetWidth);
+        console.log(`${m}    ${r}    ${t}`);
+        if (idx < tableData.length - 1) {
+          console.log("");
+        }
+      });
+      if (isWatching) {
+        console.log(`
+${colors.dim}Updating every ${intervalStr}, press q to quit${colors.reset}`);
+      }
+    }
+  };
+  await run();
+  if (isWatching) {
+    setInterval(run, intervalMs);
+  }
+}
+if (import.meta.main) {
+  main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error("Fatal Error:", message);
+    process.exit(1);
+  });
+}
+function getGeminiDir() {
+  return path.join(os.homedir(), GEMINI_DIR);
+}
+function deriveEncryptionKey() {
+  const salt = `${os.hostname()}-${os.userInfo().username}-gemini-cli`;
+  return crypto.scryptSync("gemini-cli-oauth", salt, 32);
+}
+function decrypt(encryptedData, key) {
+  const parts = encryptedData.split(":");
+  if (parts.length !== 3) {
+    throw new Error("Invalid encrypted data format");
+  }
+  const ivHex = parts[0];
+  const authTagHex = parts[1];
+  const encrypted = parts[2];
+  const iv = Buffer.from(ivHex, "hex");
+  const authTag = Buffer.from(authTagHex, "hex");
+  const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAuthTag(authTag);
+  let decrypted = decipher.update(encrypted, "hex", "utf8");
+  decrypted += decipher.final("utf8");
+  return decrypted;
+}
+function loadLocalCredentials() {
+  const geminiDir = getGeminiDir();
+  const v2Path = path.join(geminiDir, ENCRYPTED_FILE_NAME);
+  if (fs.existsSync(v2Path)) {
+    try {
+      const data = fs.readFileSync(v2Path, "utf-8");
+      const key = deriveEncryptionKey();
+      const decrypted = decrypt(data, key);
+      const tokens = JSON.parse(decrypted);
+      const mainAccount = tokens[MAIN_ACCOUNT_KEY];
+      if (mainAccount && mainAccount.token) {
+        return {
+          access_token: mainAccount.token.accessToken,
+          refresh_token: mainAccount.token.refreshToken,
+          expiry_date: mainAccount.token.expiresAt,
+          token_type: mainAccount.token.tokenType
+        };
+      }
+    } catch (e) {}
+  }
+  const legacyPath = path.join(geminiDir, LEGACY_OAUTH_FILE);
+  if (fs.existsSync(legacyPath)) {
+    try {
+      return JSON.parse(fs.readFileSync(legacyPath, "utf-8"));
+    } catch (e) {}
+  }
+  return null;
+}
+async function refreshAccessToken(refreshToken) {
+  const url = "https://oauth2.googleapis.com/token";
+  const body = new URLSearchParams({
+    client_id: OAUTH_CLIENT_ID,
+    client_secret: OAUTH_CLIENT_SECRET,
+    refresh_token: refreshToken,
+    grant_type: "refresh_token"
+  });
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString()
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to refresh token: ${response.statusText}`);
+  }
+  return response.json();
+}
+export {
+  main as default
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "gusage",
+  "version": "1.0.0",
+  "description": "A standalone CLI to export Gemini CLI quota and usage statistics",
+  "module": "index.ts",
+  "type": "module",
+  "bin": {
+    "gusage": "dist/index.js"
+  },
+  "files": [
+    "dist/index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "Abdellah Hariti <haritiabdellah@gmail.com>",
+  "license": "MIT",
+  "private": false,
+  "scripts": {
+    "format": "prettier --write .",
+    "prepare": "husky",
+    "build": "bun build ./index.ts --outfile dist/index.js && chmod +x dist/index.js"
+  },
+  "lint-staged": {
+    "*": "prettier --write --ignore-unknown",
+    "*.ts": "bash -c 'bun x tsc --noEmit'"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.8.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}