gusage 1.1.0 → 1.1.2

package/README.md

@@ -11,6 +11,7 @@ This tool reverse-engineers the internal API handshakes used by the main Gemini
 ## Features
 
 - **Live Monitoring:** Real-time quota updates using the `--watch` flag.
+- **Low-Quota Alerts:** Optional desktop notifications with `--notify` when usage drops below a threshold.
 - **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.
@@ -46,6 +47,12 @@ gusage --watch
 # Monitor quota every 1 minute and 20 seconds
 gusage --watch 1m20s
 
+# Monitor quota and notify when any model falls below 20% (default threshold)
+gusage --watch --notify
+
+# Monitor quota and notify when any model falls below 15%
+gusage --watch 30s --notify 15
+
 # Output raw JSON for scripting
 gusage --json | jq .
 
@@ -57,12 +64,14 @@ gusage --json --watch 5s | jq .
 
 - `-h, --help`: Show help message.
 - `-w, --watch [interval]`: Update live every interval (default: 10s). Supports units like `20s`, `5m`, `1m20s`.
+- `-n, --notify [threshold]`: Send a desktop notification when a model drops below the threshold percent (default: `20`). Requires `--watch`.
 - `-j, --json`: Output raw JSON instead of a table. Can be combined with `--watch` for streaming data.
 - `--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`).
+- **Notifications (Linux only):** `notify-send` must be installed when using `--notify`.
 
 ## License
 

package/dist/index.js

@@ -7,6 +7,7 @@ import path from "path";
 import os from "os";
 import crypto from "crypto";
 import { parseArgs } from "util";
+import { execSync, spawn } from "child_process";
 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";
@@ -36,6 +37,56 @@ function formatRelativeTime(dateString) {
     return `${h}h ${m}m`;
   return `${m}m`;
 }
+function sendNotification(title, message) {
+  const spawnDetached = (command, args) => {
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.on("error", () => {});
+    child.unref();
+  };
+  if (process.platform === "darwin") {
+    const escapedMessage = message.replace(/"/g, "\\\"");
+    const escapedTitle = title.replace(/"/g, "\\\"");
+    const script = `display notification "${escapedMessage}" with title "${escapedTitle}"`;
+    spawnDetached("osascript", ["-e", script]);
+  } else if (process.platform === "linux") {
+    spawnDetached("notify-send", [title, message]);
+  } else if (process.platform === "win32") {
+    const command = `Add-Type -AssemblyName System.Windows.Forms; $g = [System.Windows.Forms.NotifyIcon]::new(); $g.Icon = [System.Drawing.Icon]::ExtractAssociatedIcon("$PSHOME\\powershell.exe"); $g.Visible = $true; $g.ShowBalloonTip(5000, "${title.replace(/"/g, '`"')}", "${message.replace(/"/g, '`"')}", [System.Windows.Forms.ToolTipIcon]::Info);`;
+    spawnDetached("powershell", ["-Command", command]);
+  }
+}
+function checkNotificationSupport() {
+  if (process.platform === "linux") {
+    try {
+      execSync("which notify-send", { stdio: "ignore" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+function parseNotifyThresholdArg(raw) {
+  if (raw === undefined)
+    return null;
+  const thresholdPct = Number(raw);
+  if (!Number.isFinite(thresholdPct) || thresholdPct < 0 || thresholdPct > 100) {
+    throw new Error("Error: --notify threshold must be a number between 0 and 100.");
+  }
+  return thresholdPct / 100;
+}
+function validateNotifyRuntime(notifyThreshold, isWatching, hasNotificationSupport) {
+  if (notifyThreshold === null)
+    return null;
+  if (!isWatching)
+    return "Error: --notify requires --watch.";
+  if (!hasNotificationSupport)
+    return "Error: --notify is not supported on this system (missing notify-send).";
+  return null;
+}
+function shouldSendThresholdNotification(prevFraction, currentFraction, threshold) {
+  return prevFraction !== undefined && prevFraction > threshold && currentFraction <= threshold;
+}
 function parseVersion(modelId) {
   const match = modelId.match(/gemini-(\d+)(?:\.(\d+))?-(.*)/);
   if (match) {
@@ -94,13 +145,18 @@ async function main() {
   if (watchIdx !== -1 && (watchIdx === args.length - 1 || args[watchIdx + 1].startsWith("-"))) {
     args.splice(watchIdx + 1, 0, "10s");
   }
+  const notifyIdx = args.findIndex((a) => a === "--notify" || a === "-n");
+  if (notifyIdx !== -1 && (notifyIdx === args.length - 1 || args[notifyIdx + 1].startsWith("-"))) {
+    args.splice(notifyIdx + 1, 0, "20");
+  }
   const { values } = parseArgs({
     args,
     options: {
       help: { type: "boolean", short: "h" },
-      "output-format": { type: "string", short: "o", default: "table" },
+      json: { type: "boolean", short: "j" },
       "no-color": { type: "boolean" },
-      watch: { type: "string", short: "w" }
+      watch: { type: "string", short: "w" },
+      notify: { type: "string", short: "n" }
     },
     strict: true
   });
@@ -112,17 +168,15 @@ 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
+  -n, --notify [threshold]  Show a critical OS notification if any model falls below
+                            the threshold (default: 20%; requires --watch).
+  -j, --json                Output raw JSON instead of a table
   --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;
+  const isJson = values.json === true;
   let intervalMs = 1e4;
   let intervalStr = "10s";
   if (values.watch) {
@@ -146,6 +200,20 @@ Options:
     }
   }
   const useColor = !values["no-color"] && !process.env.NO_COLOR && process.stdout.isTTY;
+  let notifyThreshold;
+  const lastFractions = new Map;
+  try {
+    notifyThreshold = parseNotifyThresholdArg(values.notify);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+  }
+  const notifyRuntimeError = validateNotifyRuntime(notifyThreshold, isWatching, checkNotificationSupport());
+  if (notifyRuntimeError) {
+    console.error(notifyRuntimeError);
+    process.exit(1);
+  }
   const colors = {
     reset: useColor ? "\x1B[0m" : "",
     dim: useColor ? "\x1B[2m" : "",
@@ -242,11 +310,22 @@ Options:
           return vB.minor - vA.minor;
         return vB.suffix.localeCompare(vA.suffix);
       });
+      if (notifyThreshold !== null) {
+        for (const b of quotaData.buckets) {
+          const fraction = b.remainingFraction ?? 0;
+          const modelId = b.modelId;
+          const prevFraction = lastFractions.get(modelId);
+          if (shouldSendThresholdNotification(prevFraction, fraction, notifyThreshold)) {
+            sendNotification("Gemini Quota Alert", `Model ${modelId} has dropped below ${Math.round(notifyThreshold * 100)}%.`);
+          }
+          lastFractions.set(modelId, fraction);
+        }
+      }
     }
-    if (isWatching)
+    if (isWatching && !isJson)
       process.stdout.write(colors.clear);
-    if (outputFormat === "json") {
-      console.log(JSON.stringify(quotaData.buckets || [], null, 2));
+    if (isJson) {
+      console.log(JSON.stringify(quotaData.buckets || []));
     } else {
       if (!quotaData.buckets || quotaData.buckets.length === 0) {
         console.log("No quota data available.");
@@ -286,7 +365,7 @@ Options:
           console.log("");
         }
       });
-      if (isWatching) {
+      if (isWatching && !isJson) {
         console.log(`
 ${colors.dim}Updating every ${intervalStr}, press q to quit${colors.reset}`);
       }
@@ -374,5 +453,8 @@ async function refreshAccessToken(refreshToken) {
   return response.json();
 }
 export {
+  validateNotifyRuntime,
+  shouldSendThresholdNotification,
+  parseNotifyThresholdArg,
   main as default
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gusage",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "A standalone CLI to export Gemini CLI quota and usage statistics",
   "module": "index.ts",
   "type": "module",
@@ -18,7 +18,8 @@
   "scripts": {
     "format": "prettier --write .",
     "prepare": "husky",
-    "build": "bun build ./index.ts --outfile dist/index.js && chmod +x dist/index.js"
+    "build": "bun build ./index.ts --outfile dist/index.js && chmod +x dist/index.js",
+    "prepack": "bun run build"
   },
   "lint-staged": {
     "*": "prettier --write --ignore-unknown",