@karpeleslab/teamclaude 1.0.0

package/README.md

@@ -0,0 +1,169 @@
+# TeamClaude
+
+Multi-account Claude proxy with automatic quota-based rotation for [Claude Code](https://claude.ai/claude-code).
+
+Sits transparently between Claude Code and the Anthropic API, managing multiple Claude Max accounts and automatically switching when one approaches its session or weekly quota limit.
+
+![TeamClaude TUI](screenshots/teamclaude.png)
+
+## Features
+
+- **Automatic account rotation** — switches to the next account when session (5h) or weekly (7d) quota reaches the configured threshold (default 98%)
+- **Auto-retry on 429** — if an account is rate-limited, transparently retries with the next one
+- **Interactive TUI** — real-time dashboard with quota bars, activity log, and keyboard controls
+- **OAuth token refresh** — proactively refreshes expiring tokens and persists them to config
+- **Request logging** — optional full request/response logging for debugging
+- **Zero dependencies** — uses only Node.js built-in modules
+
+## Quick Start
+
+Requires Node.js 18+.
+
+```bash
+# Install
+npm install -g @karpeleslab/teamclaude
+
+# Import your current Claude Code credentials
+teamclaude import
+
+# Import a second account (log into it in Claude Code first, then import)
+# claude /login
+# teamclaude import
+
+# Start the proxy
+teamclaude server
+
+# In another terminal, run Claude Code through the proxy
+teamclaude run
+```
+
+## Adding Accounts
+
+### Import from Claude Code (recommended)
+
+The easiest way to add accounts. Log into each account in Claude Code, then import:
+
+```bash
+# Log into your first account in Claude Code
+claude /login
+
+# Import it
+teamclaude import
+
+# Switch to another account in Claude Code
+claude /login
+
+# Import that one too
+teamclaude import
+```
+
+Each import auto-detects the account email and subscription tier. Re-importing the same account updates its credentials.
+
+### API Key
+
+For Anthropic API key accounts (billed via Console):
+
+```bash
+teamclaude login --api
+```
+
+### OAuth Login (experimental)
+
+Direct browser-based OAuth login without needing Claude Code:
+
+```bash
+teamclaude login
+```
+
+> **Note:** OAuth login is currently experimental. Tokens obtained this way may not work for proxying `/v1/messages` requests. Use `teamclaude import` as the reliable method.
+
+## Usage
+
+### Start the proxy server
+
+```bash
+teamclaude server
+```
+
+When running from a TTY, shows an interactive TUI with:
+- Account table with session/weekly quota progress bars
+- Real-time activity log with request tracking
+- Keyboard shortcuts: **s**witch, **a**dd, **r**emove, **q**uit
+
+Falls back to plain log output when not a TTY (e.g. running as a service).
+
+### Run Claude Code through the proxy
+
+```bash
+teamclaude run
+```
+
+Or manually set the environment:
+
+```bash
+eval $(teamclaude env)
+claude
+```
+
+### Other commands
+
+```bash
+teamclaude accounts          # List accounts with live profile info
+teamclaude status            # Show live proxy status (requires running server)
+teamclaude remove <name>     # Remove an account
+teamclaude api <path>        # Call an API endpoint with account credentials
+teamclaude help              # Show all commands
+```
+
+### Request logging
+
+Log full request/response details to a directory (one file per request):
+
+```bash
+teamclaude server --log-to /tmp/requests
+```
+
+## Configuration
+
+Config is stored at `~/.config/teamclaude.json` (or `$XDG_CONFIG_HOME/teamclaude.json`). A random proxy API key is generated on first use.
+
+Override the config path with `TEAMCLAUDE_CONFIG`:
+
+```bash
+TEAMCLAUDE_CONFIG=./my-config.json teamclaude server
+```
+
+### Config format
+
+```json
+{
+  "proxy": {
+    "port": 3456,
+    "apiKey": "tc-auto-generated-key"
+  },
+  "upstream": "https://api.anthropic.com",
+  "switchThreshold": 0.98,
+  "accounts": [
+    {
+      "name": "user@example.com",
+      "type": "oauth",
+      "accountUuid": "...",
+      "accessToken": "sk-ant-oat01-...",
+      "refreshToken": "sk-ant-ort01-...",
+      "expiresAt": 1774384968427
+    }
+  ]
+}
+```
+
+## How It Works
+
+1. Claude Code connects to the local proxy instead of `api.anthropic.com`
+2. The proxy selects the active account and forwards requests with that account's credentials
+3. Rate limit headers from the API (`anthropic-ratelimit-unified-*`) track session and weekly quota
+4. When usage reaches the threshold, the proxy switches to the next available account
+5. If all accounts are exhausted, returns 429 with the soonest reset time
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@karpeleslab/teamclaude",
+  "version": "1.0.0",
+  "description": "Multi-account Claude proxy with automatic quota-based rotation",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "teamclaude": "src/index.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "keywords": [
+    "claude",
+    "anthropic",
+    "proxy",
+    "load-balancer",
+    "multi-account"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/account-manager.js

@@ -0,0 +1,323 @@
+import { refreshAccessToken, isTokenExpiringSoon } from './oauth.js';
+
+function emptyQuota() {
+  return {
+    // Standard API rate limits (API key accounts)
+    tokensLimit: null,
+    tokensRemaining: null,
+    requestsLimit: null,
+    requestsRemaining: null,
+    // Unified rate limits (Claude Max accounts)
+    unified5h: null,       // utilization 0-1
+    unified7d: null,       // utilization 0-1
+    unified5hReset: null,  // ms timestamp
+    unified7dReset: null,  // ms timestamp
+    unifiedStatus: null,   // allowed | allowed_warning | rejected
+    resetsAt: null,
+  };
+}
+
+export class AccountManager {
+  constructor(accounts, switchThreshold = 0.98) {
+    this.accounts = accounts.map((acct, index) => ({
+      index,
+      name: acct.name,
+      type: acct.type,
+      credential: acct.accessToken || acct.apiKey,
+      refreshToken: acct.refreshToken || null,
+      expiresAt: acct.expiresAt || null,
+      status: 'active',
+      quota: emptyQuota(),
+      usage: {
+        totalInputTokens: 0,
+        totalOutputTokens: 0,
+        totalRequests: 0,
+        lastUsed: null,
+      },
+      rateLimitedUntil: null,
+    }));
+    this.currentIndex = 0;
+    this.switchThreshold = switchThreshold;
+  }
+
+  /**
+   * Get the best available account, rotating if the current one is near quota.
+   * Returns null if all accounts are exhausted.
+   */
+  getActiveAccount() {
+    const current = this.accounts[this.currentIndex];
+    if (this._isAvailable(current)) {
+      return current;
+    }
+    return this._selectNext();
+  }
+
+  _isAvailable(account) {
+    if (!account) return false;
+
+    // Check rate limit expiry
+    if (account.status === 'throttled' && account.rateLimitedUntil) {
+      if (Date.now() < account.rateLimitedUntil) return false;
+      account.status = 'active';
+      account.rateLimitedUntil = null;
+      console.log(`[TeamClaude] Account "${account.name}" rate limit expired, marking active`);
+    }
+
+    if (account.status === 'exhausted' || account.status === 'error') return false;
+    if (this._isNearQuota(account)) return false;
+
+    return true;
+  }
+
+  _isNearQuota(account) {
+    const q = account.quota;
+    const now = Date.now();
+
+    // Clear expired unified quotas
+    if (q.unified5h != null && q.unified5hReset && now >= q.unified5hReset) {
+      console.log(`[TeamClaude] Account "${account.name}" session quota reset`);
+      q.unified5h = null;
+      q.unified5hReset = null;
+    }
+    if (q.unified7d != null && q.unified7dReset && now >= q.unified7dReset) {
+      console.log(`[TeamClaude] Account "${account.name}" weekly quota reset`);
+      q.unified7d = null;
+      q.unified7dReset = null;
+      q.unifiedStatus = null;
+    }
+
+    // Clear expired standard quotas
+    if (q.resetsAt && now >= new Date(q.resetsAt).getTime()) {
+      q.tokensRemaining = null;
+      q.tokensLimit = null;
+      q.requestsRemaining = null;
+      q.requestsLimit = null;
+      q.resetsAt = null;
+    }
+
+    // Unified quotas (Claude Max) — utilization is already 0-1
+    if (q.unified5h != null && q.unified5h >= this.switchThreshold) return true;
+    if (q.unified7d != null && q.unified7d >= this.switchThreshold) return true;
+
+    // Standard quotas (API key accounts)
+    if (q.tokensLimit != null && q.tokensRemaining != null) {
+      const used = 1 - (q.tokensRemaining / q.tokensLimit);
+      if (used >= this.switchThreshold) return true;
+    }
+
+    if (q.requestsLimit != null && q.requestsRemaining != null) {
+      const used = 1 - (q.requestsRemaining / q.requestsLimit);
+      if (used >= this.switchThreshold) return true;
+    }
+
+    return false;
+  }
+
+  _selectNext() {
+    const startIndex = this.currentIndex;
+
+    for (let i = 1; i <= this.accounts.length; i++) {
+      const idx = (startIndex + i) % this.accounts.length;
+      const account = this.accounts[idx];
+
+      if (this._isAvailable(account)) {
+        this.currentIndex = idx;
+        console.log(`[TeamClaude] Switched to account "${account.name}"`);
+        return account;
+      }
+    }
+
+    // All accounts unavailable — find the one that resets soonest
+    let soonestAccount = null;
+    let soonestTime = Infinity;
+
+    for (const account of this.accounts) {
+      const resetTime = account.rateLimitedUntil
+        || account.quota.unified5hReset
+        || account.quota.unified7dReset
+        || (account.quota.resetsAt ? new Date(account.quota.resetsAt).getTime() : null);
+
+      if (resetTime && resetTime < soonestTime) {
+        soonestTime = resetTime;
+        soonestAccount = account;
+      }
+    }
+
+    if (soonestAccount && soonestTime <= Date.now()) {
+      soonestAccount.status = 'active';
+      soonestAccount.rateLimitedUntil = null;
+      this.currentIndex = soonestAccount.index;
+      console.log(`[TeamClaude] Account "${soonestAccount.name}" reset, switching to it`);
+      return soonestAccount;
+    }
+
+    return null;
+  }
+
+  /**
+   * Update an account's quota tracking from upstream response headers.
+   */
+  updateQuota(accountIndex, headers) {
+    const account = this.accounts[accountIndex];
+    if (!account) return;
+
+    // Unified rate limits (Claude Max)
+    const u5h = parseFloat(headers['anthropic-ratelimit-unified-5h-utilization']);
+    const u7d = parseFloat(headers['anthropic-ratelimit-unified-7d-utilization']);
+    if (!isNaN(u5h)) account.quota.unified5h = u5h;
+    if (!isNaN(u7d)) account.quota.unified7d = u7d;
+
+    const r5h = headers['anthropic-ratelimit-unified-5h-reset'];
+    const r7d = headers['anthropic-ratelimit-unified-7d-reset'];
+    if (r5h) account.quota.unified5hReset = parseInt(r5h, 10) * 1000;
+    if (r7d) account.quota.unified7dReset = parseInt(r7d, 10) * 1000;
+
+    const uStatus = headers['anthropic-ratelimit-unified-status'];
+    if (uStatus) account.quota.unifiedStatus = uStatus;
+
+    // Standard rate limits (API key accounts)
+    const tokensLimit = parseInt(headers['anthropic-ratelimit-tokens-limit'], 10);
+    const tokensRemaining = parseInt(headers['anthropic-ratelimit-tokens-remaining'], 10);
+    const tokensReset = headers['anthropic-ratelimit-tokens-reset'];
+    const requestsLimit = parseInt(headers['anthropic-ratelimit-requests-limit'], 10);
+    const requestsRemaining = parseInt(headers['anthropic-ratelimit-requests-remaining'], 10);
+    const requestsReset = headers['anthropic-ratelimit-requests-reset'];
+
+    if (!isNaN(tokensLimit)) account.quota.tokensLimit = tokensLimit;
+    if (!isNaN(tokensRemaining)) account.quota.tokensRemaining = tokensRemaining;
+    if (!isNaN(requestsLimit)) account.quota.requestsLimit = requestsLimit;
+    if (!isNaN(requestsRemaining)) account.quota.requestsRemaining = requestsRemaining;
+
+    if (tokensReset) account.quota.resetsAt = tokensReset;
+    else if (requestsReset) account.quota.resetsAt = requestsReset;
+
+    account.usage.totalRequests++;
+    account.usage.lastUsed = new Date().toISOString();
+
+    // Log when approaching quota
+    if (this._isNearQuota(account)) {
+      const pct = account.quota.unified7d != null
+        ? (account.quota.unified7d * 100).toFixed(1)
+        : account.quota.tokensLimit
+          ? ((1 - account.quota.tokensRemaining / account.quota.tokensLimit) * 100).toFixed(1)
+          : '?';
+      console.log(`[TeamClaude] Account "${account.name}" at ${pct}% usage — will switch on next request`);
+    }
+  }
+
+  /**
+   * Update cumulative token usage from response body data.
+   */
+  updateUsage(accountIndex, inputTokens, outputTokens) {
+    const account = this.accounts[accountIndex];
+    if (!account) return;
+    if (inputTokens) account.usage.totalInputTokens += inputTokens;
+    if (outputTokens) account.usage.totalOutputTokens += outputTokens;
+  }
+
+  /**
+   * Mark an account as rate-limited for a given duration.
+   */
+  markRateLimited(accountIndex, retryAfterSeconds) {
+    const account = this.accounts[accountIndex];
+    if (!account) return;
+    account.status = 'throttled';
+    account.rateLimitedUntil = Date.now() + (retryAfterSeconds * 1000);
+    console.log(`[TeamClaude] Account "${account.name}" rate limited for ${retryAfterSeconds}s`);
+  }
+
+  /**
+   * Ensure an OAuth account's token is fresh, refreshing if needed.
+   * Pass force=true to refresh regardless of expiry (e.g. after a 401).
+   * Concurrent calls for the same account coalesce into a single refresh.
+   */
+  async ensureTokenFresh(accountIndex, force = false) {
+    const account = this.accounts[accountIndex];
+    if (!account || account.type !== 'oauth' || !account.refreshToken) return;
+
+    if (!force && !isTokenExpiringSoon(account.expiresAt)) return;
+
+    // Coalesce concurrent refreshes
+    if (account._refreshPromise) return account._refreshPromise;
+
+    account._refreshPromise = (async () => {
+      console.log(`[TeamClaude] Refreshing token for account "${account.name}"...`);
+      try {
+        const newTokens = await refreshAccessToken(account.refreshToken);
+        account.credential = newTokens.accessToken;
+        account.refreshToken = newTokens.refreshToken;
+        account.expiresAt = newTokens.expiresAt;
+        console.log(`[TeamClaude] Token refreshed for account "${account.name}"`);
+        this._onTokenRefresh?.(accountIndex, newTokens);
+      } catch (err) {
+        console.error(`[TeamClaude] Token refresh failed for "${account.name}": ${err.message}`);
+        account.status = 'error';
+      } finally {
+        account._refreshPromise = null;
+      }
+    })();
+
+    return account._refreshPromise;
+  }
+
+  /**
+   * Set a callback to persist refreshed tokens to config.
+   */
+  onTokenRefresh(callback) {
+    this._onTokenRefresh = callback;
+  }
+
+  /**
+   * Add a new account at runtime.
+   */
+  addAccount(acctData) {
+    const index = this.accounts.length;
+    this.accounts.push({
+      index,
+      name: acctData.name,
+      type: acctData.type,
+      credential: acctData.accessToken || acctData.apiKey,
+      refreshToken: acctData.refreshToken || null,
+      expiresAt: acctData.expiresAt || null,
+      status: 'active',
+      quota: emptyQuota(),
+      usage: { totalInputTokens: 0, totalOutputTokens: 0, totalRequests: 0, lastUsed: null },
+      rateLimitedUntil: null,
+    });
+    return index;
+  }
+
+  /**
+   * Remove an account by index.
+   */
+  removeAccount(index) {
+    if (index < 0 || index >= this.accounts.length) return;
+    this.accounts.splice(index, 1);
+    this.accounts.forEach((a, i) => a.index = i);
+    if (this.currentIndex >= this.accounts.length) {
+      this.currentIndex = Math.max(0, this.accounts.length - 1);
+    } else if (this.currentIndex > index) {
+      this.currentIndex--;
+    }
+  }
+
+  /**
+   * Return a status summary of all accounts (safe to expose, no credentials).
+   */
+  getStatus() {
+    return {
+      currentAccount: this.accounts[this.currentIndex]?.name,
+      switchThreshold: this.switchThreshold,
+      accounts: this.accounts.map(a => ({
+        name: a.name,
+        type: a.type,
+        status: a.status,
+        quota: { ...a.quota },
+        usage: { ...a.usage },
+        rateLimitedUntil: a.rateLimitedUntil
+          ? new Date(a.rateLimitedUntil).toISOString()
+          : null,
+      })),
+    };
+  }
+}

package/src/config.js

@@ -0,0 +1,48 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+
+export function getConfigPath() {
+  if (process.env.TEAMCLAUDE_CONFIG) return process.env.TEAMCLAUDE_CONFIG;
+  const configDir = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(configDir, 'teamclaude.json');
+}
+
+export function createDefaultConfig() {
+  return {
+    proxy: {
+      port: 3456,
+      apiKey: 'tc-' + randomBytes(24).toString('base64url'),
+    },
+    upstream: 'https://api.anthropic.com',
+    switchThreshold: 0.98,
+    accounts: [],
+  };
+}
+
+export async function loadConfig() {
+  const path = getConfigPath();
+  try {
+    return JSON.parse(await readFile(path, 'utf-8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+export async function loadOrCreateConfig() {
+  let config = await loadConfig();
+  if (!config) {
+    config = createDefaultConfig();
+    await saveConfig(config);
+    console.log(`Created config at ${getConfigPath()}`);
+  }
+  return config;
+}
+
+export async function saveConfig(config) {
+  const path = getConfigPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+}