aiuse 3.0.2

Aggregate AI subscription/API usage and flag use-it-or-lose-it allotments

aiuse

Your AI subscriptions reset unused capacity you already paid for. Claude, Codex, Copilot, Cursor, Grok, Gemini, OpenCode, and more each carve your usage into 5-hour / weekly / monthly windows — and whatever you don't burn by the reset is just gone. aiuse polls every plan you have from one terminal command and tells you, in plain language, what to use right now before it resets, and what's about to run out early so you can pace yourself.

CLI command: aiuse (stub ai → same entrypoint)

See it in action

This is real aiuse output from synthetic demo accounts, not a screenshot. It's the exact priority ladder printed by plain aiuse, read bottom → top: the pools most worth using right now sort to the bottom.

- error Groq · [e-mail] · No available fetch strategy for groq.
- empty Opencode · [e-mail] · OpenCode Go weekly quota: 0% left · ~lockout Thu 10:42 · pace within 4.5 days
  n/a   Deepseek · [e-mail] · balance $4.15 (no expiry)
  n/a   Openrouter · [e-mail] · balance $18.55 (no expiry)
  slow  Google AI / Antigravity · [e-mail] · Claude/GPT weekly: 22% left · ~lockout Fri 12:42 · pace within 1.2 days
  mid   Claude Code · [e-mail] · Claude Code weekly: 23% left · ok within 3.1 days
  mid   Cursor · [e-mail] · Cursor included: 29% left · ok within 3.3 days
  mid   Codex · [e-mail] · Codex weekly quota: 46% left · ok within 2.3 days
  mid   Grok · [e-mail] · Grok usage limit: 94% left · ok within 6.6 days
  mid   Gemini · [e-mail] · Gemini weekly: 84% left · ok within 4.0 days
+ use   GitHub Copilot · default · GitHub Copilot premium requests: 42% left · ~42%waste · use within ~1 day

Green (use) is capacity to burn now before it resets; red is capacity already lost (empty, including a zero/negative prepaid balance) or a source that failed to fetch (error); everything else is informational (n/a positive prepaid balances that never expire, slow windows you should pace yourself on, mid windows on track — nothing to do).

Try it in 60 seconds

pipx install aiuse
aiuse doctor   # see which data-source tools are already on your PATH
aiuse          # priority ladder for everything aiuse can see right now

No config file is required to start — aiuse doctor tells you exactly which of the optional data-source tools (below) it found, and aiuse works with however many you already have installed. See Install below for Homebrew, git-tip, and editable-dev options.

AI agents: start at AGENTS.md for a map of this repo, active priorities, and contributor guidance.

Data sources

Tool	Purpose	Authority
cswap cswap list --json	Live Claude Code quota for every configured email/account	Canonical multi-account Claude source
CodexBar codexbar usage --format json	Live quotas and balances for enabled providers	Preferred for non-Claude providers; keep its Claude source disabled on macOS until its Keychain prompting is fixed
caut caut usage --json	Independent multi-provider usage (CodexBar-class probes)	Cross-check peer, but leave disabled on macOS until its repeated Keychain prompting is fixed
OpenUsage.ai openusage / 127.0.0.1:6736/v1/limits	Quiet macOS menu-bar companion + live limits API	Cross-check peer; distinct collector key: openusage_ai
OpenUsage.sh openusage-sh export --output - --format json	Terminal dashboard, local telemetry, and quota export	Lowest-priority backup; distinct collector key: openusage_sh; only explicit quota metrics affect ranking
tokscale tokscale usage --json	Independent live subscription quota measurement	Cross-checked against peers; preferred for Copilot; fill-in when others lack a live row

This project shells out to tools already on your PATH (and optionally hits OpenUsage’s loopback API); it does not scrape billing dashboards itself. For more on collector setup, reliability, and source selection, see the documentation index.

macOS source policy (current)

Use cswap as the Claude source and CodexBar for every other provider. Keep CodexBar's Claude source disabled, even as a fallback. tokscale, OpenUsage.ai, OpenUsage.sh, and other available collectors are useful independent backup and cross-check sources. All collectors are enabled by default, whether installed now or prepared for later; disable any source in config.toml when it is not appropriate for your machine. On macOS, consider disabling caut and CodexBar's Claude integration if their Keychain-prompting bugs affect you.

Install

End users (pipx):

pipx install aiuse
# or from git tip:
# pipx install 'git+https://github.com/djbclark/aiuse.git'
aiuse doctor

(ai is installed as a stub that runs the same CLI.)

Homebrew (personal tap):

brew tap djbclark/aiuse
brew trust djbclark/aiuse
brew install aiuse

Developers (editable):

cd /path/to/aiuse
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Optional config (standard location: ~/.config/aiuse/, or $XDG_CONFIG_HOME/aiuse/):

# Create the canonical config.toml (never overwrites)
aiuse --generate-config

# Or copy the example by hand:
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/aiuse"
cp config/config.example.toml "${XDG_CONFIG_HOME:-$HOME/.config}/aiuse/config.toml"

File	Purpose
~/.config/aiuse/config.toml	All user settings: collectors, plans, analysis, timeouts, and macOS options

aiuse --generate-config creates missing parent directories and writes the TOML starter without overwriting it. Provider credentials stay with cswap, CodexBar, caut, OpenUsage, and tokscale — this file does not hold tokens or emails.

Optional OpenCode Zen balance

OpenCode Zen prepaid balance is a distinct service from OpenCode Go quota. CodexBar can report it, and aiuse can independently cross-check the live OpenCode billing response when a signed-in browser session is available. This is opt-in and normal collection never opens a browser or reads its cookie database.

# One-time optional browser reader for a pipx install.
pipx inject aiuse browser-cookie3

# Validate the OpenCode session, then save only the validated cookie through
# SecretSpec. The default manifest is ~/.config/aiuse/secretspec.toml.
aiuse credential refresh opencode-zen --from chrome --profile Default

The command reads only opencode.ai cookies, validates an authenticated workspace and a live Zen balance before saving, and never prints the cookie. Use --dry-run to validate without saving. aiuse credential refresh --help lists its confirmation, profile, timeout, and manifest options. See the OpenCode Zen balance guide for the source model and SecretSpec details.

aiuse normally unifies source-local account names automatically when each identifying source reports exactly one account for a provider. For a genuinely multi-account provider, map a local name explicitly instead of letting aiuse guess:

[account_aliases.codex.openusage_sh]
"codex-cli" = "[e-mail]"

aiuse --full prints this exact table when a multi-account source cannot be matched safely. Explicit mappings take precedence over automatic normalization.

Daily workflow

# Once: create defaults under ~/.config/aiuse/ (never overwrites)
aiuse --generate-config
aiuse doctor                 # PATH tools + config presence + timeouts
# Once per machine: install the data-source tools you intend to use
# (normally cswap, CodexBar, tokscale, and either or both distinct OpenUsage tools)
./packaging/install-deps.sh
# or: just -f ~/ops/site-djbclark/justfile install-aiuse-deps
# macOS: follow the trust guide from the documentation index when needed
aiuse trust setup            # caut: stable codesign + guide
aiuse trust sign-caut        # re-run after every cargo install
aiuse trust fix-codexbar-cache --dry-run   # CodexBar#679: trust CLI on cache items

# Optional: refresh the separately reported OpenCode Zen prepaid balance.
aiuse credential refresh opencode-zen --from chrome --profile Default

# Morning / before a long coding block
aiuse                        # priority ladder on stdout (use-soon at bottom); meta on stderr
aiuse --full                 # long report: per-provider, tips, History, detailed plan
aiuse --brief                # same as default (compat alias)
aiuse --no-tui               # classic plain-text report (also used when piping)
aiuse -q                     # ladder only (no stderr meta / Collecting…)
aiuse suggest                # single best burn pool (or “nothing urgent”)
aiuse status                 # one line for shell prompts / status bars
aiuse prompt                 # synonym of status

# Shell completion (bash or zsh)
eval "$(aiuse --print-completion bash)"
# or: source completions/ai.bash

# Tighter thresholds for “only what resets soon”
aiuse --min-remaining 50 --max-days 7

Usage

# Pretty human-readable report (default)
aiuse
aiuse --format pretty
aiuse --no-color          # plain text, no ANSI
aiuse -q / --quiet        # suppress progress on stderr

# or without install:
PYTHONPATH=src python -m ai

# Machine-readable JSON on stdout (progress on stderr unless -q)
aiuse --json
aiuse --format json
aiuse --json --alerts-only
aiuse suggest --json
aiuse --save ~/tmp/ai-snapshot.json   # also write JSON file

# Decision helpers
aiuse suggest              # single best burn pool
aiuse status               # one line for prompts / status bars
aiuse prompt               # synonym of status
aiuse serve                # loopback HTTP API for agents

# Faster / partial
aiuse --providers copilot,grok,codex   # query these separately
aiuse --no-tokscale
aiuse --min-remaining 50 --max-days 10

# Subprocess timeout for external tools (default 45s; also in config.toml)
aiuse --timeout 45
aiuse -t45

# Environment check (tools on PATH, config files, timeouts) — no usage collection
aiuse doctor
aiuse --doctor

Programmatic use and AI orchestration

aiuse turns the many local authenticated quota sources into one normalized, machine-readable snapshot. An agent can call it once instead of opening billing pages, finding credentials, or independently interpreting each provider’s reset bars — saving tokens and avoiding inconsistent conclusions.

# Full live snapshot, ranked alerts, and the best next action.
aiuse -q --json

# Only actionable alerts for a short agent/tool call.
aiuse -q --json --alerts-only

# The single best pool to use next, or null when there is nothing urgent.
aiuse suggest --json

JSON is written to stdout; -q keeps progress off stderr. Exit 0 means a successful run with no burn/conserve alert, 1 is a hard collection failure, and 2 is a successful run with an actionable alert. The stable fields and exit-code contract are in docs/json-contract.md.

For a long-lived local agent, aiuse serve provides the same decisions through a loopback HTTP API; see the documentation index.

Projects that want the ranking logic without depending on this CLI can reuse the language-neutral shared quota semantics: JSON Schemas, enums, pace rules, and golden fixtures are designed to be copied or validated from any language. aiuse uses those fixtures itself, but they do not require importing its Python package.

Flag	Effect
(none) / --format pretty	Priority ladder on stdout (empty→n/a→slow→mid→use); meta on stderr; plain when piped
--full	Long pretty report: per-provider, cross-checks, tips, History, detailed plan
--json / --format json	Full snapshot + alerts + suggestion + history as JSON
--brief	Alias of default priority-ladder pretty report
--no-tui	Force classic plain-text pretty report
--no-color	Disable ANSI colors in plain-text pretty mode
-q / --quiet	Suppress progress messages on stderr
--alerts-only	Recommendations only (respects pretty vs json)
suggest / --suggest	Single best burn pool (or nothing urgent); pair with --json for structured
status / prompt / --status	One-line status for shell prompts / status bars
serve / --serve	Loopback HTTP API for agents (127.0.0.1)
--port / --max-age	Serve bind port (default 8787) and snapshot cache max age
--print-completion bash|zsh	Print shell completion script to stdout
--no-tokscale / --no-cswap / --no-codexbar / --no-caut / --no-openusage-ai / --no-openusage-sh	Skip specific collectors
--providers copilot,grok	Query specific CodexBar providers (CSV, one per subprocess)
-t / --timeout SECONDS	Force subprocess timeout for all external tools (default 45)
--generate-config	Write default ~/.config/aiuse/config.toml; never overwrites existing
--show-config-path	Print the active config path
doctor / --doctor	Check tools on PATH, config presence, effective timeouts; no collect
trust …	macOS: codesign status, sign caut, and Keychain grant guide
credential refresh opencode-zen	Validate a Chrome OpenCode session and save it through SecretSpec
--min-remaining 50 --max-days 10	Override alert thresholds
--save PATH	Also write full JSON snapshot to PATH

Exit codes

Code	When
0	Collect succeeded (or nothing to report) and there are no burn/conserve alerts. INFO-only notes still count as 0.
1	Hard failure: collectors reported errors and no accounts were collected. Also used by aiuse doctor when an enabled tool is missing from PATH, and by --generate-config when nothing was written / overwrite refused.
2	Collect succeeded and at least one burn or conserve alert is present. Cross-check disagreements alone do not set 2. Bad --timeout values also use 2.

aiuse doctor checks config file presence, config validation (unknown keys, bad timeouts, dead plan aliases), all six data-source tools on PATH (and OpenUsage.ai loopback HTTP when the CLI is missing), and a light version probe (cswap --version, codexbar -V, caut --version, tokscale --version). It does not call usage APIs or verify login sessions.

What “use it or lose it” means

Most subscription coding plans (Claude Pro/Max, ChatGPT Plus/Codex, Cursor, Copilot, SuperGrok, Google AI Pro, …) grant windows of usage (5-hour, weekly, monthly). When the window resets, unused capacity disappears — you still paid for the month.

This tool:

1. Pulls remaining % and reset times from cswap (Claude multi-account), CodexBar (broad live quotas), caut, OpenUsage.ai, OpenUsage.sh (cross-check peers / fill-in), and tokscale (independent measurement; preferred for Copilot).
2. Scores windows with pace-based logic (default): compare how far through the cycle you are vs how much you've used, then project waste or early lockout.
3. Classifies each window as Burn (will leave capacity unused), Conserve (on track to exhaust before reset — slow down), or On pace (no alert).
4. For shared-allotment providers (Claude, Gemini by default), scores the longest governing window only so a fresh 5-hour bar does not outrank the weekly budget it draws from.
5. Default pretty output is a priority ladder on stdout (depleted → prepaid n/a → conserve → mid → use-soon at bottom; read bottom→top). Meta goes to stderr. Use aiuse --full for per-provider detail.
6. On --full, keeps the trailing plan within ~23 lines × console width when possible; if the detailed plan is taller, both detailed and at a glance are printed (glance last). Forecast fragments (~lockout …, projected waste %) appear on ladder/status lines when pace can project them.
7. Cross-checks all live sources pairwise; Claude multi-account stays canonical in cswap.
8. Optional surfaces: aiuse suggest (single burn winner), aiuse status / prompt (one-liner), and aiuse serve (loopback ranking API for agents). Snapshot history can blend into pace when enabled.

This command intentionally does not report historical local-token usage or API-equivalent cost estimates (use ccusage-class tools for local burn, not plan %).

Example output

================================================================================
AI USAGE — USE IT OR LOSE IT
Collected at … · 3 accounts · 2 alerts
================================================================================

## Per-provider usage
--------------------------------------------------------------------------------
Codex · account=[e-mail] · plan=plus · selected live source: CodexBar
  quota: Codex weekly quota
    [============] 100% left   0% used   resets in 6.4d (Jul 28 21:59 UTC)
    $6.90 · flex:▒ semi

## Cross-checks (informational)
--------------------------------------------------------------------------------
  Tools poll at different times; multi-account Claude is cswap-only. …

## Tips
--------------------------------------------------------------------------------
  • …

## Action plan — use these before they reset
--------------------------------------------------------------------------------
  Available capacity this cycle: $35.65 across 6 windows (5 providers).

  THIS WEEK (start now — capacity will reset or needs lead time)
  ─────────────────────────────────────────────────────────────
  .   Codex · [e-mail] · Codex weekly quota: 88% left · use within 6.4 days · $6.07 at risk
      Semi-throttled — steady usage will exhaust it.
  .   OpenCode Go · default · OpenCode Go weekly quota: 98% left · use within 4.5 days · $3.37 at risk
      Burstable — one heavy session will cover it.

Project layout

src/aiuse/
  cli.py                 # entrypoint
  collectors/            # cswap, codexbar, caut, openusage, tokscale
  analysis/use_or_lose.py
  report.py
config/config.example.toml
tests/

Tests

just test
just check # tests plus deterministic lint, type, spelling, and format checks
just lint  # full check plus Bandit, Semgrep, and Gitleaks
just format

The quality suite mirrors the applicable tools from stayturgid: pytest, Ruff, mypy, yamllint, markdownlint, Prettier (including TOML support), typos, Bandit, Semgrep, Gitleaks, pre-commit, and just. Ansible, shell, JavaScript/CSS, dotenv, Caddy, and browser-page checks are omitted because this repository contains none of those corresponding inputs.

Pace settings

Pace knobs (in config.toml under [analysis.pace]):

• waste_alert_fraction (default 0.30) — project this much unused → Burn
• min_elapsed_fraction (default 0.15) — too early in the window → On pace unless history says otherwise
• conserve_min_lead_hours (default 4) — exhaust this far before reset → Conserve

Shared allotment: analysis.provider_overrides.<provider>.shared_allotment: true (Claude/Gemini default) scores only the longest window per account.

Notes / limitations

• Live quota accuracy depends on each tool's auth (browser cookies, OAuth, keychain). Errors are reported per account rather than aborting the whole run.
• All enabled collectors (cswap, CodexBar, caut, OpenUsage.ai, OpenUsage.sh, tokscale) run concurrently; each CodexBar provider is its own subprocess. Default tool timeout is 45s (-t / config.toml [timeouts]).
• Per-window detail still shows $ value, flexibility class, and a pace ratio when computable.
• Duplicate live measurements are retained for cross-checking but only one copy drives recommendations.
• Dollar values use plan monthly_price with waking-hours correction (default 16h/day).

Further documentation

• packaging/install-deps.sh — install the optional data-source tools.
• docs/json-contract.md — stable JSON fields and exit codes.
• docs/shared-quota-semantics/ — reusable language-neutral schemas, rules, and fixtures.
• Documentation index — categorized guides, collector notes, automation, and maintainer material.