TeamClaude

Usage dimensions allow you to track token consumption by project, branch, or pull request without changing the proxy for every new grouping.

1. Configure the Proxy: Define the dimension name and the HTTP header it should look for in the proxy.usageDimensions config.
2. Set Identity in Client: Developers can set the identity in .claude/settings.json using the ANTHROPIC_CUSTOM_HEADERS environment variable.
3. Set Identity in CI: CI environments can export ANTHROPIC_CUSTOM_HEADERS with newline-separated values.

Constraints:

• Dimensions are capped at 500 distinct values; additional values are grouped into (other).
• Header values are sanitized and length-capped.
• Dimension headers are consumed by the proxy for labeling and are not forwarded upstream.
• Forbidden Headers: The proxy refuses to use authorization, proxy-authorization, cookie, x-api-key, x-app, x-claude-code-session-id, x-claude-code-agent-id, x-claude-code-parent-agent-id, and x-anthropic-additional-protection as dimensions.

// Proxy Configuration
{
  "proxy": {
    "usageDimensions": [
      { "name": "project", "header": "x-teamclaude-project" },
      { "name": "ref", "header": "x-teamclaude-ref" }
    ]
  }
}

// .claude/settings.json
{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "X-Teamclaude-Project: KarpelesLab/teamclaude"
  }
}

# CI Usage
export ANTHROPIC_CUSTOM_HEADERS=$'X-Teamclaude-Project: KarpelesLab/teamclaude\nX-Teamclaude-Ref: pull/123'

TeamClaude distinguishes between three types of 429 responses to prevent unnecessary account rotation or cache loss:

Why not rotate on rate-limits? Rotating on a per-minute throttle simply moves the burst to the next account and discards the prompt cache of the first account.

TeamClaude has shifted from tracking load by client session to tracking load by conversation.

Key Concepts

• Conversation vs. Session: A single client session (like a Claude Code instance) may contain multiple conversations (e.g., a parent task and several subagents). Load is measured per conversation.
• Pinning: A conversation is pinned to an account for a specific model family's weekly quota bucket. This ensures the conversation keeps hitting the same account to preserve its prompt cache.
• Subagents:
  • A fresh subagent (not sharing context) is treated as a new conversation and can be routed to a different account.
  • A forked subagent (sent with the parent's messages) shares the same conversation digest and stays on the account holding the parent's cache.
• Load Metrics: In teamclaude status, load is reported as active N sess (active conversations) and N inflight (requests currently in flight).

TeamClaude acts as a local proxy between your client (e.g., Claude Code) and api.anthropic.com. The lifecycle follows these steps:

1. Connection: The client connects to the local proxy.
2. Account Selection: The proxy selects an active account and forwards requests using that account's credentials.
3. Token Management: OAuth tokens expiring within 5 minutes are automatically refreshed and persisted to your config.
4. Quota Tracking: The proxy monitors anthropic-ratelimit-unified-* headers to track 5-hour (session) and 7-day (weekly) quota usage.
5. Rotation: When usage hits the switchThreshold (default 0.98), the proxy switches to the best available account.
6. Error Handling:
   • On 429 responses, the proxy waits for the retry-after duration and retries. Persistent errors trigger an account switch.
   • On transient network errors (timeouts, connection resets), the proxy drops the connection so the client can retry.
7. Exhaustion: If all accounts are exhausted, the proxy returns a 429 with the soonest reset time. If holdSeconds is configured, it will hold the connection open and retry silently until an account recovers.
8. Token Refresh: Client requests to /v1/oauth/token are relayed to the upstream provider untouched.

When expiryRouting.preempt is set to true, the router can move a pinned conversation (and its sticky current account) if the account's governing weekly window rolls over.

When a Pin is Re-routed:

• Only occurs when the account's weekly window resets (rollover). This prevents a conversation from 'sitting' on a freshly reset account while other accounts' quota expires.
• What does NOT trigger a move: Simple quota draining or pressure changes alone will not move a pin. This prevents unnecessary prompt cache thrashing.

When a Pin is Broken (Standard Behavior): Preemption is separate from standard pin invalidation. A pin stops being honored if:

1. The account cannot serve the request (e.g., spent quota, rate-limit hold, or upstream refusal).
2. A higher-priority account becomes available.
3. The account was already tried and failed earlier in the same request.
4. A manual route pin or TC_ACCT override is used (these bypass affinity entirely).
5. The conversation becomes idle past the known window.

Implementation Detail: A rollover move is only considered 'settled' once the request is successfully served at the destination (HTTP status < 400).

TeamClaude acts as a local MITM (Man-in-the-Middle) forward proxy between your coding agent (like Claude Code) and the provider's API (e.g., api.anthropic.com).

The Request Lifecycle:

1. Interception: The coding agent communicates with the local proxy instead of the direct Anthropic endpoint. The proxy also catches hardcoded api.anthropic.com calls via its MITM capabilities.
2. Account Selection: The proxy selects an eligible account from the pool, injects the real token, and rewrites the account_uuid in the request body to match the selected account.
3. Quota Tracking: The proxy monitors anthropic-ratelimit-unified-* response headers to track 5-hour (session) and 7-day (weekly) quotas. This state persists across restarts.
4. Rotation: When an account reaches a threshold (98% by default), the proxy rotates to the next account. If a request hits a quota 429, the proxy transparently resends the request using a different account so the client never sees the error.
5. Resilience: The proxy handles expiring tokens, transient network errors, and client token refreshes internally to prevent session interruptions.