Usage & Metrics

Workbench surfaces three related but distinct views:

Composer usage meter — small battery indicator next to the mic button in every chat composer. Always visible for Codex / OpenAI / OpenRouter / Ollama sessions (driven by Workbench’s per-turn token records). For Claude-family sessions, the meter is greyed out until you opt in to the Claude Code Usage experimental toggle, at which point it surfaces real Anthropic subscription quotas.
Claude Code subscription panel — the deeper Settings > Usage view, gated by the same toggle. Shows session / weekly limits and resets.
Workbench metrics — local activity (workspaces, sessions, commits, slash commands). Computed from Workbench’s database; never sent off-machine.

Context cost health icon

A passive icon in the composer toolbar tracks per-turn cache-read token usage and escalates through color stages as costs rise:

Color	Meaning
— (hidden)	Below yellow threshold — no icon shown
Yellow	Cache-read tokens crossed the yellow threshold
Orange	Cache-read tokens crossed the orange threshold
Red	Cache-read tokens crossed the red threshold

The thresholds are configurable in Settings > General under the Yellow threshold, Orange threshold, and Red threshold fields. The icon is informational only — it doesn’t block sends or trigger compaction. Hover for the exact token count.

Composer usage meter

The composer indicator picks a data source per backend:

Backend kind	Data source	Always-on?
Anthropic / Custom Anthropic	Anthropic OAuth Usage API (subscription quotas)	Off by default — gated by the Claude Code Usage toggle
Codex Native / Codex Subscription	Live Codex `account/rateLimits/*` quotas (Session 5h + Weekly) when available; falls back to local-aggregate tokens with a plain `Codex` label until the first rate-limits push lands	Yes
OpenAI API / Custom OpenAI / OpenRouter	Local-aggregate tokens + OpenRouter `/credits` balance when the active endpoint is OpenRouter	Yes
Ollama	Local-aggregate tokens	Yes

Local-aggregate data comes from the chat_messages.input_tokens / output_tokens / cost_usd columns Workbench already writes for every turn. Nothing leaves your machine for those backends.

Claude Code subscription panel

The Settings > Usage panel shows your subscription type, rate-limit tier, and current consumption against your plan. Open it from the sidebar footer or via the /usage slash command.

This panel is gated by the Claude Code Usage experimental toggle (off by default). When the toggle is off, Workbench never reads your Claude Code OAuth tokens for usage data — they stay strictly in the keychain / .credentials.json for the claude CLI’s own use. Enable it in Settings > Experimental if you want the panel. Requires a Pro or Max plan with standard login (env-var auth tokens like CLAUDE_CODE_OAUTH_TOKEN lack the OAuth scopes the API needs).

Claude Code sign-in itself is separate and always available in Settings > Models. Usage credential failures reuse that same sign-in flow.

The data comes from the same usage API your Claude Code CLI hits. Workbench caches the result for 5 minutes to avoid hammering the endpoint, and backs off for 2 minutes if a fetch fails (e.g. a rate limit). To force a refresh, close and reopen the panel.

To dive into the full Anthropic-hosted dashboard:

Click Open in browser in the panel, or
Use the /extra-usage slash command.

Both deep-link to claude.ai/settings/usage. The browser session uses your existing Anthropic login, not anything Workbench is holding.

Usage bars and quota types

The panel surfaces multiple independent quota bars when your plan has them:

Quota	Description
5-hour session	Rolling session window usage
Weekly all-model	Combined weekly cap across all models
Weekly model-specific	Per-model weekly cap (e.g. Fable, Opus). Workbench discovers the first model-specific weekly limit from the API and renders it as a third bar alongside the 5-hour and weekly all-model bars. Omitted when no model-specific limit exists on your plan.
Extra usage	Overage credits, when your plan includes them

Each bar shows its own reset countdown inline — the time remaining until that specific quota resets — so you can tell at a glance when capacity frees up.

Multi-provider usage

For non-Claude backends, usage meters display without the experimental gate:

OpenRouter — remaining OpenRouter credits (polled from the /credits endpoint with your configured key).
Ollama — local-aggregate token counts; no remote API needed.

These meters are always visible when the corresponding backend is active. They use the same composer-bar UI but pull from Workbench’s local database rather than Anthropic’s subscription API.

Parallel agents and your plan

Workbench can run multiple agents in parallel git worktrees, but Anthropic’s plan terms treat Pro/Max usage as “ordinary, individual” use. Keep parallelism conservative (1–3 agents) unless you’ve moved to API-key billing.

Workbench metrics

The Metrics view shows Workbench’s view of your activity — derived entirely from local data.

Dashboard metrics

Metric	Meaning
Active sessions	Sessions currently running an agent turn.
Sessions today	Sessions started in the last 24h.
Commits today	Commits authored across all workspaces today.
Additions / deletions (7d)	Lines added / removed across all workspaces in the last 7 days.

Per-workspace metrics

Each workspace gets its own card with:

Commit count and net additions / deletions on the workspace’s branch.
Latest session turn count.
Total input / output / cache tokens for the latest session, when the underlying CLI emitted them.

Analytics

The deeper analytics view exposes:

Repo leaderboard — workspaces ranked by activity over a configurable window.
Heatmap — session activity by day of week and hour of day, like GitHub’s contribution graph.
Turn histogram — distribution of turn counts per session.
Top slash commands — which commands you actually use, ordered by frequency.
Recent sessions (24h) — a session-dot timeline of the last day.

These are designed to surface your own patterns. There’s no telemetry; the queries run against your local database and never leave the machine.

Context overflow recovery

When a long session fills its context window, Workbench can recover automatically instead of surfacing a raw error.

Automatic compaction on overflow

Enabled by default (Settings > General > Automatically compact context on overflow). When the agent returns a “prompt is too long” error — whether via a structured result or on stderr before the process exits — Workbench compacts the conversation context and retries the failed turn once, without inserting a synthetic /compact message into the chat timeline. The chat status shows Compacting context… during recovery.

If automatic recovery fails, the error banner shows a Compact & Retry button so you can re-attempt compaction and retry the failed turn without retyping your message. Your original turn is preserved until you send a new message or the session is torn down. You can also switch to a larger-context model via the link in the same banner.

Disable the toggle to handle overflow manually — run /compact yourself or switch models before continuing.

Proactive compaction

Rather than waiting for a turn to fail, Workbench can compact before the context window overflows. Set Settings > General > Proactive compaction threshold (%) (default 85%) and, when context usage crosses that percentage of the model window, the next turn is compacted automatically before it runs. The threshold reuses the same token count that drives the chat context meter, so it tracks exactly what the meter shows. If the active model doesn’t report a model_context_window, proactive compaction can’t compute a percentage and is skipped — reactive compaction on overflow still applies. Set the threshold to 100 to disable proactive compaction entirely.

Rate-limit auto-retry

When a turn fails because the provider returns a rate-limit error, Workbench can wait and retry automatically instead of surfacing the failure. Enable Settings > General > Auto-retry on rate limit (on by default). Retries use exponential backoff: the wait starts at Rate-limit base backoff (seconds) (default 5s) and doubles each attempt, capped at Rate-limit max backoff (seconds) (default 120s), for up to Rate-limit retry attempts tries (default 3).

Provider rate-limit responses don’t include a retry-after header, so the wait is an estimate rather than an exact server-provided delay. The worst-case hold before Workbench gives up is roughly max backoff × retry attempts (about 6 minutes at the defaults). While a retry is pending, the chat shows a holding banner with a live countdown to the next attempt and a pointer to where these limits are configured, so a long backoff never looks like a hang. Disable the toggle to have rate-limit failures surface immediately instead.

80% context warning

When the context meter crosses 80% capacity for the first time in a session, Workbench shows a toast recommending /compact. The warning re-arms after a compaction drops context below the threshold, so it fires again only if the session fills back up.

Deleted-workspace summaries

Archiving a workspace doesn’t drop its activity from the metrics. Closed-out work still counts toward leaderboards and 7-day deltas, so the dashboard keeps an honest picture of recent throughput even after cleanup.

What gets queried over the network

Source	Data	Trigger
Anthropic usage API	Subscription, tier, token totals	Opening the Usage panel; cached 5 min
OpenRouter credits API	Total, used, and remaining credits for OpenRouter-backed sessions	Composer meter refresh; 5-min cadence while active
Local SQLite	Everything else	On view; never network

See Privacy for the full network-activity ledger.