TeamClaude

Multi-account proxy for Claude Code and Codex: it pools Claude Max, ChatGPT/Codex, API-key and third-party backend accounts, and rotates on quota.

It sits between the coding agent and the provider's API, holds several 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. Claude accounts serve Claude Code, Codex accounts serve the Codex CLI, and both pools share one proxy.

Quick start

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 proxy

Already logged into Claude Code? teamclaude import takes its credentials instead of a fresh OAuth round. A container image is on GHCR — see Running in a container. API keys, and one email holding accounts in several orgs, are covered in docs/accounts.md.

What it does

• 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.
• Opt-in MCP endpoint that hands the same control plane to Claude Code as tools, so an agent can read the fleet's quota or switch accounts from inside a session.
• Catches hardcoded api.anthropic.com endpoints (the Claude Design MCP, for one) through a local MITM forward proxy, not only what ANTHROPIC_BASE_URL covers.
• 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).
• Optionally leans on accounts with Anthropic's paid extra usage once every account is out of free quota, instead of returning 429 (allowExtraUsage, off by default — it bills real money). Quota between the switch threshold and 100% is used first, on any account; billing starts only when none is left, and stops as soon as a window resets.
• Refreshes OAuth tokens before they expire and writes them back to config. Client refreshes pass through untouched.
• Pools OpenAI Codex subscriptions alongside Claude accounts (experimental): the Codex CLI is routed through the same proxy, by config or transparently through the MITM proxy, and rotates on its own quota.
• Takes any Anthropic-compatible API (DeepSeek, GLM) as a low-priority fallback for when the Claude accounts are done.
• Sends one account's traffic through its own HTTP or SOCKS proxy (login --routing "socks5h://user:pass@host:1080"), sign-in and token refresh included, and leaves every other account alone. If that proxy goes down, the request fails over to the next account.
• No dependencies. Node built-ins only.

Everyday commands

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 else

Full reference: docs/usage.md.

Configuration

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.

How it works

1. Claude Code talks to the local proxy instead of api.anthropic.com.
2. The proxy picks an eligible account, injects that account's real token, and rewrites account_uuid in the body to match.
3. anthropic-ratelimit-unified-* response headers feed the session (5h) and weekly (7d) quota view, which survives a restart.
4. 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.
5. 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.

Documentation

| Page | Contents | | --- | --- | | Accounts | OAuth login, import, API keys, multiple orgs, per-account proxy routing, Codex accounts, third-party backends | | Usage | Server and TUI, running Claude Code, shell alias, command reference, browser dashboard, MCP endpoint, 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, upstream proxy, per-account routing, sx.org residential egress | | Compliance | Terms of service notes |

Renaming to TeamRouter

TeamClaude is becoming TeamRouter — it pools Codex and third-party accounts as well as Claude ones, and the name should say so. The rename is spread over several releases so that nothing installed, scripted or configured breaks; the plan and its progress are in issue #72. As of this release the new name is accepted everywhere while the old one stays canonical: teamrouter runs the same CLI as teamclaude, every TEAMCLAUDE_* variable is also read as TEAMROUTER_*, every /teamclaude/… control route also answers at /teamrouter/…, and a ~/.config/teamrouter.json is used when it exists. Nothing on an existing install needs to change, now or when the default flips.

Security

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.

Compliance

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.

Star history

License

MIT — see LICENSE.