Agent Usage Limits and Profile Failover

Providers meter in windows rather than in a single monthly bucket. A session window resets a fixed number of hours after your first request in it, so heavy morning use can leave you throttled in the afternoon even though the month has barely started. A weekly window sits on top of that and is the one that ends a bad week early.

Two windows interacting is why a naive percentage is useless. Sixty percent of your weekly budget consumed is fine on a Friday and alarming on a Monday. What you want is a verdict about pace: at this rate, do you finish the window or run out first.

Workspace puts a usage gauge in the titlebar. It reads both the session and the weekly window and renders a pace verdict rather than a bare number, so the question it answers is the one you asked: am I going to run out. Provider coverage starts with Claude, and a broader catalog is in development.

The reads are done with your own credentials, in the app. The token is held in memory for the one request that used it and then dropped, and the percentages are kept locally so the gauge can draw a history. Nothing about your usage is brokered through us, which is a property of the whole design rather than a feature of the gauge.

A profile is the set of environment pointers an agent launches with: which account, which config directory, which key name. Switching profiles switches which credentials the CLI picks up on its next launch, and that is the entire mechanism.

Deliberately, a profile does not contain your secrets. Workspace runs a deny-list sanitizer over a profile before it is saved, and a value that looks like a secret is refused rather than stored. Credentials belong to the agent CLI and to your operating system's vault, and the app never sits between you and your provider.

Agent CLIs signal a usage limit in their output. Workspace reads that signal from the same stream it is already rendering, so the response is immediate rather than polled. What happens next is your choice, and the default is deliberately conservative.

• By default you get a toast. The pane is yours to decide about
• Auto-failover is opt-in, per workspace, and off until you turn it on
• With it on, a limit interrupts the agent and relaunches the same pane on the next profile, resuming the session where the CLI supports resume
• Scrollback survives the switch, so you keep the transcript of what the agent did before it stalled

The metering side of the system offers a suggestion rather than an action. When a threshold is crossed, it tells you failover is available and lets you take it. Automatic anything is opt-in, and the thing being automated is a relaunch rather than an approval, which is the same reasoning behind the reviewer gate in a swarm.

It cannot un-spend the tokens, and it cannot move a running process to a new account. A pane already running keeps the environment it launched with, because that is how process environments work. Failover applies to the relaunch, not to the process in flight, and nothing silently re-authenticates behind your back.

It also cannot rescue a swarm that was sized wrong. Four agents on one repository draw down a session window roughly four times as fast, and no amount of failover fixes arithmetic. Size the swarm to the window, and watch both in a surface that streams rather than polls so you see the stall the moment it happens.

• Keep a second profile configured before you need it, not during the outage
• Leave auto-failover off on workspaces where a mid-task account switch would confuse a reviewer, and on where throughput matters more
• Watch the weekly window, not the session window, when planning a long refactor
• Read the pace verdict; a raw percentage tells you much less

Profiles, the gauge, and failover behavior are documented in the usage meters docs. For how this fits with the rest of agent control, see the AI agent command center.