Claude Code spillover to OpenRouter: flip before the 429, flip back after reset.

It is the workaround where you point Claude Code at OpenRouter's API endpoint instead of Anthropic's once your Pro or Max plan hits a rolling 5-hour or weekly cap, so the agent loop keeps running on metered API pricing instead of stalling. You flip four environment variables (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY blanked, plus model overrides), and Claude Code happily talks the Anthropic protocol to OpenRouter as if it were Anthropic.

Per OpenRouter's own integration doc: ANTHROPIC_BASE_URL="https://openrouter.ai/api", ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY", ANTHROPIC_API_KEY="" (explicitly empty so it does not collide with your real plan key), and model overrides like ANTHROPIC_DEFAULT_OPUS_MODEL="anthropic/claude-opus-4.7" / ANTHROPIC_DEFAULT_SONNET_MODEL="anthropic/claude-sonnet-4.6" / ANTHROPIC_DEFAULT_HAIKU_MODEL="anthropic/claude-haiku-4.5". Reverse the same four vars to flip back to plan billing.

Because if you are already paying $100 to $200 a month for Claude Max, the plan is meaningfully cheaper than API rates for the same Opus/Sonnet traffic until you saturate it. Spillover only makes financial sense as overflow: run the plan as your default, flip to OpenRouter the moment a plan bucket is about to 429, and flip back when the 5-hour rolling window resets. That cycle is what people actually want when they search for 'spillover'. The Anthropic plan cannot give you 'wait it out' for the rest of the week, but it does give you another full bucket every five hours.

Two reasons. One, a 429 mid-agent-loop usually leaves Claude Code holding partial tool outputs and a pending edit; restarting from the same checkpoint costs you a few minutes of context rebuild every time. Two, you do not know which of the eight server-side buckets fired the 429, so you cannot tell if waiting 5 hours unblocks you or if the wall is a 7-day bucket that will not reset until Sunday. Flipping at 95% utilization on five_hour, before the wall, avoids both: no half-finished turn, and you keep the option to fall back to plan if the next bucket up is healthy.

ccusage reads the local ~/.claude/projects/<project>/<session>.jsonl files Claude Code writes to disk. That is local-truth: tokens that left your machine, priced against a model card. The plan caps live on Anthropic's servers as utilization fractions on /api/organizations/{org_uuid}/usage. They are different numbers, and ccusage cannot see the server one. ClaudeMeter reads the server one (the same JSON claude.ai/settings/usage renders) and exposes it as JSON, which is why a spillover hook can be driven by it. ccusage and ClaudeMeter are complementary; one tells you tokens-spent, the other tells you plan-quota-remaining.

Twelve lines. Run claude-meter --json, jq the five_hour.utilization fraction, compare it against a threshold (0.95 is a sane default), and either export ANTHROPIC_BASE_URL=https://openrouter.ai/api or unset it. The full snippet is in the Spillover hook section above. Wire it as a direnv hook, a starship/zsh prehook, or run it on a 60-second cron and write to a file your shell sources. The schema you depend on is documented in src/models.rs lines 18 to 28 of the open-source repo, so the field names will not move on you silently.

Yes, but on a different axis. OpenRouter's free models cap around 20 requests per minute and 200 per day per model. Paid OpenRouter credits raise that significantly and add automatic provider failover (if one Anthropic provider in their pool is throttled, OpenRouter routes your next request to a different one). For agent-loop spillover, you generally want paid OpenRouter credits, not free-tier; a single Claude Code session blasts past 200 requests/day on the first refactor.

On the Anthropic-routed providers in OpenRouter's pool, base model cost is the same per-token as Anthropic's API. OpenRouter takes its margin on top, which they publish per provider on each model page. So spilled-over traffic is a few percent more expensive than calling Anthropic's API directly with your own API key, and meaningfully more expensive per token than driving the same model through your plan. The point of the cycle is to use the plan as long as possible and only spill the overflow.

Same JSON, different field. claude-meter --json returns five_hour.resets_at as an ISO-8601 timestamp. Either compare it to now() in the shell hook ('if resets_at <= now and utilization < 0.5, flip back'), or just rerun the threshold check; the moment the 5-hour clock rolls, utilization on five_hour drops back near zero and the hook unsets ANTHROPIC_BASE_URL on its next tick. ClaudeMeter's menu bar shows the same number as a relative duration ('in 4h 12m'), so eyeballing it works too.

Nothing changes there. Spillover traffic flows through OpenRouter's API key, which is billed against your OpenRouter account, not your Claude plan. The plan-side buckets keep their utilization frozen until the rolling window rolls. So you can spill over for an hour, watch claude.ai/settings/usage stay still, and then spill back the moment your bucket comes off the wall. The two billing surfaces never cross.