ASU: agent subscription usage

Name: asu
Author: allixsenos

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

# One account, by alias, masked label, or source
npx --yes @allixsenos/asu@latest claude --account opencode

# 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/[email protected]. 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://[email protected]/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-14 at 10:13 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. Accounts appear only as masked labels.

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.10.0 · 2026-09-14T10:13:52.452Z

Claude · l***@c***.guru · Max 20x · active · cached
  via Claude Code (in use)
  5 hours         ╸─────────────────────────    3%  resets 4h 16m · 16:30
  Weekly          ━━━━━━━━━━━━━━━━━━━━━─────   82%  resets 18h 46m · Tue 15 Sep 07:00
  Weekly · Fable  ━━━━━━━━━━━━━━━━━━━━━━━━━━  100%  resets 18h 46m · Tue 15 Sep 07:00
  Extra usage     Enabled
  fetched <1m ago · cache expires in 5m

Codex · d***@l.hr · Prolite · active · cached
  via Codex CLI (in use)
  Weekly                         ━━────────────────────────    8%  resets 6d · Sun 20 Sep 12:37
  GPT 5.3 Codex Spark · 5 hours  ──────────────────────────    0%  resets 4h 59m · 17:13
  GPT 5.3 Codex Spark · Weekly   ──────────────────────────    0%  resets 6d · Sun 20 Sep 12:35
  Gpt Reserve · Weekly           ──────────────────────────    0%  resets 6d · Sun 20 Sep 12:35
  Credits                        0 credits left
  Credits available              No
  fetched <1m ago · cache expires in 5m

GitHub Copilot · a*** · Individual · active · cached
  via GitHub CLI (in use)
  Chat                  ──────────────────────────    0%  resets 16d 13h · Thu 1 Oct 02:00  0 / 200 requests
  Completions           ──────────────────────────    0%  resets 16d 13h · Thu 1 Oct 02:00  0 / 2,000 requests
  Premium Interactions  ━━━━━━━━━━━━━━━━━━━━━━━━━━  100%  resets 16d 13h · 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.10.0 · 2026-09-14T10:13:52.633Z
┌──────────────────┬────────────────────┬───────────────────────┬───────────────────────┬────────────────────┐
│ Provider         │ Plan               │ Window / balance      │ Usage                 │ Resets in          │
├──────────────────┼────────────────────┼───────────────────────┼───────────────────────┼────────────────────┤
│ Claude           │ Max 20x            │ 5 hours               │ 3% used               │ 4h16m              │
│ l***@c***.guru   │                    │ Weekly                │ 82% used              │ 18h46m             │
│ active           │                    │ Weekly · Fable        │ 100% used             │ 18h46m             │
│ cached           │                    │ Extra usage           │ Enabled               │ —                  │
├──────────────────┼────────────────────┼───────────────────────┼───────────────────────┼────────────────────┤
│ Codex            │ Prolite            │ Weekly                │ 8% used               │ 6d (Sun 20 Sep)    │
│ d***@l.hr        │                    │ GPT 5.3 Codex Spark · │ 0% used               │ 5h                 │
│ active           │                    │  5 hours              │                       │                    │
│ cached           │                    │ GPT 5.3 Codex Spark · │ 0% used               │ 6d (Sun 20 Sep)    │
│                  │                    │  Weekly               │                       │                    │
│                  │                    │ Gpt Reserve · Weekly  │ 0% used               │ 6d (Sun 20 Sep)    │
│                  │                    │ Credits               │ 0 credits left        │ —                  │
│                  │                    │ Credits available     │ No                    │ —                  │
├──────────────────┼────────────────────┼───────────────────────┼───────────────────────┼────────────────────┤
│ GitHub Copilot   │ Individual         │ Chat                  │ 0% used               │ 16d13h (Thu 1 Oct) │
│ a***             │                    │                       │ 0 / 200 requests      │                    │
│ active           │                    │ Completions           │ 0% used               │ 16d13h (Thu 1 Oct) │
│ cached           │                    │                       │ 0 / 2,000 requests    │                    │
│                  │                    │ Premium Interactions  │ 100% used             │ 16d13h (Thu 1 Oct) │
│                  │                    │                       │ 0 / 0 requests        │                    │
└──────────────────┴────────────────────┴───────────────────────┴───────────────────────┴────────────────────┘
Claude (l***@c***.guru) via Claude Code (in use): fetched <1m ago; cache expires in 5m.
Codex (d***@l.hr) via Codex CLI (in use): fetched <1m ago; cache expires in 5m.
GitHub Copilot (a***) via GitHub CLI (in use): 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.

Show the complete plain-text output

ASU 0.10.0 · 2026-09-14T10:13:52.805Z

Claude (claude)
  active
  Account: l***@c***.guru
  Via: Claude Code (in use)
  Plan: Max 20x
  5 hours: 3% used; resets in 4h16m
  Weekly: 82% used; resets in 18h46m
  Weekly · Fable: 100% used; resets in 18h46m
  Extra usage: Enabled
  Fetched <1m ago; cached; expires in 5m

Codex (codex)
  active
  Account: d***@l.hr
  Via: Codex CLI (in use)
  Plan: Prolite
  Weekly: 8% used; resets in 6d (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 6d (Sun 20 Sep)
  Gpt Reserve · Weekly: 0% used; resets in 6d (Sun 20 Sep)
  Credits: 0 credits left
  Credits available: No
  Fetched <1m ago; cached; expires in 5m

GitHub Copilot (copilot)
  active
  Account: a***
  Via: GitHub CLI (in use)
  Plan: Individual
  Chat: 0% used; 0 / 200 requests; resets in 16d13h (Thu 1 Oct)
  Completions: 0% used; 0 / 2,000 requests; resets in 16d13h (Thu 1 Oct)
  Premium Interactions: 100% used; 0 / 0 requests; resets in 16d13h (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.

Show the complete version 2 JSON report

{
  "schemaVersion": 2,
  "asuVersion": "0.10.0",
  "generatedAt": "2026-09-14T10:13:52.260Z",
  "warnings": [],
  "providers": [
    {
      "planLabel": "Max 20x",
      "windows": [
        {
          "id": "five_hour",
          "label": "5 hours",
          "percentUsed": 3,
          "resetsAt": "2026-09-14T14:30:01.000Z"
        },
        {
          "id": "seven_day",
          "label": "Weekly",
          "percentUsed": 82,
          "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": "Enabled"
        }
      ],
      "providerId": "claude",
      "displayName": "Claude",
      "experimental": false,
      "installed": true,
      "credentialsPresent": true,
      "authenticated": true,
      "availability": "available",
      "reason": null,
      "account": {
        "id": "claude:a3aae40f",
        "label": "l***@c***.guru",
        "sources": [
          {
            "name": "Claude Code",
            "inUse": true
          }
        ]
      },
      "fetchedAt": "2026-09-14T10:13:52.160Z",
      "expiresAt": "2026-09-14T10:18:52.160Z",
      "cached": false
    },
    {
      "planLabel": "Prolite",
      "windows": [
        {
          "id": "usage-primary_window",
          "label": "Weekly",
          "percentUsed": 8,
          "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-14T15:13:52.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,
      "account": {
        "id": "codex:10af7872",
        "label": "d***@l.hr",
        "sources": [
          {
            "name": "Codex CLI",
            "inUse": true
          }
        ]
      },
      "fetchedAt": "2026-09-14T10:13:52.256Z",
      "expiresAt": "2026-09-14T10:18:52.256Z",
      "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,
      "account": {
        "id": "copilot:b8b76928",
        "label": "a***",
        "sources": [
          {
            "name": "GitHub CLI",
            "inUse": true
          }
        ]
      },
      "fetchedAt": "2026-09-14T10:13:52.078Z",
      "expiresAt": "2026-09-14T10:18:52.078Z",
      "cached": false
    }
  ]
}

CLI reference

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

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

Option	Behavior
`--format plain\|table\|bars\|json`	Select one output format. Without it, a terminal gets the bars, or plain text when even the narrowest bar layout would wrap. A pipe gets plain text.
`--bars`, `--table`, `--plain`, `--json`	Shortcuts for `--format`. Use only one.
`--utc`	Print full UTC timestamps in table and plain output instead of times relative to now, such as `2h30m` or `7d (Tue 15 Sep)`
`claude codex`	Select providers by their bare names, in any position. `asu claude --plain` and `asu --plain claude` are the same.
`--provider claude,codex`	The same selection as a flag. Repeat the flag or separate the IDs with commas.
`--all`	Include providers with no detected installation or credentials
`--account SELECTOR`	Keep only accounts that match an alias, a masked label, an email, an account ID, or a source name such as `opencode`
`--show-email`	Show full email addresses instead of masked labels, in that run's output only
`--fresh`	Bypass cached usage. Concurrent fresh requests still share one fetch.
`--no-cache`	Do not read or write the persistent cache
`--cache-dir PATH`	Set the usage cache directory
`--plugin PATH_OR_PACKAGE`	Load a trusted provider plugin that you name explicitly. Repeatable.
`--help`, `-h`	Show help
`--version`, `-v`	Print the package version

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

Code	Meaning
`0`	At least one selected provider returned available usage
`1`	No selected provider returned available usage. ASU still prints a report.
`2`	Invalid invocation or plugin configuration. ASU prints an error to stderr.

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 2 includes:

Field	Meaning
`asuVersion`	The ASU package version that wrote the report. The plain and table headers show it too.
`generatedAt`, `warnings`, `providers`	Report timestamp, shared warnings, and independent provider results
`providerId`, `displayName`, `experimental`	Provider identity and live-validation status. One provider appears once per account.
`account`	The login behind the result: a stable `id`, a masked `label`, and the `sources` it was found in, each with `inUse`. `email` appears only with `--show-email`. `null` when no login was found.
`installed`, `credentialsPresent`, `authenticated`	Separate discovery and authentication observations
`availability`, `reason`	`available`, `unavailable`, or `error`, with a reason code and a safe message when needed
`planLabel`	Subscription label, or `null` if unknown
`windows`	Variable-length usage windows with IDs, percentages, UTC resets, optional quantities, and model or surface scope
`balances`	Reported credits or monetary balances with explicit units
`details`	Additional normalized label and value pairs
`fetchedAt`, `expiresAt`, `cached`	Timestamp and freshness of each provider snapshot

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. A provider can appear several times, once per account, so group results by providerId and account.id rather than by position. 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

ID	Provider	Credential sources	Validation
`claude`	Claude	`.credentials.json` under `$CLAUDE_CONFIG_DIR`, `$CLAUDE_HOME`, or `~/.claude`, with the identity from `.claude.json`. macOS Keychain. opencode `anthropic`.	Live account, Linux. opencode fixture tests only.
`codex`	Codex	`$CODEX_HOME/auth.json`, `~/.config/codex/auth.json`, `~/.codex/auth.json`, opencode `openai`	Live account, Linux. opencode fixture tests only.
`copilot`	GitHub Copilot	`COPILOT_TOKEN`, `GITHUB_TOKEN`, `GITHUB_PAT`, every account in GitHub CLI `hosts.yml`, opencode `github-copilot`	Live account, Linux. opencode fixture tests only.
`cursor`	Cursor	`CURSOR_ACCESS_TOKEN`, `CURSOR_TOKEN`, desktop SQLite, `~/.config/cursor/auth.json`	Experimental. Fixture tests only.
`zai`	Z.ai	`ZAI_API_KEY`, `GLM_API_KEY`, opencode `zai-coding-plan`	Experimental. Fixture tests only.
`grok`	Grok	`GROK_API_KEY`, `GROK_TOKEN`, `~/.grok/auth.json`, opencode `xai`	Experimental. Fixture tests only.
`kimi`	Kimi	`KIMI_TOKEN`, `KIMI_API_KEY`, credentials under `$KIMI_CODE_HOME`, `~/.kimi-code`, and legacy `~/.kimi`, opencode `kimi-for-coding`	Experimental. Fixture tests only.
`minimax`	MiniMax	`MINIMAX_API_KEY`, `~/.mmx/credentials.json`, `~/.mmx/config.json`, opencode `minimax-coding-plan` and `minimax-cn-coding-plan`	Experimental. Fixture tests only.

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.
opencode keeps its logins in $XDG_DATA_HOME/opencode/auth.json, or ~/.local/share/opencode/auth.json, on every platform.

Accounts

ASU reads every credential store on every run and reports each login as an account. Claude Code can use one Claude subscription while opencode uses another, and ASU reports both. Logins merge into one account when they share an account identity, such as a Claude account UUID or a Codex account ID, or the same token. A login with neither, such as an opencode Claude login, stays its own account and shows only where it came from. Accounts that a tool uses right now come first, and the via line names the tools.

Each account shows the alias it was given, or else a masked email such as j***@e***.org. Pass --show-email to see the full address. Pass --account to select one account.

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:

--cache-dir PATH
$ASU_CACHE_DIR
$XDG_CACHE_HOME/asu
~/.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 masks every email it shows, so [email protected] becomes j***@e***.org. The full email appears only with --show-email, only in that run's output, and never in the cache, a log, or an error message.

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

Symptom	What to examine
GitHub says the repository is missing or access is denied	Examine your Git access with `git ls-remote https://github.com/allixsenos/asu.git HEAD`. The SSH URL needs a GitHub SSH key.
The Git install fails during `prepare`	Examine the Node version, the dependency-registry access, and whether npm permits build scripts. See the local checkout instructions below.
`npx` exits with code 1 and prints nothing, or npm 9 reports `could not determine executable to run`	npm 9 cannot run the nested install that a Git dependency with a `build` or `prepare` script needs through `npx`. ASU commits `dist/` and has neither script, so a current checkout does not hit this. Clear the npx cache with `rm -rf ~/.npm/_npx` and retry, or use the release tarball URL.
No supported agents or credentials detected	Use `--all`, examine the credential sources above, and examine the home-directory overrides and `PATH`.
`token_expired`, shown as `token expired`	The stored token is past its expiry. ASU never refreshes tokens. Use the tool named on the `via` line so it refreshes the token, then run ASU with `--fresh`.
`missing_credentials`, `invalid_credentials`, or `unauthorized`	Sign in or refresh through the provider's CLI, then run ASU again with `--fresh`. A successful CLI login helps only if ASU supports its credential store.
`credential_read_error`	Make sure that your current user can read the credential file or store.
`timeout`, `rate_limited`, or `http_error`	Examine the connectivity and the provider status. Wait before you retry after a rate limit. Use `--fresh` to bypass a cached failure.
`invalid_response`	The provider may have a new response schema. See the known limitations.
Usage looks stale	Examine `fetchedAt` and `cached`, then use `--fresh`. ASU cannot make the provider update its figures sooner.
One provider fails but the command exits with zero	Exit code `0` means that at least one provider succeeded. Examine the `availability` of each provider.
`npx --yes @allixsenos/asu` runs an old version	npx reuses the first version it cached for a bare name and never looks again. Use `@allixsenos/asu@latest`, which resolves on every run, or remove the cache with `rm -rf ~/.npm/_npx`. ASU prints a one-line notice on stderr once a day when a newer version exists.

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.