Maxpool

Multi-account proxy for Claude Code that spreads your work across several Claude accounts with adaptive, rate-aware load balancing.

Sits transparently between Claude Code and the Anthropic API, managing multiple Claude Max (or API key) accounts. Instead of waiting until one account hits a wall, it continuously balances requests by how much quota each account has and how soon that quota resets — so an account about to refresh gets used, and one burning through its budget early gets spared.

Features

• Rate-aware load balancing — ranks accounts by remaining quota ÷ time-to-reset, not raw usage %, so a near-reset account with quota left is drained (use-it-or-lose-it) and one burning fast early in its window is spared; sequential traffic rotates across accounts instead of funnelling onto one
• Interactive account & routing management — add/import/enable-disable accounts and switch between automatic load balancing and a preferred (manual) account, all from the TUI
• Quota-aware routing — avoids accounts when session (5h) or weekly (7d) quota reaches the configured threshold (default 90%)
• Session affinity — optional session headers keep one Claude Code session on the same account until that account becomes unavailable
• Fast failover on 429/overload — parks the affected account and retries another account before response bytes are sent
• Provider fallback profile — optional all profile can use Claude accounts first, then GLM, then Kimi via local custom headers
• Provider telemetry — GLM/Kimi rows show active requests, completed/failed counts, last status/latency, and standard rate-limit headers when providers return them
• Rolling load view — each row shows current in-flight load plus request counts/average latency over the last 15 minutes and 1 hour
• Interactive TUI — real-time dashboard with color-coded quota bars, reset countdowns, activity log, and keyboard controls
• Graceful drain on restart — restart/quit/Ctrl-C stops new requests and waits for active streams to finish before exiting or relaunching
• OAuth token management — automatically refreshes tokens nearing expiry and persists them to config; client token refreshes pass through untouched
• Hot-sync accounts — add accounts via import or login while the server is running; the server auto-syncs config and s can sync immediately
• Account deduplication — detects duplicate accounts by UUID and keeps the most recent
• Request logging — optional full request/response logging for debugging
• Zero dependencies — uses only Node.js built-in modules

Quick Start

Requires Node.js 18+.

# Install
npm install -g maxpool

# Add your first account (opens browser for OAuth)
maxpool login

# Add a second account
maxpool login

# Start the proxy
maxpool server

# In another terminal, run Claude Code through the proxy
maxpool run

You can also import existing Claude Code credentials instead of logging in:

claude /login           # Log into an account in Claude Code
maxpool import       # Import its credentials

Adding Accounts

OAuth Login (recommended)

The easiest way to add accounts — opens your browser for authentication:

maxpool login

Uses the same OAuth flow as Claude Code. Auto-detects the account email and subscription tier. Logging in with the same account again updates its credentials.

You can add accounts while the server is running — press s in the TUI to sync immediately, or wait for automatic sync.

Import from Claude Code

If you already have Claude Code set up, you can import its credentials directly:

claude /login           # Log into an account in Claude Code
maxpool import       # Import its credentials

Re-importing the same account updates its credentials. You can also import from a custom path:

maxpool import --from /path/to/credentials.json

API Key

For Anthropic API key accounts (billed via Console):

maxpool login --api

Usage

Start the proxy server

maxpool server

When running from a TTY, shows an interactive TUI with:

• Account table with session/weekly quota progress bars and reset countdowns
• Real-time activity log with request tracking
• Keyboard shortcuts (see below)

Falls back to plain log output when not a TTY (e.g. running as a service).

TUI Keyboard Shortcuts

State-changing actions show what will happen and require y or n. In selection mode, use j/k or arrow keys to navigate, Enter to choose, and Esc to go back.

The Accounts menu can import the current Claude Code login, add an Anthropic API key, enable or disable an account, or permanently delete an idle account. Disabling keeps credentials in config but prevents new requests from using the account. Deletion is blocked while that account has active requests.

Routing modes:

• Automatic spreads requests across healthy accounts using live load, quota pressure, and recent errors.
• Manual preference sends subsequent requests, including the next request from existing idle sessions, to the selected Claude account whenever it is healthy. Maxpool still fails over automatically when necessary and returns to the preferred account after recovery.

Routing changes do not move requests already in flight.

Run Claude Code through the proxy

maxpool run

Or manually set the environment:

eval "$(maxpool env)"
claude

maxpool env exports only ANTHROPIC_BASE_URL by default so Claude Code can keep using your claude.ai subscription login without showing an ANTHROPIC_API_KEY auth conflict warning. Use maxpool env --with-key only for non-local clients that need to authenticate to the proxy.

The proxy also understands an optional internal header profile:

• default/absent x-maxpool-profile: Claude accounts only
• x-maxpool-profile: all: Claude accounts first, then lower-priority provider fallbacks

Provider fallback credentials can be supplied per Claude Code process with ANTHROPIC_CUSTOM_HEADERS. Maxpool strips all x-maxpool-* headers before forwarding upstream.

x-maxpool-session: <id> enables session affinity. With this header, the first request for a Claude Code process is routed by the adaptive load balancer, then later requests from the same process keep using that home account while it remains available. If the home account is rate-limited, exhausted, in cooldown, or removed, the session temporarily uses another eligible route. When the home account becomes available again, the session returns to it. For the all profile, fallback priority still wins: a session that had to use GLM or Kimi can move back to Claude when a Claude account becomes available again.

Provider rows do not use Claude Max session/week bars unless the provider returns compatible quota headers. For GLM/Kimi, Maxpool always tracks operational telemetry (Act, OK, Fail, Last) and also parses common x-ratelimit-* / ratelimit-* headers if present.

When GLM/Kimi return 429 without standard retry headers, Maxpool also parses provider-specific JSON error bodies. Z.AI next_flush_time / weekly-monthly exhausted messages and Kimi “try again after N seconds” rate-limit messages are converted into provider cooldowns and queue wake-up timing.

Every account/provider row also includes load telemetry: Load current/weight, 15m <requests> <avg latency>, and 1h <requests>. This is based on completed requests retained in memory for the last hour, plus current in-flight requests.

Restart behavior

When you confirm Restart, confirm Stop, press Ctrl-C, or send SIGTERM, Maxpool enters draining shutdown:

1. The proxy stops accepting new requests.
2. Existing in-flight streams keep running.
3. The process exits when active requests finish.
4. If you selected Restart, Maxpool starts a fresh maxpool server process in the same terminal.
5. Press Ctrl-C again to force exit.

Idle Claude Code sessions are not tied to the server process. If the server is restarted while a Claude Code session is idle, its next request reconnects to the new server. If the server is forced closed while a stream is actively running, that stream can still fail because the TCP connection disappears.

Other commands

maxpool accounts          # List accounts with subscription tier and token status
maxpool accounts -v       # Also show token expiry times
maxpool status            # Show live proxy status (requires running server)
maxpool remove <name>     # Remove an account
maxpool api <path>        # Call an API endpoint with account credentials
maxpool help              # Show all commands

Request logging

Log full request/response details to a directory (one file per request):

maxpool server --log-to /tmp/requests

Request logging includes prompt and response bodies. Use it only for short debugging windows and delete logs afterwards.

Configuration

Config is stored at ~/.config/maxpool.json (or $XDG_CONFIG_HOME/maxpool.json). A random proxy API key is generated on first use.

Override the config path with TEAMCLAUDE_CONFIG:

TEAMCLAUDE_CONFIG=./my-config.json maxpool server

Config format

{
  "proxy": {
    "host": "127.0.0.1",
    "port": 3456,
    "apiKey": "tc-auto-generated-key"
  },
  "upstream": "https://api.anthropic.com",
  "switchThreshold": 0.90,
  "scheduler": {
    "mode": "adaptive-least-loaded",
    "safetyMaxActivePerAccount": 50,
    "safetyMaxGlobalActive": 150,
    "cooldownMs": 30000,
    "maxCooldownMs": 900000,
    "weeklySoftThreshold": 0.65,
    "weeklyReserveThreshold": 0.85,
    "weeklyCriticalThreshold": 0.95,
    "weeklyExhaustedThreshold": 0.985,
    "weeklyBurnDebtWeight": 0.6
  },
  "retry": {
    "maxAttemptsPerRequest": 0,
    "maxRetryBufferBytes": 10485760
  },
  "queue": {
    "enabled": true,
    "maxWaitMs": 86400000,
    "autoMaxWaitMs": null,
    "capacityMaxWaitMs": 900000,
    "maxQueuedBodyBytes": 268435456,
    "weeklyMaxWaitMs": 0,
    "pollMs": 1000
  },
  "shutdown": {
    "drainTimeoutMs": 600000
  },
  "accounts": [
    {
      "name": "user@example.com",
      "type": "oauth",
      "accountUuid": "...",
      "accessToken": "sk-ant-oat01-...",
      "refreshToken": "sk-ant-ort01-...",
      "expiresAt": 1774384968427
    }
  ]
}

Weekly Claude quota is treated as long-horizon budget, not the same as the 5-hour session cap:

• normal: accepts new and sticky sessions.
• soft: remains available, but new sessions prefer cooler accounts.
• reserve: existing sticky sessions can continue; new sessions use other Claude accounts when possible.
• critical: avoided unless no healthier eligible route exists. This can be raw weekly usage or reset-aware pace pressure.
• exhausted: unavailable until weekly reset or upstream recovery.

The weekly usage bar shows raw upstream utilization and reset timing. Reset-aware burn rate is a separate pace signal used for routing pressure; it can mark an account as Pace critical, but only raw near-exhaustion or upstream rejection can show/block as Wk exhausted.

How It Works

1. Claude Code connects to the local proxy instead of api.anthropic.com
2. The proxy selects the least-loaded healthy account and forwards requests with that account's credentials
3. If the client sends x-maxpool-session, the session is pinned to that account while it stays available
4. OAuth tokens expiring within 5 minutes are automatically refreshed and persisted to config
5. Rate limit headers from the API (anthropic-ratelimit-unified-*) track session (5h) and weekly (7d) quota utilization
6. 5-hour quota controls immediate availability; weekly quota controls new-session admission and preservation; weekly critical is last-resort, while weekly exhausted is blocked
7. Account quota 429s cool down only that account and fail over before response bytes are sent
8. Anthropic's server-side 429 and 529 responses first fail over across every eligible Claude account; only a request-wide set of matching failures with no concurrent Claude success promotes to the shared circuit breaker. One real request probes recovery after retry-after, then queued work resumes automatically
9. Queued streaming requests receive SSE heartbeats, preventing Claude Code's client timeout from abandoning temporary waits
10. Transient network errors (connection reset, timeout) fail over before the stream starts; if every eligible route has a network failure, the proxy returns 503 connection_unavailable instead of a quota error
11. In the all profile only, if all Claude accounts are unavailable, provider fallbacks are tried by priority: GLM before Kimi
12. If all eligible accounts/providers are temporarily unavailable for a temporary reason (5h/session limit, provider cooldown, short 429), the proxy queues the request and retries when one recovers
13. Repeated upstream 5xx/overload failures use the shorter capacityMaxWaitMs cap, not the long quota wait
14. Weekly exhaustion and non-retryable 4xx errors fail fast by default; if the queue wait expires, returns 429 with the soonest retry time
15. Temporary OAuth refresh failures cool the account down and queue/fail over; invalid refresh credentials disable only that account and require login
16. In an interactive terminal, the server runs under a foreground supervisor so confirmed Restart (r) can drain and restart without detaching the replacement TUI
17. When Restart is confirmed, new upstream admission pauses immediately. Existing upstream requests finish, queued requests cannot deadlock restart, and their sockets close during relaunch so Claude Code reconnects automatically
18. Client token refresh requests (/v1/oauth/token) are relayed to upstream untouched — the proxy and client manage their own token lifecycles independently

Credits

maxpool is a fork of KarpelesLab/teamclaude by Mark Karpelès, substantially extended with rate-aware (use-it-or-lose-it) load balancing, interactive account & routing management, atomic credential storage, and resilient upstream-error handling. Thanks to the original authors.

License

MIT — see LICENSE. Copyright © 2026 KarpelesLab and Max Krasnykh.