caam

CAAM — Coding Agent Account Manager

A Go CLI for instant account switching between fixed-cost AI coding subscriptions (Claude Max, GPT Pro, Gemini Ultra). When you hit rate limits, swap accounts in ~50ms instead of 30-60 seconds of browser OAuth friction.

Why This Exists

You're paying $200-275/month for fixed-cost AI coding subscriptions. These plans have rolling usage limits—not billing caps, but rate limits that reset over time. When you hit them mid-flow:

The Problem:

/login → browser opens → sign out of Google → sign into different Google →
authorize app → wait for redirect → back to terminal

That's 30-60 seconds of friction, 5+ times per day across multiple tools.

The Solution:

caam activate claude bob@gmail.com   # ~50ms, done

No browser. No OAuth dance. No interruption to your flow state.

How It Works

Each AI CLI stores OAuth tokens in plain files. CAAM backs them up and restores them:

~/.claude.json ←→ ~/.local/share/caam/vault/claude/alice@gmail.com/
~/.codex/auth.json ←→ ~/.local/share/caam/vault/codex/work@company.com/

That's it. No daemons, no databases, no network calls. Just cp with extra steps.

Why This Works

OAuth tokens are bearer tokens—possession equals access. The CLI tools don't fingerprint your machine beyond what's already in the token file. Swapping files is equivalent to "being" that authenticated session.

Profile Detection

caam status uses content hashing:

1. SHA-256 hash current auth files
2. Compare against all vault profiles
3. Match = that's what's active

This means:

• Profiles are detected even if you switched manually
• No hidden state files that can desync
• Works correctly after reboots

Quick Start

# Install
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_account_manager/main/install.sh?$(date +%s)" | bash

# Backup current account
caam backup claude alice@gmail.com

# Clear and login to another account
caam clear claude
claude  # /login with bob@gmail.com
caam backup claude bob@gmail.com

# Switch instantly forever
caam activate claude alice@gmail.com   # < 100ms
caam activate claude bob@gmail.com     # < 100ms

# Check status
caam status

Two Operating Modes

1. Vault Profiles (Simple Switching)

Swap auth files in place. One account active at a time per tool. Instant switching.

caam backup claude work@company.com
caam activate claude personal@gmail.com

Use when: You want to switch between accounts sequentially (most common).

2. Isolated Profiles (Parallel Sessions)

Run multiple accounts simultaneously with full directory isolation.

caam profile add codex work@company.com
caam profile add codex personal@gmail.com
caam exec codex work@company.com -- "implement feature X"
caam exec codex personal@gmail.com -- "review code"

Each profile gets its own $HOME and $CODEX_HOME with symlinks to your real .ssh, .gitconfig, etc.

Use when: You need two accounts running at the same time in different terminals.

Supported Tools

| Tool | Subscription | Auth Files | |------|--------------|------------| | Claude Code | Claude Max ($200/mo) | ~/.claude.json, ~/.config/claude-code/auth.json, ~/.claude/settings.json | | Codex CLI | GPT Pro ($200/mo) | ~/.codex/auth.json (or $CODEX_HOME/auth.json) | | Gemini CLI | Gemini Ultra (~$275/mo) | ~/.gemini/settings.json, ~/.gemini/oauth_credentials.json, ~/.gemini/.env |

Tool-Specific Details

Claude Code (Claude Max)

• Login: /login inside CLI
• Rate Limits: 5-hour rolling usage window
• Notes: When you hit limits, you'll see rate limit messages. Switch accounts to continue.

Codex CLI (GPT Pro)

• Login: codex login or codex login --device-auth (headless)
• Notes: Respects CODEX_HOME. CAAM enforces file-based auth by writing cli_auth_credentials_store = "file" to ~/.codex/config.toml.

Gemini CLI (Google One AI Premium)

• Login: Start gemini, select "Login with Google" or use /auth to switch modes
• Notes: OAuth cache stored in oauth_credentials.json, API key mode uses .env.

Command Reference

Auth File Swapping (Primary)

| Command | Description | |---------|-------------| | caam backup <tool> <email> | Save current auth files to vault | | caam activate <tool> <email> | Restore auth files from vault (instant switch) | | caam status [tool] | Show which profile is currently active | | caam ls [tool] | List all saved profiles in vault | | caam delete <tool> <email> | Remove a saved profile | | caam paths [tool] | Show auth file locations for each tool | | caam clear <tool> | Remove auth files (logout state) | | caam uninstall | Restore originals and remove caam data/config |

Aliases: caam switch and caam use work like caam activate

Activate Options

| Flag | Description | |------|-------------| | --auto | Use rotation algorithm to pick best profile | | --backup-current | Backup current auth before switching | | --force | Activate even if profile is in cooldown |

Uninstall Options

| Flag | Description | |------|-------------| | --dry-run | Show what would be restored/removed | | --keep-backups | Keep vault after restoring originals | | --force | Skip confirmation prompt |

Smart Profile Management

| Command | Description | |---------|-------------| | caam activate <tool> --auto | Auto-select best profile using rotation algorithm | | caam next <tool> | Preview which profile rotation would select | | caam run <tool> [-- args] | Wrap CLI with automatic failover on rate limits | | caam cooldown set <provider/profile> | Mark profile as rate-limited (default: 60min) | | caam cooldown list | List active cooldowns with remaining time | | caam cooldown clear <provider/profile> | Clear cooldown for a profile | | caam cooldown clear --all | Clear all active cooldowns | | caam project set <tool> <profile> | Associate current directory with a profile | | caam project get [tool] | Show project associations for current directory | | caam tui | Interactive TUI dashboard |

Profile Isolation (Advanced)

| Command | Description | |---------|-------------| | caam profile add <tool> <email> | Create isolated profile directory | | caam profile ls [tool] | List isolated profiles | | caam profile delete <tool> <email> | Delete isolated profile | | caam profile status <tool> <email> | Show isolated profile status | | caam login <tool> <email> | Run login flow for isolated profile | | caam exec <tool> <email> [-- args] | Run CLI with isolated profile |

Smart Profile Management

When you have multiple accounts across multiple providers, manually tracking which account has headroom becomes tedious. Smart Profile Management automates this decision-making.

Profile Health Scoring

Each profile displays a health indicator:

| Icon | Status | Meaning | |------|--------|---------| | 🟢 | Healthy | Token valid for >1 hour, no recent errors | | 🟡 | Warning | Token expiring within 1 hour, or minor issues | | 🔴 | Critical | Token expired, or repeated errors in last hour | | ⚪ | Unknown | No health data available yet |

Health scoring combines:

• Token expiry: Time until OAuth token expires
• Error history: Recent authentication or rate limit errors
• Penalty score: Accumulated issues with exponential decay (20% reduction every 5 minutes)
• Plan type: Enterprise/Pro plans get slight scoring boosts

After ~30 minutes of no errors, penalty score returns to near zero.

Proactive Token Refresh

CAAM automatically refreshes OAuth tokens before they expire, preventing mid-session auth failures.

Smart Rotation Algorithms

When you run caam activate claude --auto:

| Algorithm | Description | |-----------|-------------| | smart (default) | Multi-factor: cooldown state, health, recency (avoids last 30min), plan type