maxpool 1.0.4 → 1.0.6

package/README.md

@@ -52,6 +52,48 @@ claude /login           # Log into an account in Claude Code
 maxpool import       # Import its credentials
 ```
 
+## Recommended setup
+
+The cleanest way to use maxpool day-to-day: **keep your normal `claude` login untouched, and add a separate alias that routes through the pool.** Then plain `claude` still uses your default single account, and `ccmax` (call it whatever you like) spreads work across all your accounts.
+
+1. **Install and add your accounts** (see [Adding Accounts](#adding-accounts)):
+   ```bash
+   npm install -g maxpool
+   maxpool login        # repeat for each account (browser) — or `maxpool import`
+   ```
+2. **Start the proxy** and leave it running (it shows a live dashboard):
+   ```bash
+   maxpool
+   ```
+3. **Add an alias** to your `~/.zshrc` (or `~/.bashrc`):
+   ```bash
+   # Run Claude Code through the maxpool proxy.
+   # Your plain `claude` stays on its own separate login.
+   ccmax() {
+     local url
+     url="$(maxpool env | sed -n 's/^export ANTHROPIC_BASE_URL=//p')"
+     ( unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN
+       ANTHROPIC_BASE_URL="$url" \
+       ANTHROPIC_CUSTOM_HEADERS="x-maxpool-session: $(uuidgen)" \
+       claude "$@" )
+   }
+   ```
+   Reload with `source ~/.zshrc` (or just open a new terminal).
+4. **Use it:**
+   ```bash
+   ccmax            # Claude Code, load-balanced across all your accounts
+   claude           # unchanged — still your normal single-account login
+   ```
+
+Why this approach:
+
+- **Your normal `claude` stays separate.** maxpool keeps its own account tokens in its config; your everyday Claude Code login (in the OS keychain) is never touched. Use `ccmax` when you want the pool, `claude` when you don't.
+- **Session affinity.** The `x-maxpool-session` header pins each terminal to one account (with automatic failover), so a single task doesn't bounce between accounts mid-stream.
+- **No key needed locally.** The proxy listens on `127.0.0.1` and accepts local clients without an API key, so the alias stays short.
+- **Composes with your other aliases.** If you already use aliases for other providers (GLM, Kimi, …), `ccmax` slots right in alongside them.
+
+> Prefer zero config? `maxpool run` launches Claude Code through the proxy for you — the alias above is the same idea, just composable with your own setup. Most people end up making an alias.
+
 ## Adding Accounts
 
 ### OAuth Login (recommended)
@@ -116,7 +158,18 @@ Falls back to plain log output when not a TTY (e.g. running as a service).
 
 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.
+The Accounts menu (`a`) lets you add and manage accounts without leaving the TUI:
+
+| Key | Action |
+|-----|--------|
+| `i` | Import the account you're currently logged into Claude Code as |
+| `l` | Log in via browser — add *any* account, then name it |
+| `k` | Add an Anthropic API key account |
+| `n` | Rename the selected account |
+| `t` | Enable or disable the selected account |
+| `d` | 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. The currently-active account is marked with a green `►`.
 
 Routing modes:
 
@@ -174,6 +227,7 @@ maxpool accounts          # List accounts with subscription tier and token statu
 maxpool accounts -v       # Also show token expiry times
 maxpool status            # Show live proxy status (requires running server)
 maxpool remove <name>     # Remove an account
+maxpool rename <name|#> <new>  # Rename an account (by name or list number)
 maxpool api <path>        # Call an API endpoint with account credentials
 maxpool help              # Show all commands
 ```
@@ -208,6 +262,8 @@ TEAMCLAUDE_CONFIG=./my-config.json maxpool server
     "apiKey": "tc-auto-generated-key"
   },
   "upstream": "https://api.anthropic.com",
+  "updateCheck": true,
+  "autoUpdate": false,
   "switchThreshold": 0.90,
   "scheduler": {
     "mode": "adaptive-least-loaded",
@@ -235,7 +291,7 @@ TEAMCLAUDE_CONFIG=./my-config.json maxpool server
     "pollMs": 1000
   },
   "shutdown": {
-    "drainTimeoutMs": 600000
+    "drainTimeoutMs": 15000
   },
   "accounts": [
     {
@@ -256,7 +312,10 @@ TEAMCLAUDE_CONFIG=./my-config.json maxpool server
 | `proxy.port` | Local port the proxy listens on |
 | `proxy.apiKey` | API key clients use for status/admin requests |
 | `upstream` | Upstream API base URL |
-| `switchThreshold` | Quota utilization (0–1) at which an account is avoided |
+| `updateCheck` | Check npm for a newer maxpool on startup and notify; defaults to `true` |
+| `autoUpdate` | Install new versions automatically (applied on next restart, never interrupting sessions); defaults to `false` |
+| `switchThreshold` | Quota utilization (0–1) at which an account is avoided (5h *and* weekly); default `0.90`. Raise toward `0.97` to use more before rotating |
+| `scheduler.weeklySoftThreshold` / `weeklyReserveThreshold` / `weeklyCriticalThreshold` / `weeklyExhaustedThreshold` | Weekly (7d) quota tiers (0–1) controlling how aggressively an account is de-prioritised as its weekly usage climbs |
 | `scheduler.safetyMaxActivePerAccount` | Emergency circuit breaker, not a normal capacity cap |
 | `scheduler.safetyMaxGlobalActive` | Emergency global circuit breaker |
 | `retry.maxAttemptsPerRequest` | Retry attempts before returning an error; `0` means one pass over accounts |
@@ -302,6 +361,32 @@ The weekly usage bar shows raw upstream utilization and reset timing. Reset-awar
 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
 
+## FAQ
+
+**Does this touch my normal Claude Code login?**
+No. maxpool stores its own account tokens in its config file. Your everyday `claude` login lives in the OS keychain and is never modified. Run `ccmax` for the pool, `claude` for your normal login.
+
+**How do I add another account?**
+`maxpool login` (browser — adds any account), or in the TUI press `a` then `l`. To add the account you're currently logged into Claude Code with, use `maxpool import` (or `a` then `i`).
+
+**Can I rename an account?**
+Yes — `maxpool rename <name|number> <new-name>`, or in the TUI press `a` then `n`.
+
+**An account stopped being used before it hit 100% — why?**
+maxpool stops routing to an account at `switchThreshold` (default 90%) of its 5-hour or weekly window, leaving a safety margin so it's never hard rate-limited. Raise it in your config (toward 0.97) to use more before rotating.
+
+**One account shows empty quota bars but it's serving requests — is it broken?**
+No. The bars show how *full* an account is toward its limit, so an empty bar means lots of headroom (good). Actual activity is in the `15m`/`1h` request-count columns.
+
+**Will updates apply automatically?**
+Set `"autoUpdate": true` in your config and maxpool installs new versions itself (applied on the next restart; running sessions are never interrupted). Otherwise `npm i -g maxpool` updates it.
+
+**Where do my tokens go?**
+They're stored locally in your config (file mode `0600`) and sent only to Anthropic — or, in the optional `all` profile, to GLM/Kimi if you supply those. Nothing else leaves your machine. Zero third-party dependencies.
+
+**How do I stop it?**
+Press `q` in the TUI (or Ctrl-C). It drains briefly, then exits.
+
 ## Credits
 
 maxpool is a fork of [KarpelesLab/teamclaude](https://github.com/KarpelesLab/teamclaude)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maxpool",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Multi-account Claude Code proxy with adaptive, rate-aware load balancing across Claude accounts",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -48,6 +48,10 @@ switch (command) {
     await removeCommand();
     process.exit(0);
     break;
+  case 'rename':
+    await renameCommand();
+    process.exit(0);
+    break;
   case 'api':
     await apiCommand();
     process.exit(0);
@@ -798,6 +802,42 @@ async function removeCommand() {
   console.log(`Removed account "${name}"`);
 }
 
+// Resolve an account by exact name, else by 1-based index. Returns -1 if none.
+function resolveAccountIndex(accounts, target) {
+  let idx = accounts.findIndex(a => a.name === target);
+  if (idx < 0 && /^\d+$/.test(String(target))) idx = Number(target) - 1;
+  return idx >= 0 && idx < accounts.length ? idx : -1;
+}
+
+async function renameCommand() {
+  const config = await loadOrCreateConfig();
+  const target = args[1];
+  const newName = args[2];
+
+  if (!target || !newName) {
+    console.error('Usage: maxpool rename <account-name|number> <new-name>');
+    process.exit(1);
+  }
+
+  const idx = resolveAccountIndex(config.accounts, target);
+  if (idx < 0) {
+    console.error(`Account "${target}" not found`);
+    process.exit(1);
+  }
+  if (config.accounts.some((a, i) => i !== idx && a.name === newName)) {
+    console.error(`An account named "${newName}" already exists`);
+    process.exit(1);
+  }
+
+  const old = config.accounts[idx].name;
+  config.accounts[idx].name = newName;
+  // Keep manual-preference routing pointing at the renamed account.
+  if (config.routing?.preferredAccount === old) config.routing.preferredAccount = newName;
+  await saveConfig(config);
+  console.log(`Renamed "${old}" → "${newName}"`);
+  console.log('Restart maxpool to apply this to a running proxy (or rename live from the TUI: a → n).');
+}
+
 // ── help ────────────────────────────────────────────────────
 
 function showHelp() {
@@ -815,6 +855,7 @@ Commands:
   status              Show proxy & account status (live)
   accounts            List configured accounts
   remove <name>       Remove an account
+  rename <name|#> <new>  Rename an account (by name or list number)
   api <path>          Call an API endpoint with account credentials
   help                Show this help
 

package/src/tui.js

@@ -1,4 +1,5 @@
-import { importCredentials, fetchProfile } from './oauth.js';
+import { createInterface } from 'node:readline';
+import { importCredentials, fetchProfile, loginOAuth } from './oauth.js';
 
 // ── ANSI helpers ─────────────────────────────────────────────
 
@@ -369,6 +370,14 @@ export class TUI {
           () => this._doAddKey(value),
         );
       };
+    } else if (k === 'l') {
+      this._confirm(
+        'Log in via browser?',
+        'Opens a browser to add any Claude account; you name it afterward.',
+        () => this._doLogin(),
+      );
+    } else if (k === 'n' && this.am.accounts.length > 0) {
+      this._startSelection('rename');
     } else if (k === 't' && this.am.accounts.length > 0) {
       this._startSelection('toggle');
     } else if (k === 'd' && this.am.accounts.length > 0) {
@@ -432,6 +441,14 @@ export class TUI {
           'Permanently remove it from Maxpool config. Deletion is blocked while it has active requests.',
           () => this._doDelete(this.selIdx),
         );
+      } else if (this.selAction === 'rename') {
+        const targetIdx = this.selIdx;
+        const current = account.name;
+        this.mode = 'input';
+        this.inputPrompt = `New name for "${current}"`;
+        this.inputBuf = '';
+        this.inputSensitive = false;
+        this.inputCb = value => this._doRename(targetIdx, String(value || '').trim());
       }
     }
     else if (k === 'esc' || k === 'q') { this.mode = 'normal'; }
@@ -519,74 +536,123 @@ export class TUI {
   async _doImport() {
     try {
       this._addLog('Importing credentials...');
-      const creds = await importCredentials('~/.claude/.credentials.json');
+      const creds = await importCredentials(); // file, then macOS Keychain fallback
       const profile = await fetchProfile(creds.accessToken);
-      const profileOk = profile && !profile.error;
-
-      if (!profileOk) {
+      if (!profile || profile.error) {
         this._addLog(`Warning: could not fetch profile — ${profile?.error || 'no token'}`);
       }
-
       let name;
       if (profile?.email) {
         name = profile.email;
         const tier = profile.hasClaudeMax ? 'Max' : profile.hasClaudePro ? 'Pro' : null;
         if (tier) this._addLog(`Detected Claude ${tier}: ${name}`);
-      } else {
-        const n = this.config.accounts.filter(a => a.name.startsWith('account-')).length + 1;
-        name = `account-${n}`;
       }
+      await this._upsertOAuthAccount({ creds, profile, name, source: 'import', verb: 'Imported' });
+    } catch (e) {
+      this._addLog(`Import failed: ${e.message}`);
+    }
+  }
 
-      const entry = {
-        name, type: 'oauth', source: 'import',
-        accountUuid: profile?.accountUuid || null,
-        accessToken: creds.accessToken,
-        refreshToken: creds.refreshToken,
-        expiresAt: creds.expiresAt,
-      };
+  // Browser OAuth login: any Claude account, named afterward. Suspends the TUI
+  // around the interactive flow (browser + name prompt), then resumes.
+  async _doLogin() {
+    const wasRunning = this.running;
+    if (wasRunning) this.stop();
+    try {
+      process.stdout.write('\nOpening browser to log into Claude…\n');
+      const creds = await loginOAuth();
+      const profile = await fetchProfile(creds.accessToken);
+      const suggested = profile?.email
+        || `account-${this.config.accounts.filter(a => a.name.startsWith('account-')).length + 1}`;
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await new Promise(resolve => rl.question(`Name this account [${suggested}]: `, resolve));
+      rl.close();
+      const name = String(answer || '').trim() || suggested;
+      await this._upsertOAuthAccount({ creds, profile, name, source: 'login', verb: 'Added' });
+      process.stdout.write(`\nAdded account "${name}". Returning to maxpool…\n`);
+    } catch (e) {
+      process.stdout.write(`\nLogin failed: ${e.message}\n`);
+    } finally {
+      if (wasRunning) this.start();
+    }
+  }
 
-      // Deduplicate: match by UUID first, then by name
-      let idx = profile?.accountUuid
-        ? this.config.accounts.findIndex(a => a.accountUuid === profile.accountUuid)
-        : -1;
-      if (idx < 0) idx = this.config.accounts.findIndex(a => a.name === name);
-
-      if (idx >= 0) {
-        const previous = this.config.accounts[idx];
-        entry.enabled = this.config.accounts[idx].enabled;
-        this.config.accounts[idx] = entry;
-        try {
-          await this.saveConfig(this.config);
-        } catch (error) {
-          this.config.accounts[idx] = previous;
-          throw error;
-        }
-        // Update the running account manager entry
-        const amAcct = this.am.accounts.find(account =>
-          (entry.accountUuid && account.accountUuid === entry.accountUuid) || account.name === name
-        );
-        if (amAcct) {
-          amAcct.credential = creds.accessToken;
-          amAcct.refreshToken = creds.refreshToken;
-          amAcct.expiresAt = creds.expiresAt;
-          amAcct.accountUuid = entry.accountUuid;
-          amAcct.name = name;
-          if (amAcct.status === 'error') amAcct.status = 'active';
-        }
-        this._addLog(`Updated account "${name}"`);
-      } else {
-        this.config.accounts.push(entry);
-        try {
-          await this.saveConfig(this.config);
-        } catch (error) {
-          this.config.accounts.pop();
-          throw error;
-        }
-        this.am.addAccount(entry);
-        this._addLog(`Imported account "${name}"`);
+  // Rename an account in config and in the running manager.
+  async _doRename(idx, newName) {
+    const account = this.am.accounts[idx];
+    if (!account) { this._addLog('Account no longer exists'); return; }
+    if (!newName) { this._addLog('Rename cancelled (empty name)'); return; }
+    if (this.am.accounts.some((a, i) => i !== idx && a.name === newName)) {
+      this._addLog(`An account named "${newName}" already exists`); return;
+    }
+    const cfgIdx = this._configAccountIndex(account);
+    if (cfgIdx < 0) { this._addLog(`Cannot rename "${account.name}" (not in config)`); return; }
+    const old = account.name;
+    const prev = this.config.accounts[cfgIdx].name;
+    this.config.accounts[cfgIdx].name = newName;
+    if (this.config.routing?.preferredAccount === old) this.config.routing.preferredAccount = newName;
+    try {
+      await this.saveConfig(this.config);
+    } catch (error) {
+      this.config.accounts[cfgIdx].name = prev;
+      throw error;
+    }
+    account.name = newName; // update the running account manager
+    this._addLog(`Renamed "${old}" → "${newName}"`);
+  }
+
+  // Upsert an OAuth account into config + the running manager. Dedupes by
+  // accountUuid, then name. Shared by import and browser login.
+  async _upsertOAuthAccount({ creds, profile, name, source, verb = 'Added' }) {
+    if (!name) {
+      name = profile?.email
+        || `account-${this.config.accounts.filter(a => a.name.startsWith('account-')).length + 1}`;
+    }
+    const entry = {
+      name, type: 'oauth', source,
+      accountUuid: profile?.accountUuid || null,
+      accessToken: creds.accessToken,
+      refreshToken: creds.refreshToken,
+      expiresAt: creds.expiresAt,
+    };
+
+    let idx = entry.accountUuid
+      ? this.config.accounts.findIndex(a => a.accountUuid === entry.accountUuid)
+      : -1;
+    if (idx < 0) idx = this.config.accounts.findIndex(a => a.name === name);
+
+    if (idx >= 0) {
+      const previous = this.config.accounts[idx];
+      entry.enabled = previous.enabled;
+      this.config.accounts[idx] = entry;
+      try {
+        await this.saveConfig(this.config);
+      } catch (error) {
+        this.config.accounts[idx] = previous;
+        throw error;
       }
-    } catch (e) {
-      this._addLog(`Import failed: ${e.message}`);
+      const amAcct = this.am.accounts.find(account =>
+        (entry.accountUuid && account.accountUuid === entry.accountUuid) || account.name === name
+      );
+      if (amAcct) {
+        amAcct.credential = creds.accessToken;
+        amAcct.refreshToken = creds.refreshToken;
+        amAcct.expiresAt = creds.expiresAt;
+        amAcct.accountUuid = entry.accountUuid;
+        amAcct.name = name;
+        if (amAcct.status === 'error') amAcct.status = 'active';
+      }
+      this._addLog(`Updated account "${name}"`);
+    } else {
+      this.config.accounts.push(entry);
+      try {
+        await this.saveConfig(this.config);
+      } catch (error) {
+        this.config.accounts.pop();
+        throw error;
+      }
+      this.am.addAccount(entry);
+      this._addLog(`${verb} account "${name}"`);
     }
   }
 
@@ -829,7 +895,13 @@ export class TUI {
 
   _renderAcct(idx, bw, showBoth) {
     const a = this.am.accounts[idx];
-    const isCur = this.am.routingMode === 'preferred' && a.name === this.am.preferredAccountName;
+    // Highlight the currently-active account. In manual mode that's the
+    // preferred account; in automatic mode it's the one most recently routed
+    // to (currentIndex). Previously only manual mode highlighted anything, so
+    // in automatic load-balancing no row was ever marked current.
+    const isCur = this.am.routingMode === 'preferred'
+      ? a.name === this.am.preferredAccountName
+      : idx === this.am.currentIndex;
     const isSel = this.mode === 'select' && idx === this.selIdx;
 
     // Prefix: selection marker + current marker
@@ -936,7 +1008,7 @@ export class TUI {
       case 'normal':
         return ` ${bold('a')} Accounts  ${bold('m')} Routing  ${bold('s')} Sync  ${bold('r')} Restart  ${bold('q')} Stop`;
       case 'accounts':
-        return ` ${bold('i')} Import Claude login  ${bold('k')} API key  ${bold('t')} Enable/disable  ${bold('d')} Delete  ${bold('Esc')} Back`;
+        return ` ${bold('i')} Import  ${bold('l')} Login (browser)  ${bold('k')} API key  ${bold('n')} Rename  ${bold('t')} Enable/disable  ${bold('d')} Delete  ${bold('Esc')} Back`;
       case 'routing':
         return ` ${bold('a')} Automatic  ${bold('p')} Manual preference  ${bold('Esc')} Back`;
       case 'select': {
@@ -944,7 +1016,9 @@ export class TUI {
           ? 'prefer'
           : this.selAction === 'toggle'
             ? 'enable/disable'
-            : 'delete';
+            : this.selAction === 'rename'
+              ? 'rename'
+              : 'delete';
         return ` ${dim('↑↓')} select  ${bold('Enter')} ${act}  ${bold('Esc')} cancel`;
       }
       case 'input':