Skip to content

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:

Terminal
Codex · Weekly 72% used · resets in 2d 4h

The meter's color follows how close you are:

MeterMeaning
NeutralBelow 80% used.
Warning80% to 99% used.
Danger100% or more. The tooltip says limit reached.
Plain glyphNo provider has reported a percentage yet.
Dimmed, with a ringThe 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:

Terminal
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                                           Settings

Every 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 or 0%.
  • 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:

Terminal
Claude Code                                    • Needs access
  Needs Keychain access                               [Allow]
  1. Click Allow. CompozyOS saves your consent (the Claude Keychain access switch in Settings) and the daemon refreshes Claude once.
  2. macOS may ask whether security may use the confidential information stored in Claude Code-credentials in your keychain. security is the macOS Keychain tool CompozyOS uses to read the login.
  3. 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 security read that item without asking. Choose Allow to grant access only for this request.
  4. 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 security after checking that the unlocked Keychain item already trusts that tool, includes its apple-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 denied with 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 security directly and may request authorization. If you click Deny, the row reads Keychain access denied with Try again.
  • If Claude Code has no login in the Keychain, the row reads Signed out · Sign in with Claude to read usage. Run claude, 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 .credentials.json file in its config directory, CompozyOS reads that file and never touches the Keychain. 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:

Terminal
$ 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:

Terminal
$ 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:

CommandWhat it does
compozy provider usage list codexShows one provider.
compozy provider usage list -o jsonPrints the full JSON envelope: every window, balance, spending cap, status, and error.
compozy provider usage refresh --wait 0sStarts the refresh and returns at once. Rows still collecting read refreshing.
compozy provider usage refresh --max-age 2mSkips providers measured in the last two minutes (the minimum is always 30 seconds).
compozy provider usage list --profile workReads 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:

Terminal
$ 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:

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 true

Changes 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 IDWhat you seeWhat CompozyOS reads
codexSession and Weekly limits, credits, planThe Codex login in $CODEX_HOME (~/.codex), through codex app-server. File credential store only, see Codex.
claudeSession, Weekly, per-model weekly limits, Extra usageClaude Code's login: .credentials.json in its config directory, or the macOS Keychain with consent.
openrouterKey spending cap, account balanceThe provider's bound API key.
vercel-ai-gatewayTeam balance, lifetime spendThe provider's bound API key.
zaiCoding plan limitsThe provider's bound API key. A key without a coding plan shows No coding plan on this key.
moonshotKimi Coding 5-hour, weekly, and monthly limitsThe provider's bound Kimi API key.
kimi-cliKimi Coding limitsThe Kimi CLI login (~/.kimi-code/credentials/kimi-code.json, or under KIMI_CODE_HOME).
cursorMonthly included usage, extra usageThe cursor-agent login (~/.config/cursor/auth.json, or under XDG_CONFIG_HOME).
geminiPer-model quotasThe 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:

Terminal
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.

StatusCollapsed rowExpanded row saysWhat to do
ok72% usedThe numbersNothing.
refreshingLoading…Loading…Wait. This is the first collection after a daemon start.
staleThe old percent, with a ringStale · updated 25 min ago, old numbers keptClick Retry or Refresh. The last refresh failed or the numbers are old.
signed_outSigned outSigned out · Sign in with Claude to read usageSign in with the provider's own CLI, then refresh.
needs_consentNeeds access, Access denied, or Login expiredNeeds Keychain access, Keychain access denied, or Refresh to reload your Claude loginClick Allow, Try again, or Refresh. See Step 5.
rate_limitedRate limitedRate limited · retry in 4mWait, or click Retry once.
errorCouldn't loadCouldn't load usageClick Retry. The JSON error.message says what failed.
unsupportedIn the closed group at the endUsage not available for this provider, or the reasonNothing, or follow the reason (for example the Codex credential store).
disabledIn the closed group at the endTurned off in settingsTurn 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.

toml
[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
KeyDefaultDescription
provider_usage.enabledtrueMaster 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>.enabledtruePer-provider opt-out. <id> is a canonical provider ID.
provider_usage.providers.claude.keychain_accessfalseConsent 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:

ToolInput (all optional)What it does
compozy__provider_usage_listprovider_idReturns the cached envelope for the session's profile. Read-only, never contacts providers.
compozy__provider_usage_refreshprovider_ids, max_age_secondsRefreshes, 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:

RoutePurpose
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/refreshRefresh all or some providers, with wait_ms (0–30000) and max_age_seconds.
GET /api/provider-usage/streamServer-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-usageRead 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

SymptomFix
No meter in the topbarCheck compozy config get provider_usage.enabled and that a supported provider is configured for this profile.
Claude row says Signed out right after AllowClaude Code has no login in the Keychain. Run claude, sign in, then refresh.
Claude row says Signed out on Linux or WindowsClaude Code keeps a file login there. Run claude, sign in, then refresh.
macOS prompt appears after each Claude token refreshRefresh 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 keyringSwitch Codex to the file store: see Codex.
Numbers differ between two profilesExpected. 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.