GitHub - allixsenos/asu: Agent subscription usage: a pluggable CLI for humans and agents

See how much of your coding-agent subscription you used, straight from the provider's account API.

ASU is a local TypeScript CLI for humans and agents. It finds supported installations and credentials, fetches usage from each provider concurrently, and prints bars, a table, plain text, or versioned JSON. Each provider has its own adapter. A failed provider does not hide the results of the other providers.

What it looks like

npx --yes @allixsenos/asu@latest

This is a real run against the maintainer's accounts on 2026-09-13. Bars are green below 70 percent, yellow from 70, and red from 90. Reset times are relative to the moment of the run, with the local clock after the dot. Pass --table for the table view, --utc for full timestamps, --plain for log-friendly text, or --json for agents and scripts. The same view as plain text is in the snapshot section below.

Quick start

ASU needs Node.js 22.13 or newer and npm. Sign in through the provider's own CLI first.

npx --yes @allixsenos/asu@latest

This runs the newest release of @allixsenos/asu from npm. No token is needed. Your provider credentials, which are separate, let ASU read usage.

# Plain text for terminals, logs, and pipes
npx --yes @allixsenos/asu@latest --plain

# Structured output for agents and scripts
npx --yes @allixsenos/asu@latest --json

# One provider, by its bare name
npx --yes @allixsenos/asu@latest claude

# Select accounts and bypass the five-minute usage cache
npx --yes @allixsenos/asu@latest claude codex copilot --fresh --table

# Include every built-in provider, even if no credentials are found
npx --yes @allixsenos/asu@latest --all --table

To pin a version, name it, for example @allixsenos/asu@0.3.0. The --fresh flag refreshes provider usage. It does not select a newer package revision.

Run the unreleased main branch

npx --yes github:allixsenos/asu --table

This needs Git. The repository commits the built dist/ directory, so the install needs no build step. For SSH, use git+ssh://git@github.com/allixsenos/asu.git#main. To pin a commit or a tag, append it, for example github:allixsenos/asu#v0.3.0. Each GitHub release also carries the packed tarball, and npx --yes https://github.com/allixsenos/asu/releases/latest/download/asu.tgz --table runs the newest one.

Real account output

We fetched the snapshot below on 2026-09-13 at 11:10 UTC from the maintainer's authenticated Claude, Codex, and GitHub Copilot accounts on Linux. These are real provider-reported figures, not fixtures or estimates. They become stale as usage changes.

Each block below is the recorded output of one of these commands, run one after another from the local checkout:

node dist/cli.js claude codex copilot --fresh --json
node dist/cli.js claude codex copilot --bars
node dist/cli.js claude codex copilot --table
node dist/cli.js claude codex copilot --plain

The first run fetched fresh figures. The other three ran inside the five-minute cache, so all four show the same figures and only the report timestamp differs. The output went to a file, so it has no colors. The examples include no credentials and no account identifiers.

The bars, the table, and the plain text show reset, fetch, and expiry times relative to the moment of the run, for example 2h30m or 45m. A time a day or more away also names the calendar day, and the bars add the local clock time of the recording machine. A reset time that already passed shows as now. Pass --utc for full UTC timestamps. JSON always contains them.

Bars

Use --bars for this view. It is the default in an interactive terminal. One bar per window, colored by severity in a terminal, with the countdown and the local clock after each bar. The bar shrinks in a narrow terminal, then the clock goes, and below that the default falls back to plain text.

ASU 0.9.0 · 2026-09-13T11:10:44.216Z

Claude · Max 20x · active · cached
  5 hours         ━─────────────────────────    5%  resets 3h 19m · 16:30
  Weekly          ━━━━━━━━━━━━━━━━━━━━──────   78%  resets 1d 17h · Tue 15 Sep 07:00
  Weekly · Fable  ━━━━━━━━━━━━━━━━━━━━━━━━━━  100%  resets 1d 17h · Tue 15 Sep 07:00
  Extra usage     Disabled
  fetched <1m ago · cache expires in 5m

Codex · Prolite · active · cached
  Weekly                         ━─────────────────────────    4%  resets 6d 23h · Sun 20 Sep 12:37
  GPT 5.3 Codex Spark · 5 hours  ──────────────────────────    0%  resets 4h 59m · 18:10
  GPT 5.3 Codex Spark · Weekly   ──────────────────────────    0%  resets 6d 23h · Sun 20 Sep 12:35
  Gpt Reserve · Weekly           ──────────────────────────    0%  resets 6d 23h · Sun 20 Sep 12:35
  Credits                        0 credits left
  Credits available              No
  fetched <1m ago · cache expires in 5m

GitHub Copilot · Individual · active · cached
  Chat                  ──────────────────────────    0%  resets 17d 12h · Thu 1 Oct 02:00  0 / 200 requests
  Completions           ──────────────────────────    0%  resets 17d 12h · Thu 1 Oct 02:00  0 / 2,000 requests
  Premium Interactions  ━━━━━━━━━━━━━━━━━━━━━━━━━━  100%  resets 17d 12h · Thu 1 Oct 02:00  0 / 0 requests
  fetched <1m ago · cache expires in 5m

Pretty table

Use --table for this view. When a cell would wrap, the default falls back to plain text. Pass --table to force the table.

ASU 0.9.0 · 2026-09-13T11:10:44.391Z
┌──────────────────┬────────────────────┬───────────────────────┬───────────────────────┬────────────────────┐
│ Provider         │ Plan               │ Window / balance      │ Usage                 │ Resets in          │
├──────────────────┼────────────────────┼───────────────────────┼───────────────────────┼────────────────────┤
│ Claude           │ Max 20x            │ 5 hours               │ 5% used               │ 3h19m              │
│ active           │                    │ Weekly                │ 78% used              │ 1d17h (Tue 15 Sep) │
│ cached           │                    │ Weekly · Fable        │ 100% used             │ 1d17h (Tue 15 Sep) │
│                  │                    │ Extra usage           │ Disabled              │ —                  │
├──────────────────┼────────────────────┼───────────────────────┼───────────────────────┼────────────────────┤
│ Codex            │ Prolite            │ Weekly                │ 4% used               │ 6d23h (Sun 20 Sep) │
│ active           │                    │ GPT 5.3 Codex Spark · │ 0% used               │ 5h                 │
│ cached           │                    │  5 hours              │                       │                    │
│                  │                    │ GPT 5.3 Codex Spark · │ 0% used               │ 6d23h (Sun 20 Sep) │
│                  │                    │  Weekly               │                       │                    │
│                  │                    │ Gpt Reserve · Weekly  │ 0% used               │ 6d23h (Sun 20 Sep) │
│                  │                    │ Credits               │ 0 credits left        │ —                  │
│                  │                    │ Credits available     │ No                    │ —                  │
├──────────────────┼────────────────────┼───────────────────────┼───────────────────────┼────────────────────┤
│ GitHub Copilot   │ Individual         │ Chat                  │ 0% used               │ 17d12h (Thu 1 Oct) │
│ active           │                    │                       │ 0 / 200 requests      │                    │
│ cached           │                    │ Completions           │ 0% used               │ 17d12h (Thu 1 Oct) │
│                  │                    │                       │ 0 / 2,000 requests    │                    │
│                  │                    │ Premium Interactions  │ 100% used             │ 17d12h (Thu 1 Oct) │
│                  │                    │                       │ 0 / 0 requests        │                    │
└──────────────────┴────────────────────┴───────────────────────┴───────────────────────┴────────────────────┘
Claude: fetched <1m ago; cache expires in 5m.
Codex: fetched <1m ago; cache expires in 5m.
GitHub Copilot: fetched <1m ago; cache expires in 5m.

Read Copilot's premium row with care. The endpoint returned zero entitlement, zero remaining requests, and zero percent remaining. ASU therefore shows 100% used next to 0 / 0 requests. This does not show that anyone consumed a premium request. The internal endpoint can return legacy quota information. Treat its quantities as the provider's reported snapshot, not as a complete billing statement.

Plain text

Use --plain for readable output in logs and pipes. It is the default when stdout is not a terminal.

ASU 0.9.0 · 2026-09-13T11:10:44.559Z

Claude (claude)
  active
  Plan: Max 20x
  5 hours: 5% used; resets in 3h19m
  Weekly: 78% used; resets in 1d17h (Tue 15 Sep)
  Weekly · Fable: 100% used; resets in 1d17h (Tue 15 Sep)
  Extra usage: Disabled
  Fetched <1m ago; cached; expires in 5m

Codex (codex)
  active
  Plan: Prolite
  Weekly: 4% used; resets in 6d23h (Sun 20 Sep)
  GPT 5.3 Codex Spark · 5 hours: 0% used; resets in 5h
  GPT 5.3 Codex Spark · Weekly: 0% used; resets in 6d23h (Sun 20 Sep)
  Gpt Reserve · Weekly: 0% used; resets in 6d23h (Sun 20 Sep)
  Credits: 0 credits left
  Credits available: No
  Fetched <1m ago; cached; expires in 5m

GitHub Copilot (copilot)
  active
  Plan: Individual
  Chat: 0% used; 0 / 200 requests; resets in 17d12h (Thu 1 Oct)
  Completions: 0% used; 0 / 2,000 requests; resets in 17d12h (Thu 1 Oct)
  Premium Interactions: 100% used; 0 / 0 requests; resets in 17d12h (Thu 1 Oct)
  Fetched <1m ago; cached; expires in 5m

JSON

Use --json for agents and scripts. Stdout contains the report. An ASU invocation error goes to stderr. The human output rounds quantities to two decimal places and shows relative times. JSON keeps the normalized numeric precision and the full UTC timestamps.

{
  "schemaVersion": 1,
  "asuVersion": "0.9.0",
  "generatedAt": "2026-09-13T11:10:44.042Z",
  "warnings": [],
  "providers": [
    {
      "planLabel": "Max 20x",
      "windows": [
        {
          "id": "five_hour",
          "label": "5 hours",
          "percentUsed": 5,
          "resetsAt": "2026-09-13T14:30:01.000Z"
        },
        {
          "id": "seven_day",
          "label": "Weekly",
          "percentUsed": 78,
          "resetsAt": "2026-09-15T05:00:01.000Z"
        },
        {
          "id": "weekly-model-fable",
          "label": "Weekly · Fable",
          "percentUsed": 100,
          "resetsAt": "2026-09-15T05:00:00.000Z",
          "scope": {
            "model": "Fable"
          }
        }
      ],
      "balances": [],
      "details": [
        {
          "label": "Extra usage",
          "value": "Disabled"
        }
      ],
      "providerId": "claude",
      "displayName": "Claude",
      "experimental": false,
      "installed": true,
      "credentialsPresent": true,
      "authenticated": true,
      "availability": "available",
      "reason": null,
      "fetchedAt": "2026-09-13T11:10:43.895Z",
      "expiresAt": "2026-09-13T11:15:43.895Z",
      "cached": false
    },
    {
      "planLabel": "Prolite",
      "windows": [
        {
          "id": "usage-primary_window",
          "label": "Weekly",
          "percentUsed": 4,
          "resetsAt": "2026-09-20T10:37:55.000Z"
        },
        {
          "id": "additional-0-gpt-5-3-codex-spark-primary_window",
          "label": "GPT 5.3 Codex Spark · 5 hours",
          "percentUsed": 0,
          "resetsAt": "2026-09-13T16:10:44.000Z"
        },
        {
          "id": "additional-0-gpt-5-3-codex-spark-secondary_window",
          "label": "GPT 5.3 Codex Spark · Weekly",
          "percentUsed": 0,
          "resetsAt": "2026-09-20T10:35:37.000Z"
        },
        {
          "id": "additional-1-gpt-reserve-primary_window",
          "label": "Gpt Reserve · Weekly",
          "percentUsed": 0,
          "resetsAt": "2026-09-20T10:35:37.000Z"
        }
      ],
      "balances": [
        {
          "id": "credits",
          "label": "Credits",
          "unit": "credits",
          "remaining": 0,
          "unlimited": false
        }
      ],
      "details": [
        {
          "label": "Credits available",
          "value": "No"
        }
      ],
      "providerId": "codex",
      "displayName": "Codex",
      "experimental": false,
      "installed": true,
      "credentialsPresent": true,
      "authenticated": true,
      "availability": "available",
      "reason": null,
      "fetchedAt": "2026-09-13T11:10:44.041Z",
      "expiresAt": "2026-09-13T11:15:44.041Z",
      "cached": false
    },
    {
      "planLabel": "Individual",
      "windows": [
        {
          "id": "chat",
          "label": "Chat",
          "percentUsed": 0,
          "resetsAt": "2026-10-01T00:00:00.000Z",
          "used": 0,
          "limit": 200,
          "unit": "requests",
          "unlimited": false
        },
        {
          "id": "completions",
          "label": "Completions",
          "percentUsed": 0,
          "resetsAt": "2026-10-01T00:00:00.000Z",
          "used": 0,
          "limit": 2000,
          "unit": "requests",
          "unlimited": false
        },
        {
          "id": "premium-interactions",
          "label": "Premium Interactions",
          "percentUsed": 100,
          "resetsAt": "2026-10-01T00:00:00.000Z",
          "used": 0,
          "limit": 0,
          "unit": "requests",
          "unlimited": false
        }
      ],
      "balances": [],
      "details": [],
      "providerId": "copilot",
      "displayName": "GitHub Copilot",
      "experimental": false,
      "installed": true,
      "credentialsPresent": true,
      "authenticated": true,
      "availability": "available",
      "reason": null,
      "fetchedAt": "2026-09-13T11:10:43.927Z",
      "expiresAt": "2026-09-13T11:15:43.927Z",
      "cached": false
    }
  ]
}

CLI reference

asu [usage] [provider...] [options]

When you run ASU through npx, put the ASU options after the package name.

Without --all or --provider, ASU omits a provider that has no detected installation, no credentials, and no discovery error. Credentials can work even when the provider's executable is not on PATH. The table and the plain text show one status per provider: active when usage came back, not logged in when credentials are missing or rejected, not installed when neither credentials nor the provider's executable were found, and error when the request failed. JSON keeps installed, credentialsPresent, and authenticated as separate fields, where null means unknown.

Exit codes

A zero exit code does not mean that every provider succeeded. When you automate ASU, examine the availability of each provider. Missing credentials, a timeout, or a malformed response from one provider does not discard the data of the other providers.

Use JSON in scripts

npx --yes @allixsenos/asu@latest --json > usage.json
jq '.providers[] | {providerId, availability, planLabel, windows}' usage.json

# Find available providers with a window at or above 80% used
jq '[.providers[]
  | select(.availability == "available")
  | select(any(.windows[]; .percentUsed != null and .percentUsed >= 80))
  | .providerId]' usage.json

A consumer must examine schemaVersion before it processes a report. Version 1 includes:

An unknown percentage or reset time is null. A missing quantity or balance does not mean zero. An unlimited allowance is explicit. A percentage can exceed 100 if a provider reports overage. Do not assume a fixed number or order of windows. See the report contract and the schemas for the full model. An agent that wants to watch its own budget can follow Use ASU from an agent. The asu-usage skill measures what one command costs, and npx skills add allixsenos/asu installs it.

Supported providers

Only Claude Max 20x, Codex Plus, and GitHub Copilot Individual passed a check against the maintainer's live accounts. The other five adapters always return experimental: true, and the human output marks them. A passed fixture test does not prove a live subscription or every credential-store variant. The macOS and Windows paths have no live test.

Credential lookup details:

• Claude reads claudeAiOauth.accessToken. On macOS it falls back to the Keychain service Claude Code-credentials. It tries the current user's account before the legacy service-only lookup.
• Codex needs the OAuth tokens.access_token, with an optional tokens.account_id. This adapter does not support API-key authentication or credentials that live only in the OS keyring.
• Copilot obeys GH_CONFIG_DIR and XDG_CONFIG_HOME when it reads the GitHub CLI credentials. It does not read credentials that live only in the Copilot CLI's own store. An installed gh alone does not count as an installed Copilot CLI.
• Cursor reads its desktop state.vscdb in read-only mode. It uses the platform locations, including macOS Application Support and Windows APPDATA. The Linux lookup obeys XDG_CONFIG_HOME.
• Kimi's credential file is credentials/kimi-code.json under its configured or default home.
• MiniMax supports MINIMAX_REGION=cn or a recognized MINIMAX_BASE_URL. ASU rejects an arbitrary API destination.

The APIs include undocumented internal endpoints and can change. The request methods, schemas, primary sources, and limitations of each adapter are in provider contracts.

How it works

CLI options → provider registry → concurrent provider operations
                                      │
                          read local credentials (read-only)
                                      │
                       five-minute cache or provider usage API
                                      │
                         normalize, validate, and redact
                                      │
                            table / plain text / JSON

Each provider lives in its own file under src/providers/. The shared service handles deadlines, failure isolation, caching, and report validation. The renderers accept any number of windows or balances. All work happens in the local Node process. There is no dashboard, HTTP server, hosted backend, or telemetry.

Cache and timeouts

ASU caches a result for five minutes, separately for each provider and credential identity. It selects the cache directory in this order:

1. --cache-dir PATH
2. $ASU_CACHE_DIR
3. $XDG_CACHE_HOME/asu
4. ~/.cache/asu

ASU reads the credentials on each invocation. A changed credential changes the cache key. Concurrent calls in one process share one fetch. Concurrent CLI invocations use file locks. ASU also caches an API failure. It examines missing, malformed, and locally expired credentials again on each invocation, without an API request.

Use --fresh to bypass an existing result after you solve a problem. Use --no-cache when ASU must not read or write the persistent cache. The report still includes the five-minute expiresAt of the snapshot when disk caching is off. ASU replaces an expired entry at the next lookup. It does not remove the old entries of unused accounts.

An HTTP request has an eight-second deadline, a one-MiB response limit, and no redirects. Each provider operation has a twelve-second deadline. A wait for the cache lock stops after about 32 seconds. When the cache fails, ASU fetches without persistence and adds a warning.

Credential handling

ASU reads existing credentials and sends them only to the provider endpoint of the adapter. It never refreshes a token, signs in, rewrites a provider file, runs the provider CLI to get usage, or estimates subscription consumption from conversation history. Missing or rejected credentials give an unavailable result. Sign in or refresh through the provider's own CLI.

Once a day, after the report, ASU asks the npm registry for its own newest version and prints one line on stderr when a newer one exists. The request carries only the package name, and the answer is kept in the cache directory. --no-cache, ASU_NO_UPDATE_CHECK=1, NO_UPDATE_NOTIFIER=1, or CI=true turns the check off. This is the only request ASU makes to anything other than a provider.

ASU prints and caches only normalized usage. It excludes tokens, refresh tokens, account IDs, and raw API errors. The cache uses private directory and file permissions on Unix, and SHA-256 filenames derived from the credential identity. A usage report still contains plan and account-usage information. The maintainer shared the examples above on purpose.

Troubleshooting

Plugins

A provider is an ESM module with a unique ID, a version, and three operations: detect the installation, resolve the credentials, and fetch normalized usage. An adapter owns its credential format and its API contract. The shared service and the renderers stay provider-independent.

npx --yes @allixsenos/asu@latest --plugin ./my-provider.mjs --provider my-provider --json

A plugin can export default or provider. ASU resolves an installed package name from the current working directory. A plugin is local code that you load explicitly, and it has full access to the process. Load only modules that you trust. ASU does not download plugins and does not search for them. See the plugin contract and example for the details. The package also exports its service, schemas, and TypeScript types as a library.

Local development and testing

gh repo clone allixsenos/asu
cd asu
npm ci

# dist/ is committed. Rebuild after you edit TypeScript and commit the result.
npm run compile
node dist/cli.js --table
node dist/cli.js --provider claude,codex,copilot --fresh --json

# Required checks for behavior changes
npm run check
npm test

The tests use synthetic API responses and temporary credential stores. They cover normalization, credential precedence and expiration, malformed responses, failure isolation, timeouts, cache expiry, concurrent requests, account changes, redaction, and real CLI subprocess output. They do not use your accounts and do not call provider APIs. Live verification is a separate step, as the snapshot above documents.

GitHub Actions runs the type checks, the tests, and a packed-package smoke test on Node 22 and 24. It also fails when the committed dist/ differs from a fresh build. To try the packed artifact locally without a publication:

npx --yes --package "./$(npm pack --silent)" asu --help
npx --yes --package "./$(npm pack --silent)" asu --table

Enable the commit-message hook of the repository and prefer rebase on pull:

git config core.hooksPath .githooks
git config pull.rebase true

Conventional Commits are mandatory. Prefer small, scoped commits and squash merges. Rebase merges are permitted, and merge commits are off. CLAUDE.md is a symlink to AGENTS.md, so Claude and other agents share the project instructions.

Releases

release-please writes CHANGELOG.md and creates each release from the commit history. Releasing describes the release pull request, the GitHub release with the packed tarball, and the npm publication.

Project status

Public repository under the MIT license. The release workflow publishes the package to the public npm registry. ASU has no telemetry and never will. See the security policy for what that means and how to report a vulnerability.