When a usage limit is reached Added in 0.9.6

A Claude subscription has usage limits: a window of a few hours and a weekly one. When a turn runs into one, OAR does not fail the turn. It pauses it, tells you when the limit resets, and sends the work again by itself after the reset. You can also send it sooner or drop it.

What happens to the turn #

When Claude refuses a turn at the limit:

1. The agent's reply closes with a note. What the turn had written before the refusal stays above it.
2. The relay adds a message of its own to the conversation, held until the reset. It starts with Automatic message from OAR: the work was paused at the Claude usage limit., quotes what was refused (up to the last 5 requests, in the order you sent them, each cut at 4000 characters) and asks Claude to continue where it left off, subagents and background tasks included.
3. A banner appears above the composer with Resume now and Cancel.

The note says which limit it was and when the turn carries on. The windows are named 5-hour limit, weekly limit, weekly Opus limit, weekly Sonnet limit and extra usage limit:

⏸ Paused: the Claude 5-hour limit is reached. The turn carries on by itself at 22:01 UTC.

The banner above the composer says the same:

⏸ Paused at the Claude 5-hour limit — carries on at 22:01

In the banner, times are in your browser's time zone. The note is written by the relay, so its times are in the relay host's time zone and end with the zone's abbreviation. A time on another day carries the day, for example Thu 2 Oct, 09:00.

When it carries on #

A pause survives a restart of the relay. If the relay is down at the reset time, the held message is sent once it is back.

When a limit does not pause the turn #

A reset more than 8 days away is not taken for a usage window. The turn is not paused and fails as an ordinary failed turn. The same holds for a plain API error such as an API key's requests per minute, and for a window the account's extra usage covers: that ends no turn at all.

Resume now and Cancel #

The banner belongs to the conversation that was paused. For a pause that resumes by itself, the banner goes away when the time has come. A pause that waits for you stays until you use a button; after the reset its banner reads ⏸ Paused at the Claude weekly limit — the limit has reset. If no turn was paused any more, the notice says No turn was paused.

Messages you send meanwhile #

A conversation holds one such message. A message you send during the pause is delivered at once like any other. If Claude refuses it too, the held message moves back to the end of the conversation, quotes that request as well, and the wait starts over with the new reset time.

The warning before the limit #

From 90 % of a window on, Claude conversations show a banner above the composer. It is based on the reports Claude sends at the start of each turn, so it only appears for a subscription:

Claude usage at 96 % of the 5-hour limit — resets 22:01

It is about the account, so it shows in every Claude conversation, not only in the one that used the plan. A conversation with a paused turn shows the pause banner instead. Hide removes it until the next report (another window, another reset time, or the limit being reached). When the limit is reached and no turn is paused yet, the banner reads:

Claude 5-hour limit reached — resets 22:01. A turn sent before that is paused until then.

Neither line shows while the account uses its extra usage, and both go away at the reset time.

For agents and other sessions #

• Watching. A session that watches a paused session gets an error event of the kind usage_limit, with the note as its message. A paused turn has not ended, so it does not get a turn-end event.
• Not at work. While the held message waits, the session does not count as running a turn, and it does not count as queued work in the relay's status.
• Checking first. The usage action of relay_tool lists the paused sessions of a relay with their window, reset time, the time they resume (resumeAt) and whether they do so by themselves (auto), next to the account's latest report.

Notifications and host suspend #

The paused turn is reported like a finished one: it sends the push notification for a finished turn, with the note as its text. The later turn, after the held message is sent, gets its own. A queued host suspend waits for a pause that resumes by itself, but not for one that waits for you.

By provider #

The pause covers the Claude subscription's windows only.