Provider usage
See how much of each provider subscription you have used and when it resets, from the topbar, the Usage app, the CLI, and native tools.
16 min read9 pages in Agents
On this page15
- Before you start
- Step 1: Find the usage meter in the topbar
- Step 2: Open the popover
- Step 3: Refresh
- Step 4: Open the Usage app
- Step 5: Allow Claude on macOS
- Step 6: Read usage from the terminal
- Step 7: Choose what CompozyOS collects
- Supported providers
- Codex: file credential store
- Statuses and what to do
- Configuration
- For agents and scripts
- Troubleshooting
- Related pages
Provider usage shows how much of each subscription you have used and when each limit resets, without leaving CompozyOS. Claude Code has a 5-hour session limit and weekly limits, Codex has session and weekly windows plus credits, and API-key providers have balances and spending caps. The daemon collects these numbers for the active profile, keeps them fresh in the background, and shows them in the topbar, in a Usage app, in the CLI, and to agents through native tools.
By the end of this page you will have read your usage in the topbar, opened the details, refreshed them, allowed Claude to be read on macOS, read the same numbers from the terminal, and changed what CompozyOS collects.
Before you start
- CompozyOS is running (
compozy status) and the desktop app or Web UI is open. - At least one supported provider is set up and signed in for the active profile, for example
Codex (
codex login) or Claude Code (claude, then/login). See supported providers for the full list. - There is nothing to turn on. Provider usage is on by default.
CompozyOS only reads the login each provider already keeps. It never signs you in, never opens a browser, and never asks for a password while you browse the usage views.
Step 1: Find the usage meter in the topbar
Look at the right side of the topbar, between All desktops and the notification bell. The Provider usage control is a small meter. It shows your most used limit across all providers.
Hover it. The tooltip names that limit:
Codex · Weekly 72% used · resets in 2d 4hThe meter's color follows how close you are:
| Meter | Meaning |
|---|---|
| Neutral | Below 80% used. |
| Warning | 80% to 99% used. |
| Danger | 100% or more. The tooltip says limit reached. |
| Plain glyph | No provider has reported a percentage yet. |
| Dimmed, with a ring | The numbers are old. The tooltip says when they were taken. |
The control appears once the active profile has at least one provider to show. It is absent when provider usage is turned off.
Step 2: Open the popover
Click the meter, or focus it and press Enter. A Provider usage popover opens:
Provider usage Updated 1 min ago ⟳
─────────────────────────────────────────────────────────────
› Claude Code Max 20x 88% used
› Codex Pro 72% used
› Cursor Agent • Signed out
› 6 providers without usage data
─────────────────────────────────────────────────────────────
Open Usage SettingsEvery row starts collapsed to one line: the provider, its plan, and how much of its most used limit
you have used. A row without numbers says why in a word or two instead, such as Signed out.
Providers you have not set up read Signed out; Step 7
shows how to hide the ones you do not use. Providers CompozyOS cannot read usage for are folded into
one closed group at the end, such as 6 providers without usage data. Open it to see each name and
its reason.
Click a row to expand it. The detail starts with the full status message and its button, when the
row has one, then lists every limit with its own bar and reset time, then
balances and spending caps in their own units (120 credits, $12.40), the account, where the
numbers came from (for example Claude Code OAuth), and when they were measured.
Things to know about the popover:
- Opening it asks the daemon to update rows older than one minute. Rows keep their numbers while they update.
- A limit without a known percentage shows
Usage unknown, never an empty bar or0%. - A countdown appears only when the provider reports an exact reset time.
- When there are more rows than fit, the list scrolls. Its scroll bar appears only while you hover or scroll the list.
- Press Esc to close. Focus returns to the meter.
Step 3: Refresh
Click ⟳ in the popover header. The daemon asks every provider again and the rows fill in as results arrive. The daemon refreshes in the background every five minutes either way, so you only need this button after something changed, such as signing in to a provider.
A provider measured less than 30 seconds ago keeps its current numbers. A row that cannot refresh says why when you expand it, and offers a button when you can fix it from here. See statuses.
Step 4: Open the Usage app
Click Open Usage in the popover footer. The Usage window opens with every provider as a collapsed row and its own ⟳ button. Expand the rows you want to compare. Providers without usage data stay in the same closed group at the end. It reads the same numbers as the popover and updates live. Use it when you want all limits side by side, for example before starting a long run.
Step 5: Allow Claude on macOS
On macOS, Claude Code usually keeps its login in the macOS Keychain instead of a file. CompozyOS
reads the Keychain only with your consent. The Allow button and the
Claude Keychain access setting appear only when the daemon runs on macOS. Until you allow it, the
Claude row reads Needs access. Expand it to see:
Claude Code • Needs access
Needs Keychain access [Allow]- Click Allow. CompozyOS saves your consent (the Claude Keychain access switch in Settings) and the daemon refreshes Claude once.
- macOS may ask whether
securitymay use the confidential information stored inClaude Code-credentialsin your keychain.securityis the macOS Keychain tool CompozyOS uses to read the login. - Click Allow to approve this read only, or Always Allow so later reads do not ask again.
Always Allow lets any program on your Mac that runs
securityread that item without asking. Choose Allow to grant access only for this request. - The Claude row fills in with Session, Weekly, and per-model weekly limits, plus Extra usage when your plan has it.
What happens next:
- The daemon keeps the Claude login in memory only and never writes it to disk.
- Background refreshes reuse the cached login. After expiry, an account change, or a daemon restart,
they can reload it through
securityafter checking that the unlocked Keychain item already trusts that tool, includes itsapple-tool:partition, and does not require confirmation. Claude Code token refreshes preserve this access, so they do not normally require another approval. - If those checks fail, the row reads
Keychain access deniedwith Try again. Click it on the host Mac to request authorization. Background refreshes do not attempt a secret read in that state. - If the item changes between the check and the read, macOS could briefly show a prompt. The daemon stops a background read after 1.5 seconds and reports that authorization may have been required, with Refresh for local recovery. This bounds the race; macOS does not offer this command a flag that absolutely forbids a prompt.
- Explicit Refresh uses
securitydirectly and may request authorization. If you click Deny, the row readsKeychain access deniedwith Try again. - If Claude Code has no login in the Keychain or a usable credential file, the row reads
Signed out · Sign in with Claude to read usage. Runclaude, sign in, then refresh. - If you sign in to Claude Code with another account, or sign out, CompozyOS drops the old login and its numbers.
- To withdraw consent, turn off Claude Keychain access in Settings → Provider usage. CompozyOS forgets the login right away.
When Claude Code keeps a usable .credentials.json file in its config directory, CompozyOS reads
that file and never touches the Keychain. On macOS, an expired or unreadable leftover file does not
hide the Keychain login: with Claude Keychain access on, CompozyOS reads the Keychain the same
silent way it does without a file. With access off, the row asks for Keychain access rather than a
new login. Linux and Windows read the file only. CompozyOS never rewrites either credential store.
If you reach CompozyOS from another device through the
Gateway, the row says
Approve on the host Mac: open CompozyOS there and refresh: only someone at the Mac that runs the
daemon can approve a Keychain read.
Step 6: Read usage from the terminal
compozy provider usage list prints the numbers the daemon already has. It never contacts
providers:
$ compozy provider usage list
PROVIDER STATUS TIGHTEST WINDOW USED RESETS IN UPDATED
Claude Code ok Weekly · Opus 88% 3d 2h 1m ago
Codex ok Weekly 72% 2d 4h 1m ago
Cursor Agent signed_out — — — —
Pi unsupported — — — —
Experimental: provider usage output may change.TIGHTEST WINDOW is the limit with the highest percentage used. UPDATED is how long ago the
numbers were measured.
compozy provider usage refresh asks the providers again, waits up to 15 seconds, and prints the
same table. Pass a provider ID to refresh and print only that provider. When a Claude row needs
Keychain consent, the table ends with the command that grants it:
$ compozy provider usage refresh claude
PROVIDER STATUS TIGHTEST WINDOW USED RESETS IN UPDATED
Claude Code needs_consent — — — —
Claude: Needs Keychain access. Allow it with: compozy config set provider_usage.providers.claude.keychain_access true
Experimental: provider usage output may change.A refresh from the CLI on the daemon's own machine counts as you asking, so on macOS it may read the Claude Keychain item once consent is on, and macOS may show its prompt.
Useful flags and forms:
| Command | What it does |
|---|---|
compozy provider usage list codex | Shows one provider. |
compozy provider usage list -o json | Prints the full JSON envelope: every window, balance, spending cap, status, and error. |
compozy provider usage refresh --wait 0s | Starts the refresh and returns at once. Rows still collecting read refreshing. |
compozy provider usage refresh --max-age 2m | Skips providers measured in the last two minutes (the minimum is always 30 seconds). |
compozy provider usage list --profile work | Reads another profile. Each profile has its own logins and its own numbers. |
--wait accepts 0s to 30s. Both commands exit 0 even when some providers end in an error
status; they exit 1 for a bad request:
$ compozy provider usage refresh --wait 90s
error: --wait must be between 0s and 30s (invalid_request)
$ compozy provider usage list nope
error: provider "nope" not found (provider_not_found)Full flag reference: compozy provider usage.
Step 7: Choose what CompozyOS collects
Open Settings → Provider usage, or click Settings in the popover footer:
- Show provider usage turns the whole feature on or off. Off removes the topbar meter and stops every usage request to providers.
- Refresh in the background sets how often the daemon refreshes: every 1, 2, 5 (default), 10, 15, or 30 minutes, or every hour. Opening the popover or pressing ⟳ still refreshes right away.
- Providers has one switch per configured provider that CompozyOS can read. Off stops collecting that provider, and it disappears from the usage views.
- Claude Keychain access (macOS only) is the consent from Step 5.
The same settings are config.toml keys. To turn usage off and back on from the terminal:
$ compozy config set provider_usage.enabled false
$ compozy provider usage list
Provider usage is turned off. Enable it with: compozy config set provider_usage.enabled true
$ compozy config set provider_usage.enabled trueChanges apply live. You do not need to restart the daemon.
Supported providers
CompozyOS reads usage for these providers. Every other provider appears with
Usage not available for this provider.
| Provider ID | What you see | What CompozyOS reads |
|---|---|---|
codex | Session and Weekly limits, credits, plan | The Codex login in $CODEX_HOME (~/.codex), through codex app-server. File credential store only, see Codex. |
claude | Session, Weekly, per-model weekly limits, Extra usage | Claude Code's login: .credentials.json in its config directory, or the macOS Keychain with consent. |
openrouter | Key spending cap, account balance | The provider's bound API key. |
vercel-ai-gateway | Team balance, lifetime spend | The provider's bound API key. |
zai | Coding plan limits | The provider's bound API key. A key without a coding plan shows No coding plan on this key. |
moonshot | Kimi Coding 5-hour, weekly, and monthly limits | The provider's bound Kimi API key. |
kimi-cli | Kimi Coding limits | The Kimi CLI login (~/.kimi-code/credentials/kimi-code.json, or under KIMI_CODE_HOME). |
cursor | Monthly included usage, extra usage | The cursor-agent login (~/.config/cursor/auth.json, or under XDG_CONFIG_HOME). |
gemini | Per-model quotas | The Gemini CLI login (~/.gemini/oauth_creds.json). |
A custom provider without a collector of its own reads usage through the collector of its
runtime_provider, for example a second Claude account configured with runtime_provider = "claude"
and its own CLAUDE_CONFIG_DIR in the launch command (bare NAME=value or an env prefix). Each
such provider reads only the login in its own config directory or its own bound key, and appears as
its own row; accounts never merge. A provider whose own ID has a collector always keeps it.
API-key providers use the key you already configured for the provider; see wrapped API-key providers. CompozyOS uses only the login or key that the profile's provider route resolves: it never borrows another profile's login, never reads browser cookies, and never writes to another tool's credential files. The one exception is Codex, which may renew its own login while it answers, exactly as it does when CompozyOS runs a Codex session.
Codex: file credential store
Codex can keep its login in a file (~/.codex/auth.json) or in the system keyring. CompozyOS reads
Codex usage only from the file store, so that it never triggers a keyring prompt. When
$CODEX_HOME/config.toml sets cli_auth_credentials_store = "keyring" or "auto", the Codex row
reads:
Codex keeps its login in the system keyring; usage needs cli_auth_credentials_store = "file"To fix it, set cli_auth_credentials_store = "file" in ~/.codex/config.toml (or remove the line),
then sign in again with codex login so Codex writes auth.json. CompozyOS never changes this
setting for you. The codex executable must be installed; if it cannot start, CompozyOS reads the
same numbers over HTTPS with the login in auth.json.
Statuses and what to do
Every provider row has one status. The CLI prints the status name. The collapsed row shows a short cue; expanding the row shows the full message and its button.
| Status | Collapsed row | Expanded row says | What to do |
|---|---|---|---|
ok | 72% used | The numbers | Nothing. |
refreshing | Loading… | Loading… | Wait. This is the first collection after a daemon start. |
stale | The old percent, with a ring | Stale · updated 25 min ago, old numbers kept | Click Retry or Refresh. The last refresh failed or the numbers are old. |
signed_out | Signed out | Signed out · Sign in with Claude to read usage | Sign in with the provider's own CLI, then refresh. |
needs_consent | Needs access, Access denied, or Login expired | Needs Keychain access, Keychain access denied, or Refresh to reload your Claude login | Click Allow, Try again, or Refresh. See Step 5. |
rate_limited | Rate limited | Rate limited · retry in 4m | Wait, or click Retry once. |
error | Couldn't load | Couldn't load usage | Click Retry. The JSON error.message says what failed. |
unsupported | In the closed group at the end | Usage not available for this provider, or the reason | Nothing, or follow the reason (for example the Codex credential store). |
disabled | In the closed group at the end | Turned off in settings | Turn the provider back on in Settings → Provider usage. |
Numbers are kept when a refresh fails with the same login, marked stale with their original measurement time. They are dropped when the login changes, because they describe another account.
Configuration
[provider_usage] lives in your user config.toml (~/.compozy/config.toml). Workspace and
profile config files cannot set it.
[provider_usage]
enabled = true # false removes the topbar meter and stops collection
refresh_interval = "5m" # background cadence, 1m to 1h
[provider_usage.providers.cursor]
enabled = false # stop collecting one provider
[provider_usage.providers.claude]
keychain_access = false # macOS only: allow reading Claude Code's Keychain login| Key | Default | Description |
|---|---|---|
provider_usage.enabled | true | Master switch. false hides the meter, stops collection, and empties every usage read. |
provider_usage.refresh_interval | "5m" | Background refresh cadence, from 1m to 1h. |
provider_usage.providers.<id>.enabled | true | Per-provider opt-out. <id> is a canonical provider ID. |
provider_usage.providers.claude.keychain_access | false | Consent to read Claude Code's macOS Keychain login. Ignored on other systems; only valid for claude. |
See [provider_usage] for validation details.
For agents and scripts
Agents read the same numbers with two native tools, in toolset compozy__provider_usage:
| Tool | Input (all optional) | What it does |
|---|---|---|
compozy__provider_usage_list | provider_id | Returns the cached envelope for the session's profile. Read-only, never contacts providers. |
compozy__provider_usage_refresh | provider_ids, max_age_seconds | Refreshes, waits up to 15 seconds, and returns the envelope. |
An agent always works on its own session's profile. Its refreshes run in the background: they
reuse the cached login or perform the consented background checks described above, and respect provider rate limits. An agent also cannot
grant Keychain consent: the native config tools refuse
provider_usage.providers.claude.keychain_access, so only you can turn it on, in Settings or with
compozy config set.
Scripts can use the same HTTP and UDS routes as the CLI:
| Route | Purpose |
|---|---|
GET /api/provider-usage?profile=<name> | The envelope for one profile, with the topbar signal in tray. |
GET /api/provider-usage/providers/{id} | One provider's row. |
POST /api/provider-usage/refresh | Refresh all or some providers, with wait_ms (0–30000) and max_age_seconds. |
GET /api/provider-usage/stream | Server-Sent Events, or a WebSocket upgrade carrying the same frames: ready and provider_usage_changed, each with revision and boot_id. Re-read the envelope on each event. |
GET / PATCH /api/settings/provider-usage | Read or change the [provider_usage] settings. |
The envelope and the settings response carry a read-only keychain_supported flag, true only when
the daemon runs on macOS; clients use it to decide whether to offer Allow. A read filtered to one
provider returns tray: null.
Only the desktop app and the CLI on the daemon's own machine can request interactive Keychain authorization. Agents, paired remote devices, and app tokens always refresh in the background, and app tokens from another origin cannot refresh at all. No route ever returns a credential. Request and response schemas: Providers API.
Troubleshooting
| Symptom | Fix |
|---|---|
| No meter in the topbar | Check compozy config get provider_usage.enabled and that a supported provider is configured for this profile. |
Claude row says Signed out right after Allow | Claude Code has no login in the Keychain. Run claude, sign in, then refresh. |
Claude row says Signed out on Linux or Windows | Claude Code keeps a file login there. Run claude, sign in, then refresh. |
| macOS prompt appears after each Claude token refresh | Refresh once on the host Mac. CompozyOS reads through security, whose access survives the normal Claude Code rewrite. |
| Codex row says the login is in the system keyring | Switch Codex to the file store: see Codex. |
| Numbers differ between two profiles | Expected. Each profile has its own logins and keys. |
error: provider usage is turned off (provider_usage_disabled) | Run compozy config set provider_usage.enabled true. |
Related pages
- Providers: provider IDs, logins, and API keys.
- Profiles: separate logins per operator profile.
compozy provider usage: CLI reference.[provider_usage]: configuration reference.