A Claude account hits its limit
Each agent uses one profile: one Claude login. When the account reaches its usage limit, the turn ends with a limit error. fleet pauses the profile and every agent that uses it. At the reset time, the agents continue.
| Fact | Value | Code |
|---|---|---|
| How fleet finds the limit | HTTP 429, or text that matches usage limit, hit your limit or limit reached |
fleet/internal/driver/claude/claude.go |
| The reset time | From the rate_limit_event, or from the error text |
claude.go |
| No reset time known | Wait 1 h | fleet/internal/supervisor/supervisor.go (UsageWait) |
| The check for the reset | Every 15 s | fleet/internal/creds/limiter.go, fleet/internal/server/recover.go |
| A gate before the limit | usage_threshold in serve.yaml: no new turn above this percent. 0 turns it off. |
fleet/internal/registry/registry.go (UsageGate) |
| Pacing a burst | pace in serve.yaml (#449): a new turn starts only while the five_hour reading plus turn_cost for each turn of the profile in flight stays under five_hour; max_concurrent caps the turns of a profile that sets none. A live chat waiting for input is not in flight: the node names it in its heartbeat's idle list, and an older node that sends none counts every lease. Incident agents go first and are not paced. |
fleet/internal/sched/pace.go |
| Spreading over profiles | A spawn with no --profile takes the user's profile with the most room (#460, Pace.Spread); a queued turn that fleet placed and that has not started moves to another profile with room when its own holds it (agents.profile_auto, ruling 2026-11-11 23:42). |
fleet/internal/sched/pace.go, fleet/internal/api/spread.go, fleet/internal/node/spread.go |
- The readings come from the turn's own output stream. The server keeps them when the turn ends, and the Claude usage panel shows them. fleet does not ask a vendor API.
- Each
rate_limit_eventnames one binding limit, and itsunifiedWindowsholds every window (five_hour,seven_day, ...). fleet keeps a reading for each window, soseven_dayis fresh after each turn, not only after a warning (#302).fleet profile ls --jsonshows each reading withobserved, the end of the turn that read it. A worker token gets 403. - Pacing (#449). A reading comes only when a turn ends, so a burst of turns that start together
all see the same low reading.
paceadds the expected cost of the turns in flight:pace: {five_hour: 80, turn_cost: 5}lets 16 turns start on a profile at 0%, 6 at 50%, none at 80%. A held agent staysqueuedand its reason names the profile, the reading and the reset time ("profile X is at 62% of its 5-hour window with 4 turns running ...; the window resets at 22:40 UTC").turn_costdefaults to 5: on 2026-11-11 about 20 turns used a whole window in 15 minutes. Turns are counted on every node, by their agent leases. - Incidents first (#449). An agent whose ticket is an open issue labelled
type:incidentis claimed before the other agents and is not paced: the part of the window above the budget is the reserve it runs on. The label is read from the Work page's kept data, so it needsforgejo_urland a channel with the repo. A limited profile andusage_thresholdstill hold it. - Spreading (#460). One profile at its pace cap while another sits idle wastes the idle one. The
room of a profile is the pace budget (100% with no
pace) less itsfive_hourreading andturn_costfor each turn: at spawn its turns in flight and its agents queued (so a burst spawned at once alternates), at a claim its turns in flight. Left out: alimitedprofile, one atusage_thresholdor at its own or the pace'smax_concurrent, a removed one, the box login in a fleet with more users, and profiles of another kind or driver than the default (for a move: than the agent's profile). A tie goes to the default. The spawn writesprofile_auto: trueonagent.spawn; a move writesagent.profilewithauto: true, and a move by hand (fleet agent profile) clears it. Only an agent withprofile_auto,queuedand 0 turns moves: an agent with a conversation stays on the account that holds it. A move is logged (profile move: ...in the scheduler log). Moves happen on node claims; the server's own local scheduler does not move. - A paused agent spends no retry.
- A login that does not work also pauses the profile, with the reason
auth. Telegram reminds the owner at most each 6 h (fleet/internal/creds/keeper.go). - The API can pause or resume a profile by hand:
POST /v1/profiles/{id}/pauseandresume. - To move one agent to another profile:
fleet agent profile <agent> <profile>. - Not built, and rejected on purpose: automatic change to another profile at the limit. The
spec rejects it (
docs/fleet/spec.md).fleet profile rotatechanges the secret of a profile. It does not change the profile of an agent. - No Telegram message goes out for a usage limit.