TeamClaude: a quota-rotation proxy for Claude Code and Codex

The problem TeamClaude solves: a 429 in the middle of an unattended run

A Claude Code session stops when the account behind it hits a session or weekly limit. If you hold several Claude Max subscriptions, nothing in the CLI lets you spread one session across them; you switch accounts by hand, and anything running unattended simply dies at the limit. TeamClaude puts a local proxy between the coding agent and the provider's API, holds the accounts, and moves to the next one when the current account gets close to its limit. The README states the session keeps running instead of stopping on a 429.

The audience is narrow and specific. You need more than one account for the rotation to mean anything. The README also lists Codex subscriptions as an experimental pool, plus any Anthropic-compatible API such as DeepSeek or GLM as a low-priority fallback. A single-account user gets a proxy with nothing to fail over to.

Request lifecycle: token injection, account_uuid rewriting and the quota headers

The mechanism is documented step by step. Claude Code is pointed at the local proxy instead of api.anthropic.com. The proxy picks an eligible account, injects that account's real token, and rewrites account_uuid in the body to match. Then anthropic-ratelimit-unified-* response headers feed a session (5h) and weekly (7d) quota view, which survives a restart because observed quota is written to teamclaude.state.json next to the config. At the threshold, rotation moves on.

The interesting part is how it tells two failures apart. TeamClaude separates a spent quota bucket from a per-minute rate limit and only rotates on the first. The README's reasoning is that rotating on a rate limit would move the burst to the next account and drop the warm cache, so it paces the same account instead. When a quota 429 does arrive, the request is resent on another account, so the client never sees the limit while some account still has headroom. Per-model weekly caps are tracked separately: the README gives the example of an account out of Fable quota being skipped for Fable requests while still serving Opus and Sonnet.

Two details are easy to miss. First, rotation prefers the account whose weekly quota resets soonest, which spreads load rather than draining one account. Second, a freshly switched account gets paced requests, because a herd of agents failing over at the same instant would otherwise throttle it and cascade down the fleet.

Installing TeamClaude and running Claude Code through it

Node.js 20 or newer is required, and the package is published on npm. The README gives this quick start:

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

Run login once per account. If you are already logged into Claude Code, the README states teamclaude import takes its credentials instead of a fresh OAuth round. The server command starts the proxy and shows a TUI with quota bars, reset countdowns and an activity log.

Day-to-day management is a small command set:

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

Config lives at ~/.config/teamclaude.json, with $XDG_CONFIG_HOME honoured, and the README says it is meant to be hand-editable. A proxy API key is generated on first use. The separate teamclaude.state.json holds observed quota and is safe to delete, since quota gets re-learned from traffic. There is also a container image on GHCR; the Dockerfile exposes port 3456 and defaults the entrypoint to server --headless.

Where TeamClaude stops helping: rate limits, hardcoded endpoints and single-account setups

TeamClaude does not create quota. It redistributes the quota you already pay for, so an account pool that is genuinely exhausted stays exhausted. The README addresses this directly: holdSeconds keeps the request open until quota resets instead of returning 429 when every account is spent, so an unattended run finishes on its own. That behaviour is off by default, which means the default configuration still fails once the last account is spent.

The proxy also has to intercept traffic that does not honour ANTHROPIC_BASE_URL. The README notes that hardcoded api.anthropic.com endpoints, naming the Claude Design MCP, are caught through a local MITM forward proxy rather than base-URL rewriting alone. That is extra machinery in the request path, and the docs devote a separate page to proxy modes and to sx.org residential egress. If you are not prepared to run a MITM proxy on your machine, the base-URL path covers ordinary Claude Code traffic but not every integration.

Compliance is the other boundary. The README links docs/compliance.md for how multi-subscription use lines up with Anthropic's terms, and explicitly says it is not legal advice. Anyone reading this as a way around a single subscription's limits is reading it wrong: the tool assumes you hold the accounts.

TeamClaude compared with a plain ANTHROPIC_BASE_URL override or a generic HTTP load balancer

The simplest alternative is pointing Claude Code at one other account by setting ANTHROPIC_BASE_URL yourself and swapping the value when you hit a limit. That needs no extra process and no config file, but it is manual, it does not read quota headers, and it cannot distinguish a spent weekly bucket from a per-minute rate limit. TeamClaude's rotation decision is driven by the anthropic-ratelimit-unified-* headers and a persisted quota view, which is the difference between rotating at the right moment and rotating on every error.

A generic HTTP load balancer in front of api.anthropic.com is the other option. It can spread requests across upstreams, but it does not inject per-account tokens, does not rewrite account_uuid, and has no notion of a 5h session bucket versus a 7d weekly bucket. It also has no answer for token refresh: the README states TeamClaude refreshes OAuth tokens before they expire and writes them back to config, while client refreshes pass through untouched. Replicating that in nginx or Envoy means writing the rotation logic yourself.

Maintenance cost, licence and the upgrade path

The repository is not archived, and the last push was on 2026-09-12. Releases are frequent: v1.1.18 on 2026-09-09, v1.1.19 on 2026-09-10, v1.1.20 on 2026-09-11. That cadence is a maintenance cost as much as a signal, since a proxy sitting in the request path of your editor has to keep up with provider-side changes to quota headers and OAuth flows.

The codebase is small and deliberately so. package.json lists no runtime dependencies at all; the only devDependencies are @types/node, eslint and typescript. The Dockerfile sets TEAMCLAUDE_DISABLE_AUTOUPDATE=1, so the container does not self-update and you upgrade by pulling a new image. Licence is MIT, which permits commercial use and redistribution; the README's compliance page covers terms-of-service questions and states it is not legal advice, so treat that as an input to your own review rather than a clearance.

Editorial conclusion

Adopt TeamClaude if you already hold two or more Claude Max or Codex subscriptions and want one Claude Code session to keep running past a 429 without manual account juggling. Do not adopt it if you have a single account, since rotation has nothing to rotate to, or if you need a signed binary: the README states the only canonical sources are the GitHub repository and the @karpeleslab/teamclaude npm package. Before rolling it out, read docs/compliance.md on how multi-subscription use lines up with Anthropic's terms, and check the holdSeconds default, which the README says is off.

Frequently asked questions

Official sources

1. Issues
2. KarpelesLab/teamclaude on GitHub
3. License: MIT
4. README
5. Releases