aiuse 2.1.28

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 (synthetic demo accounts, generated by docs/generate-readme-demo.py — no 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) or a source that failed to fetch (error); everything else is informational (n/a 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, Claude/cswap reliability notes (docs/cswap-reliability.md), and review-derived fixes in docs/fix-implementation-plan.md.

Data sources

Tool	Purpose	Authority
cswap cswap list --json	Live Claude Code quota for every configured email/account	Canonical multi-account Claude source; prefers cswap 0.24 display-grade JSON, with local-cache recovery for older versions
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 Claude multi-account reliability (official display-grade JSON vs legacy cache), see docs/cswap-reliability.md. caut + OpenUsage setup: docs/collectors-caut-openusage.md.

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]"

More channels and release / OIDC publish docs: docs/packaging.md.

Ambient companions (menu bar) + one-line status: docs/companion-stack.md
Scheduled runs (macOS LaunchAgent, hourly): docs/scheduling.md (./packaging/launchd/install.sh). Snapshot history: docs/history-learning.md.

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

Run aiuse --show-config-path to print the canonical path and retired YAML path. aiuse --generate-config creates missing parent dirs and writes the TOML starter without overwriting it. Legacy services.yaml is read only when config.toml is absent. If both exist, aiuse exits with a migration error: move the YAML settings into TOML, then remove services.yaml. Provider credentials stay with cswap, CodexBar, caut, OpenUsage, and tokscale — these files do not hold tokens or emails.

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: Keychain trust helpers (see docs/macos-keychain-trust.md)
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

# 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

# Scripting / cron / agents (JSON on stdout; use exit codes)
aiuse -q --json
aiuse suggest --json         # includes top-level suggestion
# exit 0 = ok, no burn/conserve alerts
# exit 1 = hard failure (collectors failed, no accounts)
# exit 2 = success with at least one burn/conserve alert
# field contract: docs/json-contract.md
# loopback HTTP for multi-step agents: aiuse serve  (docs/agent-api.md)

# 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 for agents (docs/agent-api.md)

# 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

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; see docs/agent-api.md)
--port / --max-age	Serve bind port (default 8787) and snapshot cache max age
--traditional-summary	Legacy flat summary format instead of unified action plan
--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 (--no-openusage remains an alias for .ai)
--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 canonical config.toml and retired services.yaml paths
doctor / --doctor	Check tools on PATH, config presence, effective timeouts; no collect
trust …	macOS: codesign status / sign caut / Keychain grant guide (docs/macos-keychain-trust.md)
--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 (preferring 0.24 display-grade JSON, with legacy cache hydrate + fallbacks).
8. Optional surfaces: aiuse suggest (single burn winner), aiuse status / prompt (one-liner), aiuse serve (loopback ranking API for agents). Snapshot history can blend into pace when enabled (docs/history-learning.md).

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.

Scoring modes (analysis.scoring_mode)

Mode	Meaning
pace (default)	Burn / conserve / on-pace from projected waste and lockout
multi_dim	Previous value + flexibility + deadline blend (escape hatch)
legacy	Original deadline-heavy scorer (use_multi_dim_scoring: false still maps here)

Pace knobs (also 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).

Related reading

• docs/consumption-flexibility-plan.md — historical multi-dimensional scoring design (superseded by pace-based scoring in Phase 2 of the fix plan).
• docs/code-review-2026-07-23.html — a 79-agent adversarial code review (45 findings) plus design proposals for containing tokscale's collector timeouts and fixing the rating algorithm. Open it directly in a browser for the styled version; GitHub's file viewer only shows the source.
• docs/fix-implementation-plan.md — review-derived fix plan (Steps 1–34 done; Step 35 remains parked). Start at AGENTS.md for current priorities, not Step 1.
• Issue #1 — consumed upstream cswap display-grade last-good JSON (claude-swap#170); cswap 0.24 enables it, but remains optional.
• docs/cswap-reliability.md — Claude multi-account reliability: official display-grade JSON, legacy cache recovery, and peer fallbacks.
• docs/opencode-go-quota.md — OpenCode Go: why CodexBar auto/local can show remaining % when the TUI says limit reached, and how aiuse prefers web.
• docs/cursor-quota.md — Cursor Included/Auto/API + on-demand vs CodexBar slots.
• docs/antigravity-pools.md — Google AI / Antigravity: Gemini vs Claude/GPT are independent pools.
• docs/pretty-display.md — why pretty output uses Rich (not Textual / not Rich Layout) so the full report stays in scrollback.
• docs/packaging.md — pipx / PyPI / Homebrew; Trusted Publishing (OIDC) release flow.
• packaging/install-deps.sh — install all six data-source tools (cswap, CodexBar, caut, OpenUsage.ai, OpenUsage.sh, tokscale).
• docs/collectors-caut-openusage.md — caut + OpenUsage setup and cross-check priority.
• docs/macos-keychain-trust.md — aiuse trust: stable codesign for caut, Keychain Always Allow.
• docs/competitive-landscape.md — monitors vs decision tools (quotabot, onWatch, CodexBar); where aiuse is stronger/weaker at “what pool next?” after product issues #2–#9 (shipped).
• docs/next-options.md — recommended next actions and effort map for remaining competitive gaps (issues #10–#15).
• docs/shared-quota-semantics.md — design note for shared ranking semantics.
• docs/shared-quota-semantics/ — v0.1 package (schemas, formulas, golden fixtures; dogfooded in pytest).
• docs/companion-stack.md — CodexBar/OpenUsage ambient + aiuse status one-liner + LaunchAgent.
• docs/agent-api.md — aiuse serve loopback HTTP for agents (/v1/suggest, /v1/ladder, …).
• docs/scheduling.md — LaunchAgent hourly (persist_snapshots).
• docs/history-learning.md — snapshot history vs learn_from_history.
• docs/claude-local-usage.md — Local Claude Code files / ccusage (token burn) vs subscription 5h/7d % from the OAuth usage API.
• docs/tokscale-per-provider-investigation.md — why tokscale cannot yet fan out per provider like CodexBar.
• docs/json-contract.md — stable JSON fields and exit codes for scripts.
• docs/collector-concurrency.md — parallel collect + 45s timeout audit.
• docs/handoff.md — latest session wrap-up and loose ends (for agents and future you).
• completions/ — bash/zsh completion (aiuse --print-completion bash).
• docs/review-workflow.js — the Claude Code Workflow script that generated the review, checked in for reproducibility.
• docs/generate-readme-demo.py — regenerates the colored priority-ladder example at the top of this README from synthetic demo data (no real accounts, no screenshot).
• docs/memory/ — thin Claude symlink target for this project; see AGENTS.md for persistence policy and links to ~/ops/site-private generic memory.
• Local quota dashboards in the same category as OpenUsage / CodexBar — see docs/competitive-landscape.md.