claude-pool 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kiran & Claude-Pool Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,180 @@
-# Temporary Holding Version
+# 🔄 Claude Pool (`claude-pool`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-orange.svg)](https://claude.ai/code)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+> **Pool multiple Claude subscriptions into one uninterrupted coding session with automated failover, live quota gauges, and cross-account memory sync.**
+
+---
+
+## ⚡ The Problem
+
+If you have multiple Claude subscriptions (personal, work, backup), hitting Anthropic's **5-hour rolling limit or weekly cap** mid-flow is painful:
+1. You have to stop work.
+2. Manually log out and log in with your other account.
+3. Lose conversation context and file history.
+4. Guess how many tokens or remaining quota you have left across accounts.
+
+**`claude-pool` solves this completely.** It pools your accounts with customizable priority, monitors your limits in real-time, and **automatically transfers your active session transcript to your standby account** when one hits a limit. You never lose your flow.
+
+---
+
+## ✨ Features
+
+- 🔄 **Seamless Session Continuity**: Automatically syncs active project transcripts (`<session-id>.jsonl`) to the standby account and resumes via `claude --resume`. No lost memory.
+- 🎯 **Priority-Based Scheduling**: Strictly prioritize accounts (e.g. `Primary` → `Account 2` → `Account 3`).
+- 📊 **Real-time Token Metrics**: Live token aggregation directly from active sessions (Input, Output, Cache Read/Create, per model).
+- ⏳ **Quota & Countdown Tracking**: Real-time gauge bars showing exact `% session quota remaining` and reset timers (e.g. `resets at 7:10pm`).
+- 🎨 **Minimalist Aesthetic UI**: Linear & Raycast-inspired terminal UI with clean pill badges and subtle borders.
+- 🧙 **Zero-Friction Setup Wizard**: Run `claude-pool setup` to connect and authenticate all your accounts in 60 seconds.
+
+---
+
+## 🚀 Quick Start (Zero-Setup with `npx`)
+
+Since every Claude Code user already has Node.js and npm installed, you can run `claude-pool` instantly **with zero installation**:
+
+```bash
+# Run setup wizard directly via npx:
+npx claude-pool setup
+
+# Or start pooled session:
+npx claude-pool
+```
+
+### Install Globally (Recommended, exactly like `codeburn`)
+
+```bash
+npm install -g claude-pool
+```
+
+Now `claude-pool` is available anywhere in your terminal:
+```bash
+claude-pool
+```
+
+*(Python users can also install via `pip install claude-pool`)*
+
+The interactive wizard will:
+- Detect your primary account (`~/.claude`).
+- Guide you to add your secondary/standby Claude accounts.
+- Open your browser to authenticate each account safely into isolated directories (`~/.claude-account2`, etc.).
+- Set your priority rankings.
+
+### 3. Start Coding!
+
+Instead of typing `claude`, simply type:
+
+```bash
+claude-pool
+```
+
+You can pass any standard Claude flags:
+```bash
+claude-pool --model opus
+claude-pool -p "Summarize git diff"
+```
+
+---
+
+## 🖥️ Terminal Experience
+
+### 1. Launch HUD Header
+Anchored at the top of every session:
+```
+┌─  claude-pool  ─────────────────────────────────────────────────────────────┐
+│   Active Account   primary [Priority 1] · 71% remaining (resets 7:10pm)     │
+│   Pool Today       121.4M tokens across 3 accounts                          │
+│   Standby Queue    account2, account3                                       │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 2. Live Failover Transition Card
+When an account reaches its 5-hour limit, `claude-pool` catches it and migrates the session:
+```
+╭─ Auto-Failover Transition ──────────────────────────────────────────────────╮
+│  Rate limit reached on primary                                              │
+│                                                                             │
+│  + Preserved active session: 6f1ff60d-9bb...                                │
+│  + Synchronized project state to account2                                   │
+│  -> Continuing on account2 (Priority 2)                                     │
+╰─────────────────────────────────────────────────────────────────────────────╯
+```
+
+### 3. Unified Pool Dashboard (`claude-pool dashboard`)
+```
+┌─  Token Pool Dashboard  ────────────────────────────────────────────────────┐
+│ Today's Pool Total: 121.4M   │ Output: 941.2K   │ Cache: 120.4M             │
+└─────────────────────────────────────────────────────────────────────────────┘
+┌────┬──────────┬─────────┬──────────────┬───────────┬──────────────────┬─────┐
+│    │ Account  │ Status  │ Rem. Quota   │   Today's │ Model Breakdown  │ Ses │
+├────┼──────────┼─────────┼──────────────┼───────────┼──────────────────┼─────┤
+│ P1 │ primary  │  ACTIVE │ ██████░░ 71% │    118.0M │ opus-5-5: 118.0M │ 50  │
+│ P2 │ account2 │ STANDBY │ ███████░ 93% │      3.4M │ fable-5-1: 3.4M  │ 46  │
+│ P3 │ account3 │ STANDBY │ ████████ 99% │         0 │ -                │ 12  │
+└────┴──────────┴─────────┴──────────────┴───────────┴──────────────────┴─────┘
+```
+
+---
+
+## ⌨️ CLI Command Reference
+
+| Command | Description |
+|---|---|
+| `claude-pool` | Launch Claude session with active account & auto-failover |
+| `claude-pool setup` | Interactive wizard to connect all accounts from scratch |
+| `claude-pool limits` / `remaining` | View exact % session and weekly quota remaining + reset countdowns |
+| `claude-pool dashboard` | Unified pool dashboard with today's consumption & gauges |
+| `claude-pool usage [account]` | Deep token breakdown (Input, Output, Cache Read/Create) per account |
+| `claude-pool priority` | View priority order of accounts |
+| `claude-pool set-priority <name> <p>` | Change account priority (e.g. `set-priority primary 1`) |
+| `claude-pool priority --order a,b,c` | Reorder all accounts in one command |
+| `claude-pool status` / `accounts` | List all accounts, directories, and health badges |
+| `claude-pool check-auth` | Verify live authentication status across all accounts |
+| `claude-pool login <account>` | Re-authenticate an account whose OAuth session expired |
+| `claude-pool add [name]` | Add a new account to the pool interactively |
+
+---
+
+## 🧠 How It Works Under The Hood
+
+Claude Code stores project sessions as local JSONL transcripts:
+```
+~/<config_dir>/projects/<CWD-encoded>/<session-id>.jsonl
+```
+
+When an account exhausts its tokens:
+1. `claude-pool` detects the limit exit code or message.
+2. Identifies the active `<session-id>` and working directory.
+3. Copies `<session-id>.jsonl` and sidecar tool results into the next standby account's configuration directory.
+4. Sets `CLAUDE_CONFIG_DIR = ~/.claude-account2`.
+5. Relaunches `claude --resume <session-id>` with zero loss of memory.
+
+---
+
+## 🛠️ Troubleshooting & FAQ
+
+### What happens if an account's login expires?
+OAuth tokens occasionally expire. Run:
+```bash
+claude-pool check-auth
+```
+If an account is flagged as `EXPIRED`, simply re-authenticate it with:
+```bash
+claude-pool login <account_name>
+```
+
+### Can I pass custom Claude arguments?
+Yes! Any arguments passed to `claude-pool` pass directly through to Claude Code:
+```bash
+claude-pool --model opus --verbose
+claude-pool -p "Fix the failing tests in auth.py"
+```
+
+---
+
+## 📄 License
+
+Distributed under the [MIT License](LICENSE).

package/bin/cli.js

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+
+import { ConfigManager } from '../src/config.js';
+import { MetricsEngine } from '../src/metrics.js';
+import { QuotaEngine } from '../src/quota.js';
+import { ProcessRunner } from '../src/runner.js';
+import { runSetupWizard, checkAuthStatus, runAccountLogin } from '../src/setup.js';
+import { colors, formatTokenCount, makePill, makeGauge, printTable } from '../src/ui.js';
+
+const KNOWN_COMMANDS = new Set([
+  'start',
+  'setup',
+  'limits',
+  'remaining',
+  'quota',
+  'dashboard',
+  'usage',
+  'tokens',
+  'priority',
+  'set-priority',
+  'status',
+  'accounts',
+  'check-auth',
+  'login',
+  'add',
+  '--help',
+  '-h',
+]);
+
+const args = process.argv.slice(2);
+const firstArg = args[0];
+
+const cfg = new ConfigManager();
+
+async function handleCommand() {
+  if (!firstArg || (!firstArg.startsWith('-') && !KNOWN_COMMANDS.has(firstArg))) {
+    // Default: run interactive session with failover
+    const runner = new ProcessRunner(cfg);
+    runner.runSession(args);
+    return;
+  }
+
+  switch (firstArg) {
+    case 'start': {
+      const runner = new ProcessRunner(cfg);
+      runner.runSession(args.slice(1));
+      break;
+    }
+
+    case 'setup': {
+      await runSetupWizard();
+      break;
+    }
+
+    case 'limits':
+    case 'remaining':
+    case 'quota': {
+      console.log(`\n${colors.indigo}Querying live Claude usage quotas & reset countdowns...${colors.reset}`);
+      const accounts = cfg.loadAccounts();
+      const force = args.includes('-r') || args.includes('--refresh');
+      QuotaEngine.fetchAllQuotas(accounts, force);
+
+      const headers = [
+        { label: 'Rank', align: 'center' },
+        { label: 'Priority', align: 'center' },
+        { label: 'Account' },
+        { label: 'Status', align: 'center' },
+        { label: 'Session Remaining' },
+        { label: 'Session Resets At' },
+        { label: 'Weekly Remaining' },
+        { label: 'Weekly Resets At' },
+      ];
+
+      const rows = accounts.map((a, i) => [
+        i === 0 ? '#1' : `#${i + 1}`,
+        `P${a.priority}`,
+        a.name,
+        makePill(i === 0 ? 'active' : 'standby'),
+        a.quota ? makeGauge(a.quota.sessionRemainingPct) : `${colors.dim}—${colors.reset}`,
+        a.quota?.sessionReset || '—',
+        a.quota ? makeGauge(a.quota.weekRemainingPct) : `${colors.dim}—${colors.reset}`,
+        a.quota?.weekReset || '—',
+      ]);
+
+      console.log(`\n${colors.indigo}${colors.bold}Pool Quota & Remaining Usage${colors.reset}`);
+      printTable(headers, rows);
+      console.log();
+      break;
+    }
+
+    case 'dashboard': {
+      const accounts = cfg.loadAccounts();
+      const stats = MetricsEngine.getPoolStats(accounts);
+      QuotaEngine.fetchAllQuotas(accounts, false);
+
+      console.log();
+      console.log(colors.border + '┌─ ' + colors.indigo + colors.bold + 'Token Pool Dashboard' + colors.border + ' ─'.repeat(45) + '┐' + colors.reset);
+      console.log(colors.border + '│' + colors.reset + `  Today's Pool: ${colors.emerald}${colors.bold}${formatTokenCount(stats.todayPoolTokens)}${colors.reset} │ Output: ${colors.terracotta}${formatTokenCount(stats.todayPoolOutput)}${colors.reset} │ Cache: ${colors.indigo}${formatTokenCount(stats.todayPoolCache)}${colors.reset} │ Lifetime: ${colors.bold}${formatTokenCount(stats.lifetimePoolCache + stats.lifetimePoolOutput)}${colors.reset}`);
+      console.log(colors.border + '└' + '─'.repeat(68) + '┘' + colors.reset);
+      console.log();
+
+      const headers = [
+        { label: 'Priority', align: 'center' },
+        { label: 'Account' },
+        { label: 'Status', align: 'center' },
+        { label: 'Remaining Quota' },
+        { label: "Today's Tokens", align: 'right' },
+        { label: 'Model Breakdown (Today)' },
+        { label: 'Sessions', align: 'center' },
+      ];
+
+      const rows = stats.accounts.map((s, i) => {
+        const acct = accounts.find(a => a.name === s.accountName) || { priority: 99 };
+        const bdown = Object.entries(s.todayTokensByModel)
+          .map(([m, t]) => `${m.replace('claude-', '')}: ${formatTokenCount(t)}`)
+          .join(' · ') || '—';
+
+        return [
+          `P${acct.priority}`,
+          s.accountName,
+          makePill(i === 0 ? 'active' : 'standby'),
+          acct.quota ? makeGauge(acct.quota.sessionRemainingPct, 8) : `${colors.dim}—${colors.reset}`,
+          `${colors.bold}${formatTokenCount(s.todayTotalTokens)}${colors.reset}`,
+          `${colors.slate}${bdown}${colors.reset}`,
+          String(s.totalSessions),
+        ];
+      });
+
+      printTable(headers, rows);
+      console.log(`${colors.dim}Tip: Run ${colors.reset}${colors.indigo}claude-pool limits${colors.reset}${colors.dim} to inspect reset countdowns & weekly quotas.${colors.reset}\n`);
+      break;
+    }
+
+    case 'usage':
+    case 'tokens': {
+      const targetName = args[1];
+      const accounts = cfg.loadAccounts();
+
+      const targets = targetName
+        ? accounts.filter(a => a.name.toLowerCase() === targetName.toLowerCase())
+        : accounts;
+
+      if (targets.length === 0) {
+        console.log(`${colors.red}Account '${targetName}' not found in pool.${colors.reset}`);
+        return;
+      }
+
+      for (const acct of targets) {
+        const stat = MetricsEngine.readAccountStats(acct);
+        console.log();
+        console.log(colors.border + '┌─ ' + colors.indigo + colors.bold + `Token Breakdown: ${acct.name}` + colors.border + ' ─'.repeat(45) + '┐' + colors.reset);
+        console.log(colors.border + '│' + colors.reset + `  Account: ${colors.bold}${acct.name}${colors.reset} [Priority ${acct.priority}] ${colors.slate}· ${acct.email || acct.configDir}${colors.reset}`);
+        console.log(colors.border + '└' + '─'.repeat(71) + '┘' + colors.reset);
+
+        const headers = [
+          { label: 'Model' },
+          { label: 'Input Tokens', align: 'right' },
+          { label: 'Output Tokens', align: 'right' },
+          { label: 'Cache Read', align: 'right' },
+          { label: 'Cache Create', align: 'right' },
+          { label: 'Total Tokens', align: 'right' },
+        ];
+
+        const rows = Object.entries(stat.todayModelsDetail).map(([model, u]) => [
+          model,
+          u.input.toLocaleString(),
+          u.output.toLocaleString(),
+          u.cacheRead.toLocaleString(),
+          u.cacheCreate.toLocaleString(),
+          `${colors.bold}${u.total.toLocaleString()} (${formatTokenCount(u.total)})${colors.reset}`,
+        ]);
+
+        if (rows.length === 0) {
+          rows.push(['No activity today', '0', '0', '0', '0', '0']);
+        }
+
+        console.log(`\n${colors.emerald}${colors.bold}Today's Usage (Total: ${formatTokenCount(stat.todayTotalTokens)})${colors.reset}`);
+        printTable(headers, rows);
+        console.log();
+      }
+      break;
+    }
+
+    case 'priority': {
+      const accounts = cfg.loadAccounts();
+      const headers = [
+        { label: 'Rank', align: 'center' },
+        { label: 'Priority', align: 'center' },
+        { label: 'Account' },
+        { label: 'Status', align: 'center' },
+        { label: 'Email' },
+        { label: 'Config Directory' },
+      ];
+      const rows = accounts.map((a, i) => [
+        i === 0 ? '#1' : `#${i + 1}`,
+        `P${a.priority}`,
+        a.name,
+        makePill(i === 0 ? 'active' : 'standby'),
+        a.email || '—',
+        a.configDir,
+      ]);
+      console.log(`\n${colors.indigo}${colors.bold}Account Priority Ranking${colors.reset}`);
+      printTable(headers, rows);
+      console.log();
+      break;
+    }
+
+    case 'set-priority': {
+      const name = args[1];
+      const prio = parseInt(args[2], 10);
+      if (!name || isNaN(prio)) {
+        console.log(`${colors.red}Usage: claude-pool set-priority <account_name> <priority_number>${colors.reset}`);
+        return;
+      }
+      if (cfg.updateAccountPriority(name, prio)) {
+        console.log(`${colors.emerald}✓ Priority for '${name}' set to P${prio}.${colors.reset}`);
+      } else {
+        console.log(`${colors.red}Error: Account '${name}' not found.${colors.reset}`);
+      }
+      break;
+    }
+
+    case 'status':
+    case 'accounts': {
+      const accounts = cfg.loadAccounts();
+      const headers = [
+        { label: 'Rank', align: 'center' },
+        { label: 'Priority', align: 'center' },
+        { label: 'Account' },
+        { label: 'Status', align: 'center' },
+        { label: 'Email' },
+        { label: 'Plan' },
+        { label: 'Config Directory' },
+      ];
+      const rows = accounts.map((a, i) => [
+        i === 0 ? '#1' : `#${i + 1}`,
+        `P${a.priority}`,
+        a.name,
+        makePill(i === 0 ? 'active' : 'standby'),
+        a.email || '—',
+        a.subscriptionType || '—',
+        a.configDir,
+      ]);
+      printTable(headers, rows);
+      console.log();
+      break;
+    }
+
+    case 'check-auth': {
+      console.log(`\n${colors.indigo}Checking live authentication status across all accounts...${colors.reset}`);
+      const accounts = cfg.loadAccounts();
+      for (const a of accounts) {
+        const st = checkAuthStatus(a.configDir);
+        a.email = st.email;
+        a.subscriptionType = st.plan;
+      }
+      cfg.saveAccounts(accounts);
+      console.log(`${colors.emerald}✓ Authentication check complete.${colors.reset}\n`);
+
+      const headers = [
+        { label: 'Rank', align: 'center' },
+        { label: 'Priority', align: 'center' },
+        { label: 'Account' },
+        { label: 'Status', align: 'center' },
+        { label: 'Email' },
+        { label: 'Plan' },
+      ];
+      const rows = accounts.map((a, i) => [
+        i === 0 ? '#1' : `#${i + 1}`,
+        `P${a.priority}`,
+        a.name,
+        makePill(a.email ? (i === 0 ? 'active' : 'standby') : 'auth_expired'),
+        a.email || '—',
+        a.subscriptionType || '—',
+      ]);
+      printTable(headers, rows);
+      console.log();
+      break;
+    }
+
+    case 'login': {
+      const name = args[1];
+      if (!name) {
+        console.log(`${colors.red}Usage: claude-pool login <account_name>${colors.reset}`);
+        return;
+      }
+      const accounts = cfg.loadAccounts();
+      const target = accounts.find(a => a.name.toLowerCase() === name.toLowerCase());
+      if (!target) {
+        console.log(`${colors.red}Account '${name}' not found.${colors.reset}`);
+        return;
+      }
+      runAccountLogin(target.configDir);
+      const st = checkAuthStatus(target.configDir);
+      if (st.ok) {
+        target.email = st.email;
+        target.subscriptionType = st.plan;
+        cfg.saveAccounts(accounts);
+        console.log(`${colors.emerald}✓ Account '${target.name}' authenticated as ${st.email}.${colors.reset}`);
+      }
+      break;
+    }
+
+    case '--help':
+    case '-h': {
+      console.log(`
+${colors.indigo}${colors.bold}Claude Pool${colors.reset} — Multi-account token pooling and seamless failover manager
+
+${colors.bold}USAGE:${colors.reset}
+  npx claude-pool [COMMAND] [ARGS...]
+  claude-pool [COMMAND] [ARGS...]
+
+${colors.bold}COMMANDS:${colors.reset}
+  ${colors.indigo}claude-pool${colors.reset}                  Launch Claude session with pooled accounts & auto-failover
+  ${colors.indigo}claude-pool setup${colors.reset}            Guided setup wizard to connect accounts from scratch
+  ${colors.indigo}claude-pool limits${colors.reset}           Inspect remaining session/weekly % quota & reset timers
+  ${colors.indigo}claude-pool dashboard${colors.reset}        Real-time aggregated token metrics & model stats
+  ${colors.indigo}claude-pool usage [acct]${colors.reset}     Detailed token breakdown (input, output, cache) per account
+  ${colors.indigo}claude-pool priority${colors.reset}         View or reorder account priority order
+  ${colors.indigo}claude-pool set-priority <name> <p>${colors.reset} Set priority rank for an account
+  ${colors.indigo}claude-pool status${colors.reset}           List configured accounts & health badges
+  ${colors.indigo}claude-pool check-auth${colors.reset}       Verify live authentication across all accounts
+  ${colors.indigo}claude-pool login <acct>${colors.reset}     Re-authenticate an expired account in browser
+`);
+      break;
+    }
+
+    default: {
+      // Pass through any other arguments directly to Claude Code
+      const runner = new ProcessRunner(cfg);
+      runner.runSession(args);
+      break;
+    }
+  }
+}
+
+handleCommand().catch(err => {
+  console.error(`${colors.red}Error:${colors.reset}`, err.message);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "claude-pool",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Multi-account token pooling and seamless failover manager for Claude Code CLI",
+  "main": "bin/cli.js",
+  "type": "module",
+  "bin": {
+    "claude-pool": "bin/cli.js"
+  },
+  "scripts": {
+    "start": "node ./bin/cli.js",
+    "test": "node --test tests/*.test.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "token-pool",
+    "multi-account",
+    "failover",
+    "developer-tools",
+    "cli"
+  ],
+  "author": "Kiran & Claude-Pool Contributors",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kbastwad19/claude-pool.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Kbastwad19/claude-pool/issues"
+  },
+  "homepage": "https://github.com/Kbastwad19/claude-pool#readme",
+  "preferGlobal": true
+}