Multi-account Claude proxy with automatic quota-based rotation for Claude Code.
It sits between Claude Code and the Anthropic API, holds several Claude Max (or API key) accounts, and moves to the next one when the current account gets close to its session or weekly limit. The session keeps running instead of stopping on a 429.
Node.js 20+ required.
npm install -g @karpeleslab/teamclaude
teamclaude login # browser OAuth, run it once per account
teamclaude server # start the proxy, shows the TUI
teamclaude run # in another terminal: Claude Code through the proxyAlready logged into Claude Code? teamclaude import takes its credentials instead of a fresh OAuth round. API keys, and one email holding accounts in several orgs, are covered in docs/accounts.md.
- Rotates to the next account when the 5h session or 7d weekly bucket reaches the threshold (98% by default), preferring the account whose weekly quota resets soonest.
- Tracks the per-model weekly cap separately, so an account out of Fable quota is skipped for Fable requests and still serves Opus and Sonnet.
- Tells a spent quota bucket apart from a per-minute rate limit and only rotates on the first one. Rotating on a rate limit would just move the burst to the next account and drop the warm cache, so it paces the same account instead.
- Paces requests onto a freshly switched account, so a herd of agents failing over at the same instant doesn't throttle it and cascade down the fleet.
- TUI with quota bars, reset countdowns, activity log, and settings you can change while it runs, including adding and removing accounts.
- Catches hardcoded
api.anthropic.comendpoints (the Claude Design MCP, for one) through a local MITM forward proxy, not only whatANTHROPIC_BASE_URLcovers. - Holds the request open until quota resets instead of returning 429 when every account is spent, so an unattended run finishes on its own (
holdSeconds, off by default). - Refreshes OAuth tokens before they expire and writes them back to config. Client refreshes pass through untouched.
- Takes any Anthropic-compatible API (DeepSeek, GLM) as a low-priority fallback for when the Claude accounts are done.
- No dependencies. Node built-ins only.
teamclaude accounts # accounts with tier and token status
teamclaude status # live proxy status, needs a running server
teamclaude disable <name> # pause an account without removing it
teamclaude priority <name> 1 # rotation order, lower = preferred
teamclaude alias --install # make plain `claude` go through the proxy
teamclaude help # everything elseFull reference: docs/usage.md.
Config is at ~/.config/teamclaude.json ($XDG_CONFIG_HOME honoured) and is meant to be hand-editable. A proxy API key is generated on first use. Observed quota goes to a separate teamclaude.state.json next to it, safe to delete since quota gets re-learned from traffic.
Every field, plus environment variables and network tuning: docs/configuration.md.
- Claude Code talks to the local proxy instead of
api.anthropic.com. - The proxy picks an eligible account, injects that account's real token, and rewrites
account_uuidin the body to match. anthropic-ratelimit-unified-*response headers feed the session (5h) and weekly (7d) quota view, which survives a restart.- At the threshold, rotation moves on. On a quota 429 the request is resent on another account, so the client never sees the limit while some account still has headroom.
- Expiring tokens, transient network errors and client token refreshes are handled inside the proxy, so none of them interrupt the session.
Step-by-step lifecycle: docs/routing.md.
| Page | Contents |
|---|---|
| Accounts | OAuth login, import, API keys, multiple orgs, third-party backends |
| Usage | Server and TUI, running Claude Code, shell alias, command reference, logging |
| Routing | Rotation, the two kinds of 429, storm control, model routes, session spreading, pinning, prompt cache |
| Quota | Quota probe, keep-warm, holding on exhaustion |
| Configuration | Config format, every field, environment variables, network tuning |
| Proxy modes | MITM forward proxy, sx.org residential egress |
| Compliance | Terms of service notes |
The only canonical sources for TeamClaude are this repository (https://github.com/KarpelesLab/teamclaude) and the @karpeleslab/teamclaude npm package. TeamClaude is never distributed as a downloadable binary archive, so be wary of soft-forks that bundle a .zip and tell you to extract and run it. See SECURITY.md for details and how to report issues.
TeamClaude is a local proxy holding your own credentials and driving your own Claude Code CLI. How that lines up with Anthropic's terms, including the multi-subscription question people ask most, is written up in docs/compliance.md. Not legal advice.
MIT — see LICENSE.