Every account gets a score:

• Active 5h window: unused % ÷ hours until reset, so capacity that's about to expire is used first.
• No active window: a flat 10.
• Weekly pacing: multiplied by how far the account is behind an even pace through its week (its weekly cap ÷ 7 per day, so 11.4 %/day for an account capped at 80 %) (up to weekly_factor_max, 50×). An account with lots left just before its weekly reset is drained first.
• Primary: multiplied by primary_bias.
• Excluded: at ≥ 95 % of its 5h window, ≥ 98 % of its week, rate-limited, or with an expired login.

A 429 from Anthropic marks the account blocked and the request is retried once on the other.

Every request re-sends the whole conversation, so nothing is lost when it changes account, but the prompt cache is per account. The first turn after a move re-sends the context uncached, about 10× the cost of a cached turn. So the proxy decides per conversation (conversations.py):

When it asks, your message is held until you answer (up to 2 minutes), and the answer decides where that message goes:

Cancel only stops this message; nothing reaches Anthropic. To start fresh, type /clear (or /compact to keep a summary). claude-roulette status lists recent conversations with their title, account, size and cache state; questions name the app (Claude Code or Science) and the conversation's title.

add NAME starts Claude Code with a temporary, empty config folder. You /login and /exit; the tool copies the new login into its own Keychain item (service claude-roulette) and deletes the temporary item and folder. Each account therefore has its own login session, separate from Claude Code's, and the two never fight over a refresh token.

• Secrets are passed to security on stdin, never on a command line where ps could see them.
• They're never logged or written to state.json.
• Tokens are refreshed before they expire and the new refresh token is saved back.
• An account whose login is rejected (invalid_grant) is skipped until you run add again.
• On Linux, logins fall back to a chmod-600 ~/.claude-roulette/tokens.json.
• Tokens are only ever sent to api.anthropic.com and Anthropic's token endpoint; neither is a setting. With CLAUDE_ROULETTE_HOME set (meant for tests), the Keychain is not used at all.

What the Keychain doesn't protect against: the items are written by Apple's security tool, and macOS lets that tool read them back without asking. So any program running as you can read these logins, just as it can read Claude Code's own. Treat malware on your account as having all of them.

Each machine gets its own logins, so two machines never invalidate each other's.

• LaunchAgents in ~/Library/LaunchAgents: com.user.claude-roulette (the proxy, always restarted) and com.user.claude-roulette.bar (the menu bar app). Both start at login.
• ~/.claude/settings.json: adds "env": {"ANTHROPIC_BASE_URL": "http://127.0.0.1:8789/k/<key>"} and makes the file readable by you only.
• VS Code user settings (and Insiders, Cursor, VSCodium if present): adds the same variable to claudeCode.environmentVariables.
• A daily pmset wake at the earliest schedule time, if you have no repeating power events of your own (see below; --no-wake skips it).
• launchd's environment (only with the Science add-on on): launchctl setenv ANTHROPIC_BASE_URL …, for Claude Science. Every app opened afterwards inherits it, so the proxy also sees requests from other apps and shells. Those without a claude.ai login (e.g. an API key) are passed through untouched.

In the files, only that one key changes; comments and formatting are kept. The original is backed up as settings.json.bak-roulette. Files that can't be parsed are skipped and reported. uninstall removes the entries if they still point at this proxy.

<key> is a random secret in ~/.claude-roulette/proxy-key. The proxy refuses any request without it, so other programs that can reach the port (containers via host.docker.internal, other users on the Mac, web pages) can't use your accounts. run, status and install also check that whatever answers on the port knows the key before trusting it.

While the proxy is down, sessions that use these settings fail with a connection error. Setting only ANTHROPIC_BASE_URL is a documented setup that keeps your claude.ai login and subscription billing.

install records the path of the Python that ran it, so re-run install after reinstalling the tool.

After sleep, the proxy fetches fresh usage straight away. A 07:00 ping missed while asleep runs on wake, up to 09:00. To make sure the Mac is awake for it, install sets a daily wake at the earliest schedule time (sudo pmset repeat wakeorpoweron MTWRFSU 07:00:00; sudo asks for your password; skip with --no-wake). macOS allows only one repeating wake, so if you already have your own repeating power events, install leaves them alone and prints the command instead. uninstall removes the wake if it's still the one install set. With the lid closed, a MacBook wakes only briefly without turning the display on; the ping runs under caffeinate to finish, which holds the Mac awake only on AC power.

Claude Science requests are recognised by X-Anthropic-Surface: operon, and the conversation id is read from metadata.user_id (session_id = <root>[:<frame>][:<lane>]). install adds "addons": ["science"] to config.json when it finds Claude Science.app and you haven't set addons yourself. With it on, every request of a conversation (main agent, frames, side tasks such as the title generator) is pinned to one account, exactly like a Claude Code session. status lists Science conversations with all others.

Science's background service takes its API URL only from its environment (ANTHROPIC_BASE_URL), inherited from launchd when the app starts; it doesn't read ~/.claude/settings.json. So install puts the proxy URL into launchd's environment, and the proxy sets it again at every login, because launchd forgets it. Quit Claude Science completely and open it again after install: until then it sends requests on its own login, bypassing the proxy and your account_caps. install and status warn while a running Science service doesn't use the proxy. If Science starts at login before the proxy does, reopen it once. uninstall, or "addons": [] followed by install, removes the variable again.

Set "science_mode": "observe" to let Science requests through on Science's own login instead; they still show up in serve.log. An explicit claude-roulette run --account still wins over a pin.

Add-ons live in the package as separate modules; addons.py documents the interface.

uv tool install --editable .            # `claude-roulette` runs this checkout
uv sync           # .venv with the package, all add-ons and dev tools
uv run pytest     # never touches the real Keychain
uv run ruff check

launchd can't read files in ~/Documents, so an editable install of a checkout there can't run the background service. Keep the checkout elsewhere, or use a non-editable install (uv tool install --reinstall .).

Tested against a fake upstream: login import and cleanup, token refresh, per-request switching, 429 failover, pass-through, pinning, dead-login detection, secrets kept out of logs.

Verified against Anthropic (2026-10-25, Claude Code 2.1.308): the usage endpoint, token swapping, the rate-limit headers, and that sessions keep their cache through the proxy. Not yet seen in practice: a real token refresh (look for "refreshed access token" in serve.log).