axusage 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Łukasz Jerciński
+
+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,254 @@
+# axusage
+
+Monitor AI usage across Claude, ChatGPT, GitHub Copilot, and Gemini from a single command.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g axusage
+
+# Set up authentication (one-time setup per service)
+claude
+codex
+gemini
+axusage auth setup github-copilot
+
+# Check authentication status
+axusage auth status
+
+# Fetch usage
+axusage
+```
+
+## Authentication
+
+Claude, ChatGPT, and Gemini use their respective CLI OAuth sessions. GitHub
+Copilot uses browser-based authentication for persistent, long-lived sessions.
+
+**Setup (one-time per service):**
+
+```bash
+# Set up authentication for each service
+claude
+codex
+gemini
+axusage auth setup github-copilot
+
+# Check authentication status
+axusage auth status
+```
+
+When you run `auth setup` for GitHub Copilot, a browser window will open.
+Simply log in to GitHub as you normally would. Your authentication will be
+saved and automatically used for future requests.
+
+**Authenticated sessions directory (via [`env-paths`](https://github.com/sindresorhus/env-paths)):**
+
+- Linux: `~/.local/share/axusage/browser-contexts/` (or `$XDG_DATA_HOME/axusage/browser-contexts/`)
+- macOS: `~/Library/Application Support/axusage/browser-contexts/`
+- Windows: `%LOCALAPPDATA%\axusage\Data\browser-contexts\`
+
+You can override the location by providing `BrowserAuthConfig.dataDir`, but the CLI defaults to these platform-appropriate directories.
+
+> **Migration from `agent-usage`:** If upgrading from the old `agent-usage` package, copy your authentication contexts:
+>
+> - Linux/macOS: `mkdir -p ~/.local/share/axusage/ && cp -r ~/.local/share/agent-usage/* ~/.local/share/axusage/`
+> - Windows: Copy from `%LOCALAPPDATA%\agent-usage\` to `%LOCALAPPDATA%\axusage\`
+
+Security notes:
+
+- Files in this directory contain sensitive session data. They are created with owner-only permissions (0600 for files, 0700 for the directory) where possible.
+- To revoke access for GitHub Copilot, clear saved browser auth:
+
+```bash
+axusage auth clear github-copilot
+```
+
+Browser installation:
+
+- Playwright Chromium is installed automatically on `pnpm install` via a postinstall script. If this fails in your environment, install manually:
+
+```bash
+pnpm exec playwright install chromium --with-deps
+```
+
+**Global installation with pnpm:**
+
+pnpm blocks postinstall scripts for global packages by default (npm runs them automatically). After installing globally, approve and run the postinstall script:
+
+```bash
+pnpm add -g axusage
+pnpm approve-builds -g          # Select axusage when prompted
+pnpm add -g axusage             # Reinstall to run postinstall
+```
+
+Alternatively, install the browser manually after global installation. Use the Playwright binary that ships with the global package so the browser is installed in the right location:
+
+```bash
+pnpm add -g axusage
+PLAYWRIGHT_BIN="$(pnpm root -g)/axusage/node_modules/.bin/playwright"
+"$PLAYWRIGHT_BIN" install chromium --with-deps
+```
+
+## Usage
+
+```bash
+# Query all services
+axusage
+
+# Allow interactive re-authentication during usage fetch
+axusage --interactive
+
+# Single service
+axusage --service claude
+axusage --service chatgpt
+axusage --service github-copilot
+
+# JSON output
+axusage --format=json
+axusage --service claude --format=json
+
+# TSV output (parseable with cut, awk, sort)
+axusage --format=tsv
+```
+
+## Examples
+
+### Extract service and utilization (TSV + awk)
+
+```bash
+axusage --format=tsv | tail -n +2 | awk -F'\t' '{print $1, $4"%"}'
+```
+
+### Count windows by service (TSV + cut/sort/uniq)
+
+```bash
+axusage --format=tsv | tail -n +2 | cut -f1 | sort | uniq -c
+```
+
+### Filter by utilization threshold (TSV + awk)
+
+```bash
+axusage --format=tsv | tail -n +2 | awk -F'\t' '$4 > 50 {print $1, $3, $4"%"}'
+```
+
+### Extract utilization as JSON (JSON + jq)
+
+```bash
+axusage --format=json \
+  | jq -r '(.results? // .) | (if type=="array" then . else [.] end) | .[] | .windows[] | [.name, (.utilization|tostring)] | @tsv'
+```
+
+## Output
+
+Human-readable format shows:
+
+- Utilization percentage per window (5-hour, 7-day, monthly)
+- Usage rate vs expected rate
+- Reset times
+- Color coding: 🟢 on track | 🟡 over budget | 🔴 significantly over
+
+JSON format returns structured data for programmatic use.
+
+## Agent Rule
+
+Add to your `CLAUDE.md` or `AGENTS.md`:
+
+```markdown
+# Rule: `axusage` Usage
+
+Run `npx -y axusage --help` to learn available options.
+
+Use `axusage` when you need a quick, scriptable snapshot of API usage across Claude, ChatGPT, GitHub Copilot, and Gemini. It standardizes output (text, JSON, Prometheus) so you can alert, dashboard, or pipe it into other Unix tools.
+```
+
+## Troubleshooting
+
+### Authentication setup hangs
+
+- The CLI shows a countdown while waiting for login.
+- If you have completed login, press Enter in the terminal to continue.
+- If it still fails, run `axusage auth clear <service>` and retry.
+
+### "No saved authentication" error
+
+- Check which services are authenticated: `axusage auth status`.
+- Set up the missing service: `axusage auth setup <service>`.
+
+### Sessions expire
+
+- Browser sessions can expire based on provider policy. Re-run `auth setup` for the affected service when you see authentication errors.
+
+## Remote authentication and Prometheus export
+
+You can perform the interactive login flow on a workstation (for example, a local macOS laptop) and reuse the resulting browser session on a headless Linux server that collects usage and exports it for Prometheus.
+
+### 1. Authenticate on a workstation
+
+1. Install globally and authenticate the CLIs you need, then set up browser
+   auth for GitHub Copilot:
+
+   ```bash
+   npm install -g axusage
+
+   claude
+   codex
+   gemini
+   axusage auth setup github-copilot
+   ```
+
+2. Confirm the workstation has valid sessions:
+
+   ```bash
+   axusage auth status
+   ```
+
+3. Package the saved contexts so they can be transferred. Set `CONTEXT_DIR` to the path for your platform (see the table above):
+
+   ```bash
+   CONTEXT_DIR="$HOME/.local/share/axusage/browser-contexts"  # Linux default; adjust on macOS/Windows
+   tar czf axusage-contexts.tgz -C "$(dirname "$CONTEXT_DIR")" "$(basename "$CONTEXT_DIR")"
+   ```
+
+   Archive structure: `browser-contexts/claude/`, `browser-contexts/chatgpt/`, etc.
+
+### 2. Transfer the browser contexts to the Linux server
+
+1. Copy the archive to the server with `scp` (replace `user@server` with your login):
+
+   ```bash
+   scp axusage-contexts.tgz user@server:~/
+   ```
+
+2. On the server, create the target directory if it does not already exist, unpack the archive, and lock down the permissions:
+
+   ```bash
+   ssh user@server
+   CONTEXT_DIR="$HOME/.local/share/axusage/browser-contexts"  # Linux default; adjust per platform
+   AXUSAGE_DIR="$(dirname "$CONTEXT_DIR")"
+   mkdir -p "$CONTEXT_DIR"
+   tar xzf ~/axusage-contexts.tgz -C "$AXUSAGE_DIR"
+   # Directories 700, files 600
+   find "$AXUSAGE_DIR" -type d -exec chmod 700 {} +
+   find "$CONTEXT_DIR" -type f -exec chmod 600 {} +
+   ```
+
+3. Verify that the sessions are available on the server:
+
+   ```bash
+   axusage auth status
+   ```
+
+   If the server does not yet have the tool installed, run `npm install -g axusage` before checking the status.
+
+Notes:
+
+- Use `--service <name>` to restrict services.
+- Sessions may expire or become invalid if you change your password or log out of the service in another browser. Re-run `auth setup` as needed.
+- If you transfer browser contexts between machines, ensure the target system is secure and permissions are restricted to the intended user.
+- The CLI stores authentication data in the platform-specific directories listed above; protect that directory to prevent unauthorized access.
+
+## Development
+
+For local development in this repository, `pnpm run start` triggers a clean rebuild before executing the CLI. Use `pnpm run usage` only when `dist/` is already up to date. End users installing globally should run the `axusage` binary directly.

package/bin/axusage

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../dist/cli.js");

package/dist/adapters/chatgpt.d.ts

@@ -0,0 +1,8 @@
+import type { ServiceAdapter } from "../types/domain.js";
+/**
+ * ChatGPT service adapter using direct API access.
+ *
+ * Uses the OAuth token from Codex CLI's credential store (~/.codex/auth.json)
+ * to make direct API calls to ChatGPT's usage endpoint.
+ */
+export declare const chatGPTAdapter: ServiceAdapter;

package/dist/adapters/chatgpt.js

@@ -0,0 +1,68 @@
+import { extractRawCredentials, getAccessToken } from "axauth";
+import { ApiError } from "../types/domain.js";
+import { ChatGPTUsageResponse as ChatGPTUsageResponseSchema } from "../types/chatgpt.js";
+import { toServiceUsageData } from "./parse-chatgpt-usage.js";
+const API_URL = "https://chatgpt.com/backend-api/wham/usage";
+/**
+ * ChatGPT service adapter using direct API access.
+ *
+ * Uses the OAuth token from Codex CLI's credential store (~/.codex/auth.json)
+ * to make direct API calls to ChatGPT's usage endpoint.
+ */
+export const chatGPTAdapter = {
+    name: "ChatGPT",
+    async fetchUsage() {
+        const credentials = extractRawCredentials("codex");
+        if (!credentials) {
+            return {
+                ok: false,
+                error: new ApiError("No Codex credentials found. Run 'codex' to authenticate."),
+            };
+        }
+        if (credentials.type !== "oauth") {
+            return {
+                ok: false,
+                error: new ApiError("ChatGPT usage API requires OAuth authentication. API key authentication is not supported for usage data."),
+            };
+        }
+        const accessToken = getAccessToken(credentials);
+        if (!accessToken) {
+            return {
+                ok: false,
+                error: new ApiError("Invalid OAuth credentials: missing access token."),
+            };
+        }
+        try {
+            const response = await fetch(API_URL, {
+                headers: {
+                    Authorization: `Bearer ${accessToken}`,
+                },
+            });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => "");
+                return {
+                    ok: false,
+                    error: new ApiError(`ChatGPT API request failed: ${String(response.status)} ${response.statusText}${errorText ? ` - ${errorText}` : ""}`, response.status),
+                };
+            }
+            const data = await response.json();
+            const parseResult = ChatGPTUsageResponseSchema.safeParse(data);
+            if (!parseResult.success) {
+                return {
+                    ok: false,
+                    error: new ApiError(`Invalid response format: ${parseResult.error.message}`, undefined, data),
+                };
+            }
+            return {
+                ok: true,
+                value: toServiceUsageData(parseResult.data),
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: new ApiError(`Failed to fetch ChatGPT usage: ${error instanceof Error ? error.message : String(error)}`),
+            };
+        }
+    },
+};

package/dist/adapters/claude.d.ts

@@ -0,0 +1,9 @@
+import type { ServiceAdapter } from "../types/domain.js";
+/**
+ * Claude service adapter using direct API access.
+ *
+ * This adapter uses the OAuth token from Claude Code's credential store
+ * (Keychain on macOS, credentials file elsewhere) to make direct API calls
+ * to the Anthropic usage endpoint.
+ */
+export declare const claudeAdapter: ServiceAdapter;

package/dist/adapters/claude.js

@@ -0,0 +1,108 @@
+import { extractRawCredentials, getAccessToken } from "axauth";
+import { z } from "zod";
+import { ApiError } from "../types/domain.js";
+import { UsageResponse as UsageResponseSchema } from "../types/usage.js";
+import { coalesceClaudeUsageResponse } from "./coalesce-claude-usage-response.js";
+import { toServiceUsageData } from "./parse-claude-usage.js";
+const USAGE_API_URL = "https://api.anthropic.com/api/oauth/usage";
+const PROFILE_API_URL = "https://api.anthropic.com/api/oauth/profile";
+const ANTHROPIC_BETA_HEADER = "oauth-2025-04-20";
+/** Map organization_type to display name */
+const PLAN_TYPE_MAP = {
+    claude_max: "Max",
+    claude_pro: "Pro",
+    claude_enterprise: "Enterprise",
+    claude_team: "Team",
+};
+/** Fetch plan type from profile endpoint (best effort) */
+async function fetchPlanType(accessToken) {
+    try {
+        const response = await fetch(PROFILE_API_URL, {
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                "anthropic-beta": ANTHROPIC_BETA_HEADER,
+            },
+        });
+        if (!response.ok)
+            return undefined;
+        const data = (await response.json());
+        const orgType = data.organization?.organization_type;
+        return orgType ? (PLAN_TYPE_MAP[orgType] ?? orgType) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Claude service adapter using direct API access.
+ *
+ * This adapter uses the OAuth token from Claude Code's credential store
+ * (Keychain on macOS, credentials file elsewhere) to make direct API calls
+ * to the Anthropic usage endpoint.
+ */
+export const claudeAdapter = {
+    name: "Claude",
+    async fetchUsage() {
+        const credentials = extractRawCredentials("claude");
+        if (!credentials) {
+            return {
+                ok: false,
+                error: new ApiError("No Claude Code credentials found. Ensure Claude Code is installed and authenticated."),
+            };
+        }
+        if (credentials.type !== "oauth") {
+            return {
+                ok: false,
+                error: new ApiError("Claude Code usage API requires OAuth authentication. API key authentication is not supported for usage data."),
+            };
+        }
+        const accessToken = getAccessToken(credentials);
+        if (!accessToken) {
+            return {
+                ok: false,
+                error: new ApiError("Invalid OAuth credentials: missing access token."),
+            };
+        }
+        try {
+            const response = await fetch(USAGE_API_URL, {
+                headers: {
+                    Authorization: `Bearer ${accessToken}`,
+                    "anthropic-beta": ANTHROPIC_BETA_HEADER,
+                },
+            });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => "");
+                return {
+                    ok: false,
+                    error: new ApiError(`Claude API request failed: ${String(response.status)} ${response.statusText}${errorText ? ` - ${errorText}` : ""}`, response.status),
+                };
+            }
+            const data = await response.json();
+            const parseResult = UsageResponseSchema.safeParse(coalesceClaudeUsageResponse(data) ?? data);
+            if (!parseResult.success) {
+                /* eslint-disable unicorn/no-null -- JSON.stringify requires null for no replacer */
+                console.error("Raw API response:", JSON.stringify(data, null, 2));
+                console.error("Validation errors:", JSON.stringify(z.treeifyError(parseResult.error), null, 2));
+                /* eslint-enable unicorn/no-null */
+                return {
+                    ok: false,
+                    error: new ApiError(`Invalid response format: ${parseResult.error.message}`, undefined, data),
+                };
+            }
+            // Fetch plan type (best effort, don't fail if unavailable)
+            const planType = await fetchPlanType(accessToken);
+            const usageData = toServiceUsageData(parseResult.data);
+            return {
+                ok: true,
+                value: planType ? { ...usageData, planType } : usageData,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                ok: false,
+                error: new ApiError(`Failed to fetch Claude usage: ${message}`),
+            };
+        }
+    },
+};

package/dist/adapters/coalesce-claude-usage-response.d.ts

@@ -0,0 +1,12 @@
+import type { UsageResponseInput } from "../types/usage.js";
+/**
+ * Best-effort coalescing for array-shaped Claude usage responses.
+ *
+ * Notes:
+ * - Requires 5-hour and 7-day windows; otherwise returns undefined.
+ * - Windows with missing reset timestamps are retained with `resets_at: null`,
+ *   which the schema transforms to undefined for consumers.
+ * - Opus, Sonnet, and OAuth apps windows are optional and will only be included
+ *   when present in the source data.
+ */
+export declare function coalesceClaudeUsageResponse(data: unknown): UsageResponseInput | undefined;

package/dist/adapters/coalesce-claude-usage-response.js

@@ -0,0 +1,119 @@
+import { z } from "zod";
+const UsageWindowCandidate = z.object({
+    window: z.string().optional(),
+    period: z.string().optional(),
+    name: z.string().optional(),
+    key: z.string().optional(),
+    utilization: z.number().optional(),
+    percentage: z.number().optional(),
+    percent: z.number().optional(),
+    resets_at: z.union([z.string(), z.null()]).optional(),
+    reset_at: z.union([z.string(), z.null()]).optional(),
+    resetsAt: z.union([z.string(), z.null()]).optional(),
+    resetAt: z.union([z.string(), z.null()]).optional(),
+});
+const UsageWindowCandidates = z.array(UsageWindowCandidate);
+/**
+ * Tokenizes labels so we can match windows even when punctuation varies,
+ * e.g. "7-day" vs "seven_day".
+ * Splits on any non-alphanumeric characters (hyphen, underscore, space, etc.).
+ *
+ * Note: labels are normalized to lowercase in {@link normalizeLabel}, so the
+ * character class here only needs to handle lowercase a–z and digits.
+ */
+const tokenizeLabel = (label) => new Set(label.split(/[^a-z0-9]+/gu).filter(Boolean));
+const normalizeLabel = (candidate) => (candidate.window ||
+    candidate.period ||
+    candidate.name ||
+    candidate.key ||
+    "").toLowerCase();
+const resolveResetTimestamp = (candidate) => {
+    const values = [
+        candidate.resets_at,
+        candidate.reset_at,
+        candidate.resetsAt,
+        candidate.resetAt,
+    ];
+    for (const value of values) {
+        if (value === undefined)
+            continue;
+        return value;
+    }
+    // eslint-disable-next-line unicorn/no-null -- Schema expects explicit null for absent timestamps
+    return null;
+};
+const resolveUtilization = (candidate) => {
+    if (candidate.utilization !== undefined)
+        return candidate.utilization;
+    return candidate.percentage ?? candidate.percent ?? 0;
+};
+const selectMetric = (candidates, matchers) => {
+    for (const candidate of candidates) {
+        const label = normalizeLabel(candidate);
+        if (!label)
+            continue;
+        const tokens = tokenizeLabel(label);
+        const matches = matchers.includes(label) ||
+            matchers.some((matcher) => tokens.has(matcher));
+        if (!matches)
+            continue;
+        const utilization = resolveUtilization(candidate);
+        return {
+            utilization,
+            resets_at: resolveResetTimestamp(candidate),
+        };
+    }
+    return undefined;
+};
+/**
+ * Best-effort coalescing for array-shaped Claude usage responses.
+ *
+ * Notes:
+ * - Requires 5-hour and 7-day windows; otherwise returns undefined.
+ * - Windows with missing reset timestamps are retained with `resets_at: null`,
+ *   which the schema transforms to undefined for consumers.
+ * - Opus, Sonnet, and OAuth apps windows are optional and will only be included
+ *   when present in the source data.
+ */
+export function coalesceClaudeUsageResponse(data) {
+    if (!Array.isArray(data))
+        return undefined;
+    const parsed = UsageWindowCandidates.safeParse(data);
+    if (!parsed.success)
+        return undefined;
+    const candidates = parsed.data;
+    const fiveHour = selectMetric(candidates, [
+        "five_hour",
+        "five",
+        "5",
+        "5hour",
+    ]);
+    const sevenDay = selectMetric(candidates, [
+        "seven_day",
+        "seven",
+        "7",
+        "week",
+    ]);
+    const sevenDayOpus = selectMetric(candidates, ["seven_day_opus", "opus"]);
+    const sevenDaySonnet = selectMetric(candidates, [
+        "seven_day_sonnet",
+        "sonnet",
+    ]);
+    const sevenDayOauth = selectMetric(candidates, [
+        "seven_day_oauth_apps",
+        "oauth",
+    ]);
+    if (!fiveHour || !sevenDay)
+        return undefined;
+    const result = {
+        five_hour: fiveHour,
+        seven_day: sevenDay,
+    };
+    if (sevenDayOpus)
+        result.seven_day_opus = sevenDayOpus;
+    if (sevenDaySonnet)
+        result.seven_day_sonnet = sevenDaySonnet;
+    if (sevenDayOauth)
+        result.seven_day_oauth_apps = sevenDayOauth;
+    return result;
+}

package/dist/adapters/gemini.d.ts

@@ -0,0 +1,8 @@
+import type { ServiceAdapter } from "../types/domain.js";
+/**
+ * Gemini service adapter using direct API access.
+ *
+ * Uses the OAuth token from Gemini CLI's credential store (~/.gemini/oauth_creds.json)
+ * to make direct API calls to Google's quota endpoint.
+ */
+export declare const geminiAdapter: ServiceAdapter;

package/dist/adapters/gemini.js

@@ -0,0 +1,43 @@
+import { getAgentAccessToken } from "axauth";
+import { ApiError } from "../types/domain.js";
+import { fetchGeminiQuota, fetchGeminiProject, } from "../services/gemini-api.js";
+import { toServiceUsageData } from "./parse-gemini-usage.js";
+/**
+ * Gemini service adapter using direct API access.
+ *
+ * Uses the OAuth token from Gemini CLI's credential store (~/.gemini/oauth_creds.json)
+ * to make direct API calls to Google's quota endpoint.
+ */
+export const geminiAdapter = {
+    name: "Gemini",
+    async fetchUsage() {
+        const accessToken = getAgentAccessToken("gemini");
+        if (!accessToken) {
+            return {
+                ok: false,
+                error: new ApiError("No Gemini credentials found. Run 'gemini' to authenticate."),
+            };
+        }
+        try {
+            // Discover project ID for more accurate quotas (best effort)
+            const projectId = await fetchGeminiProject(accessToken);
+            // Fetch quota data
+            const quotaResult = await fetchGeminiQuota(accessToken, projectId);
+            if (!quotaResult.ok) {
+                return quotaResult;
+            }
+            return {
+                ok: true,
+                value: toServiceUsageData(quotaResult.value),
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: error instanceof ApiError
+                    ? error
+                    : new ApiError(`Failed to fetch Gemini usage: ${error instanceof Error ? error.message : String(error)}`),
+            };
+        }
+    },
+};

package/dist/adapters/github-copilot.d.ts

@@ -0,0 +1,6 @@
+import type { ServiceAdapter } from "../types/domain.js";
+/** Functional core is extracted to ./parse-github-copilot-usage.ts */
+/**
+ * GitHub Copilot service adapter
+ */
+export declare const githubCopilotAdapter: ServiceAdapter;