caam

What this skill does

# 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:**
```bash
caam activate claude [email protected]   # ~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/[email protected]/
~/.codex/auth.json ←→ ~/.local/share/caam/vault/codex/[email protected]/
```

**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

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

# Backup current account
caam backup claude [email protected]

# Clear and login to another account
caam clear claude
claude  # /login with [email protected]
caam backup claude [email protected]

# Switch instantly forever
caam activate claude [email protected]   # < 100ms
caam activate claude [email protected]     # < 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.

```bash
caam backup claude [email protected]
caam activate claude [email protected]
```

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

### 2. Isolated Profiles (Parallel Sessions)

Run multiple accounts **simultaneously** with full directory isolation.

```bash
caam profile add codex [email protected]
caam profile add codex [email protected]
caam exec codex [email protected] -- "implement feature X"
caam exec codex [email protected] -- "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 typ