caam

name	caam
description	Manage AI coding CLI accounts with sub-100ms switching. Use when hitting rate limits on Claude Max, GPT Pro, or Gemini Ultra subscriptions and need instant account swapping without browser OAuth.

CAAM — Coding Agent Account Manager

Core Problem: You hit rate limits on your $200/mo Claude Max subscription. Browser OAuth takes 30-60 seconds. CAAM swaps accounts in ~50ms.

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 [e-mail]

# Clear, login with another account, backup that too
caam clear claude
claude  # /login with [e-mail]
caam backup claude [e-mail]

# Switch instantly forever
caam activate claude [e-mail]   # ~50ms
caam activate claude [e-mail]     # ~50ms

---

THE EXACT PROMPT — Daily Commands

Check Status

caam status

Shows active profile for each tool based on content hash matching.

Instant Switch

caam activate claude [e-mail]

Restores auth files from vault. ~50ms, no browser.

Smart Auto-Switch

caam activate claude --auto

Rotation algorithm picks best profile based on health, recency, cooldowns.

Mark Rate Limited

caam cooldown set claude

Marks current profile for 60min. Rotation skips it.

Zero-Friction Aliases

# Add to .bashrc/.zshrc
alias claude='caam run claude --'
alias codex='caam run codex --'
alias gemini='caam run gemini --'

# Now these auto-failover on rate limits
claude "explain this code"

---

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/[e-mail]/
~/.codex/auth.json ←→ ~/.local/share/caam/vault/codex/[e-mail]/

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

---

Supported Tools

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

---

Smart Rotation

When you have multiple accounts, rotation picks the best one:

# Preview what rotation would select
caam next claude

# Let it pick automatically
caam activate claude --auto

Health Indicators

Icon	Status	Meaning
🟢	Healthy	Token valid >1hr, no recent errors
🟡	Warning	Token expiring <1hr, minor issues
🔴	Critical	Token expired, repeated errors
⚪	Unknown	No health data yet

Rotation Algorithms

Algorithm	Description
smart (default)	Cooldown + health + recency + jitter
round_robin	Sequential, skipping cooldowns
random	Random among non-cooldown

---

Cooldown Tracking

# Mark current profile (60min default)
caam cooldown set claude

# Specify profile and duration
caam cooldown set claude/[e-mail] --minutes 120

# View active cooldowns
caam cooldown list

# Clear early
caam cooldown clear claude/[e-mail]

---

TUI Dashboard

caam tui

Keybindings

Key	Action
↑/↓	Navigate profiles
Enter	Activate selected
p	Set project association
c	Mark/clear cooldown
r	Refresh
q	Quit

---

Project Associations

Link profiles to directories:

cd ~/projects/work-app
caam project set claude [e-mail]

# Now in this directory:
caam activate claude  # Auto-uses [e-mail]

---

Command Reference

Command	Description
caam backup <tool> <email>	Save current auth to vault
caam activate <tool> <email>	Restore auth from vault
caam activate <tool> --auto	Auto-select best profile
caam status [tool]	Show active profiles
caam ls [tool]	List saved profiles
caam clear <tool>	Remove auth files (logout)
caam run <tool> [-- args]	Wrap with auto-failover
caam cooldown set <profile>	Mark as rate limited
caam cooldown list	Show active cooldowns
caam next <tool>	Preview rotation selection
caam tui	Interactive dashboard

---

Flywheel Integration

Tool	Integration
NTM	Each tmux pane uses different account via isolated profiles
Agent Mail	Agents coordinate account switching across sessions
CASS	Search sessions by account for usage patterns

---

References

Topic	Reference
Complete commands	COMMANDS.md
Isolated profiles	ISOLATED-PROFILES.md
Vault structure	VAULT.md

---

Validation

# Verify installation
caam --version

# Check all profiles
caam status

# Test switch
caam activate claude --auto && caam status