aiusage

AI subscription usage in your terminal.

Install

macOS, Linux, WSL:

curl -fsSL https://raw.githubusercontent.com/frittlechasm/aiusage/main/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/frittlechasm/aiusage/main/install.ps1 | iex

Requires bash, curl, jq.

Cursor's optional automatic browser-cookie lookup also requires sqlite3. Chromium-based browsers additionally require python3 and openssl. Set CURSOR_COOKIE to skip browser lookup and these optional dependencies.

By default this installs to ~/.local/bin on macOS/Linux/WSL and %LOCALAPPDATA%\Programs\aiusage\bin on Windows. To choose a directory:

curl -fsSL https://raw.githubusercontent.com/frittlechasm/aiusage/main/install.sh | sh -s -- --dir "$HOME/bin"

Usage

./aiusage                         # all available providers
./aiusage claude                  # Claude only
./aiusage cursor claude           # Cursor + Claude
./aiusage codex gemini copilot    # any subset, in the order you want
./aiusage opencode-go             # OpenCode Go only
./aiusage --version               # print the installed version
./aiusage update                  # update to the latest GitHub release

aiusage update checks the latest GitHub release, validates the downloaded script, and atomically replaces the installed script. The install directory must be writable by the current user.

How it works

• Single self-contained bash script — no build step, no daemon, no framework.
• Reads local auth or quota state already present on your machine, then calls provider usage endpoints.
• On macOS, Claude credentials are read from Keychain first, falling back to ~/.claude/.credentials.json when no token can be read. Linux uses the credentials file.
• Local sources include ~/.codex/auth.json, ~/.gemini/oauth_creds.json, ~/.local/share/opencode/auth.json, Claude credentials, browser cookies for Cursor, and JetBrains quota files.
• If auth is missing, expired, or the upstream endpoint changed, that provider is shown as unavailable or returns an error line.

Provider notes

Provider	What it shows	Auth source
Claude	5h, Weekly, and optional Fable usage bars, banked reset count and expiries when offered, extra credit usage	claude login credentials
Codex	Available usage windows (for example 5h or Weekly), banked reset expiries, and extra credits	~/.codex/auth.json
Cursor	Monthly credit or request usage	Browser cookies or CURSOR_COOKIE
Gemini	Quota usage for Google OAuth / Code Assist	gemini login credentials
JetBrains	AI credit usage from local IDE quota state	AIAssistantQuotaManager2.xml
Copilot	AI Credits usage, with legacy Premium, Chat, and Completions quotas when applicable	COPILOT_GITHUB_TOKEN or copilot login
OpenCode Go	5h, Weekly, and Monthly usage	opencode login credentials, OPENCODE_GO_API_KEY, or OPENCODE_API_KEY

• Claude limit resets can be redeemed in Settings → Usage on Claude web or Desktop; the CLI shows the remaining count and available expiry dates.
• Cursor session lookup is automatic from Firefox, Chrome, Arc, Brave, Edge, or Helium.
• Copilot uses AI Credits for current plans and retains premium-request tracking for legacy annual plans.
• Copilot plans with unlimited or org-managed quotas may show only the plan name instead of bars.
• Provider endpoints and response shapes can change over time.

Adding providers

1. Add a fetch_<provider>() function.
2. Register it in run_all_parallel() and the main argument parser.

Testing

Tests live in tests/. Run ./tests/run_tests after every change.

• tests/unit/ — helpers and pure functions (calculations, rendering, formatting, caching, CLI args).
• tests/integration/ — fetch_* provider functions.

Warning

Security — treat this as a local utility with access to existing auth state.

• This script reads local auth files, local quota files, and in Cursor's case browser cookie stores. Run it only on machines you trust.
• On macOS, extracted Cursor and Copilot credentials are cached in the login Keychain. On Linux, they are cached in ~/.cache/aiusage/ with 0600 permissions.
• If you set CURSOR_COOKIE, COPILOT_GITHUB_TOKEN, OPENCODE_GO_API_KEY, or OPENCODE_API_KEY manually, avoid leaving them in shell history or dotfiles.
• Requests pass credentials as curl -H arguments rather than temp files, so tokens are briefly visible in the process list (ps) while a request runs. This is the common trade-off for CLI tools; the previous on-disk staging was worse.
• Do not commit token files, copied cookies, or cache files.
• Because this is a plain Bash script, you can audit exactly what it reads and what URLs it calls before running it.

---

_{Inspired by codexbar by @steipete.}