
runway
Switches subscriptions with claude-swap before a usage limit stops the work, resumes a session that a limit stopped, and, with tidy, suggests compacting before a long limit.
- GitHub stars
- 7
Install
/plugin install runway@jmcarthurRun it inside Claude Code after adding the marketplace with /plugin marketplace add jmcarthur/claude-plugins.
Contents
Discovered from sourceAgents 2
runway
Runway keeps a Claude Code session working through usage limits. With several subscriptions, it switches to another before a limit stops the work. When a limit stops a turn anyway, it switches or waits, then resumes the session if Claude Code's own auto-continue does not.
Install
claude plugin marketplace add jmcarthur/claude-plugins
claude plugin install runway@jmcarthur
Then run /reload-plugins in each open session. The
top-level README covers updating.
Switching uses claude-swap (cswap),
which /add-account installs for you. Without it, runway still resumes a
session that a limit stopped.
Quick start
- Run
/add-account. It installs claude-swap if needed (with uv or pipx) and adds the subscription you are logged in to. - Run
/loginfor another subscription (without/logoutfirst), then/add-accountagain. Repeat for each subscription. - Work as usual. When a usage window would reach 99% within about 35 minutes, runway switches every session on the machine to another subscription.
When a subscription's login expires, /login to it again: runway stores the new
login in claude-swap. To leave a subscription out, run cswap disable N.
How it works
- Runway tracks how fast the work uses each window (5-hour, weekly, and model-specific ones such as Fable) and switches before one fills. It picks an account that has room in both its 5-hour and weekly windows, and that would not near either limit at the current pace. Among those, it takes the one whose weekly window resets soonest, because that unused room is lost first.
- When a limit stops a turn, runway switches at once, or waits for the first account to recover, then prompts the session to continue.
- Without another account, it resumes the session a little after the reset, if auto-continue has not.
- A switch moves every session on the machine, so the sessions share one plan, and only one of them switches before a limit.
- Setup problems and failed switches show in the status line and in a desktop notification.
- With tidy, a large session that faces a long limit gets a note to compact before it stops, to try to avoid a large cache miss.
Runway logs its events to ~/.claude/runway/<session-id>.jsonl.
Settings
Set these in /config, or under pluginConfigs["runway@jmcarthur"].options in
~/.claude/settings.json. An empty or out-of-range number gives its default,
and a toast at session start names it.
| Setting | Default | Meaning |
|---|---|---|
compactBeforeLimitTokens | 300000 | Smallest context for the note to compact before a limit. 0 stops it. |
switching | true | Switch accounts with cswap before a limit. |
switchMaxWaitMinutes | 30 | Switch when a window would reach 99% within this many minutes, plus 5. |
remoteControlRestore | true | Turn Remote Control on again after a switch. |
notifications | true | Desktop notification when switching fails. |
More
The reference covers the details: how runway measures the burn and picks an account, switches that make room before a weekly reset, model limits, new logins, the resume schedule, and the note to compact.
runway reference
How runway works, in detail. For what it does and how to start, see the README.
Setup and notices
Runway switches accounts with
claude-swap (cswap) when it manages
two or more. /add-account installs claude-swap if needed (with uv or pipx) and
adds the logged-in account. For each other account, /login (not /logout) and
run /add-account again. Without claude-swap, runway still resumes a session
that a limit stopped.
Setup problems, such as an account whose login expired, show in the status line
and in a desktop notification. Runway never reports an account you take out of
rotation with cswap disable N. The status line shows one notice at a time, the
most pressing, and drops each once its cause is gone; a failed cswap command
shows until one succeeds, for at most an hour.
Account switching
- Model use. Runway notes which models each session requests, its subagents' included. A model-specific window (such as Fable) is in use for an hour after a request on a model in it, in any session.
- Readings and burn. For each window runway takes the newer of the last
response's rate-limit headers and cswap's reading, so an idle session's old
headers do not stand in for the account.
- A reading adds a point to the burn only when its own time is new.
- The burn is the work's: each account's burn comes from its own readings, and the work's is the highest across accounts in the last 45 minutes, so it carries over a switch.
- cswap reports whole percents, so a reading that has not moved counts as at most one percent over the time it held.
- Choosing an account. Runway picks the account itself and switches with
cswap switch.- The target must be short of 99% in its 5-hour and weekly windows, and must not be near its own limit at the work's burn. This is the same judgment that makes the active account near its limit, so no rule moves back to an account another rule just left.
- Among those, runway prefers one with room in every model-specific window in use, then the one whose weekly window resets soonest, because its room is lost first.
- An account without room in its all-models windows serves no model, so that room always decides first.
- Before a limit. When a 5-hour or weekly window, or a model-specific window
in use, would reach 99% at its burn rate within
switchMaxWaitMinutesplus 5 minutes, runway switches.- Without a burn rate yet, only 99% starts the switch: a fixed percent below it would switch hours early on the weekly window.
- A full model-specific window that no session uses causes no switch.
- Sooner reset. While no window is near its limit, runway also switches to
the chosen account when its weekly window resets sooner than the active one's,
so that its room is used before it is lost.
- It never moves to an account whose model-specific window in use is full, nor, until that window resets, to an account that a switch near a limit left.
- It waits an hour after any switch, and does not move while the active account's weekly reset is unknown.
- Repeated switches. A third switch within an hour shows a warning in the
status line and a notification. Each
switch-planevent in the log carries the accounts' readings and the burns it was decided on. - At a model limit. When a request, the main turn's or a subagent's, hits a model-specific limit while the account still has all-models room, runway switches at once to an account with room in that window and tells the session to retry, or tells it which account's window resets first.
- At a limit. When a limit has stopped the main turn, runway switches at
once to the chosen account. If none has room, it waits for the first account
to recover and switches to it. In both cases it then prompts the session to
continue, unless
autoContinueAtUsageLimitis off or the session already resumed. For a limit where the current account recovers first, see Resuming after a limit. - Several sessions. A switch moves the login of every session on the machine
and empties their prompt caches.
- The sessions share records and a plan in
~/.claude/runway/switch/, and only the session with the lowest id switches before a limit. Runway runs one switch at a time. - Runway records every switch, planned or at a limit, in the plan, so that every session sees it. After a switch, every session reads its rate-limit headers as those of the account it left, starts the hour of waiting before an optional switch, and counts the switch toward the repeated-switch warning. No switch moves back to an account that a switch at a limit left until that account recovers.
- Each switch also writes its time to
last-switch.jsonthere, which tidy reads.
- The sessions share records and a plan in
- Remote Control. A switch drops Remote Control. If it was on, runway turns it on again once the session shows it as off.
- A new login. Runway compares the account Claude Code is logged in to (the
oauthAccountof~/.claude.json) with cswap's accounts, by email and organization. It switches only while that account is cswap's active one, so a switch never replaces a login that cswap has not stored.- After
/loginto an account whose cswap login expired or that is not the active one, runway runscswap add, which stores the new login and makes the account active, and says so in a toast. Ifcswap addfails, a notification says why, and runway does not try again for that login. - After
/loginto an account that cswap does not manage, the status line says so, and Claude offers you/add-account.
- After
Runway never switches to an account that cswap disable took out of rotation.
Do not run cswap auto alongside runway; while a cswap auto loop runs, runway
does not switch, and the status line says so. A session whose
CLAUDE_CONFIG_DIR names another folder than ~/.claude (such as one started
with cswap run) takes no part in switching.
Resuming after a limit
When a limit stops the main turn and runway does not switch, it waits for Claude Code's auto-continue and steps in when that does not come:
- With a known reset (from the session's rate-limit readings, or cswap's), runway prompts the session to continue 2 minutes after the reset, if no turn started since the limit.
- Without one, it tries after 10 minutes, and after each try that hits the limit again it waits twice as long, up to an hour.
- With cswap, a limit that cswap reports cleared before its reset is resumed early, on the same schedule.
The status line says when runway will resume. Runway does nothing while
autoContinueAtUsageLimit is off. The stop-failure events in the log keep
Claude Code's error details, which show when its auto-continue fails.
Compacting before a limit
Runway tells the model once about the usage windows at 95% or more that reset more than an hour later, when no other account has room. An hour is the longest prompt-cache lifetime; runway does not detect the session's own.
For each window, the note gives its scope (all models, or one model family), account, use, reset, where runway read it and how long ago, and when it would fill at the recent burn. The model judges whether its work will stop, since it knows which models it will use, and compacts before the stop if it will.
The model cannot run /compact itself, so runway gives this note only while
tidy's compact tool, mcp__tidy__compact, is loaded in the session, and names
that tool in it. Without tidy, runway still switches and resumes, and gives no
note. The note needs a context of at least compactBeforeLimitTokens, runway's
own setting: tidy's compactNudgeTokens sets only its suggestions at a
boundary.
Runway logs its events to ~/.claude/runway/<session-id>.jsonl. Past 5 MB the
log moves to <session-id>.jsonl.1, replacing the one before.
Hooks 1
Sponsors
Details
- Marketplace
- jmcarthur/claude-plugins
- Source
- runway
- Category
- Community