AI Usage

Public npm package: @standardagents/sc-agent-usage-plugin.

standard plugin install @standardagents/sc-agent-usage-plugin --accept-capabilities surfaces

The package uses the published Standard Code plugin SDK. Its plugin ID stays quota-meters so upgrades retain configuration and account state.

One global sidebar card aggregates Claude and Codex accounts across machines. The card shows Claude's weekly All and Fable meters, followed by one weekly meter per Codex account. Multiple Codex accounts receive matching numbers in the sidebar and popover. The bordered card is titled AI Usage and declares a robot icon for Nerd Font viewers.

The popover shows every account together. Each identity and plan heads its own quota rows: 5h when reported, All, and Claude's Fable. Rows include usage and a compact reset countdown. Missing account-wide limits display --. Absent 5h and Fable limits have no row. Failed observations never replace a fresh successful report from another machine. Stale and unavailable accounts carry a short state label.

Meter treatment

Continuous full-height meters use seven local calendar days for cadence. Reset day permits 1/7 of the weekly quota; each local midnight advances the allowance. A subtle vertical line marks that allowance. Usage beyond it is checkered. At 100% pace, the marker occupies the gap after the bar so partial fills remain visible. Missing or expired reset times have no marker.

Provider labels use semantic identity colors in the sidebar and popover. Claude uses orange from the terminal palette. Fable uses a dimmer orange. Codex uses blue. Unknown providers use the foreground color. Scoped labels have a dim fallback for reduced-color rendering.

Every meter uses the same severity rules:

• Green: more than half a day below pace.
• Blue: within half a day below pace, through less than one day ahead.
• Orange: at least one day ahead, or at least 90% used.
• Red: at least three days ahead, or at least 95% used.

The highest severity wins. Fable also turns red when its Claude account's All quota reaches 100%; its own percentage remains unchanged. Five-hour meters have no weekly cadence marker and use blue below the 90%/95% thresholds. Unknown reset times use the same fallback.

Public CanvasSpec.themeColors recipes resolve on each viewer. Fills blend at 72% against the terminal background; markers blend the foreground at 75%. Orange mixes the terminal's red and yellow. Foreground fills and marker backgrounds use the same recipe. No machine tint or fixed RGB palette is used.

Data sources

Codex uses its CLI's stdio app-server with account/read and account/rateLimits/read. Window durations distinguish quotas. Server account IDs distinguish organizations sharing an email; normalized email is a fallback. API-key accounts have no subscription quota. No token refresh is requested.

Claude uses claude auth status --json and the installed client's read-only https://api.anthropic.com/api/oauth/usage endpoint. Credentials stay on the machine, in Keychain or the configured credential file, and are sent only to Anthropic. Redirects are rejected. The plugin never refreshes or writes tokens. Claude identity combines organization and email. Weekly All and Fable support limits[] as well as the older named weekly fields.

Executable discovery includes Mise shims, pnpm, and Bun directories for daemon environments. Only sanitized identities, labels, quota values, and generic status messages enter shared account state. Tokens and provider error bodies never enter shared state or surfaces.

Each machine owns one state key. The public state API discovers machine reports. Fresh successful observations take precedence over failed reads; percentages are never summed. Reports become stale after five minutes. Inactive machine reports expire after 24 hours. Failed refreshes retain the last valid windows until their reset times. Windows without reset times expire after 24 hours. Retained account identities expire after eight days. A valid refresh replaces retained usage. A sign-in change withdraws the previous local identity.

Settings

• refreshSeconds: provider refresh interval, 300–1800 seconds (300 default).
• enabledProviders: Claude, Codex, or both.
• accountLabels: account IDs mapped to display labels.

Shared reports refresh every 15 seconds. Provider reads are bounded and abort on disposal. Throttling postpones retries. Activation and manual refresh use the same per-machine provider guard. The guard persists across plugin reactivation.

Preview and verification

node quota-meters/preview.mjs opens the interactive preview. Left/right changes the day, Tab switches sidebar/details, and Q or Escape exits. --details starts with the popover. --plain and --json produce noninteractive output. node quota-meters/preview-export.mjs writes the portable script to ~/Shots/out. The preview uses the production meter models and sample data. It reads the terminal palette once and never accesses credentials. The host owns native window placement, chrome, and dismissal.

SDK 1.0.0-alpha.7-theme.0 supplies themeColors; the host must support that public contract and state.keys. Dependencies use the published npm package. Tests cover provider parsing, identity, report merging, cadence, color thresholds, account grouping, resets, and public SDK lifecycle behavior. The optional live Codex read probe is enabled with CODEX_LIVE_PROBE=1.

Account detail groups have shaded headers, aligned identities and plans, thin dividers, and tree guides. Quota columns align across accounts. Percentage colors match the meters, and a faint track keeps an empty quota meter visible.