Coding Agent Account Manager (caam)

Isolated Profiles allow you to run multiple accounts simultaneously with full directory isolation. Each profile receives its own $HOME and tool-specific home variables (like $CODEX_HOME), using symlinks to pass through your real development tooling (like .ssh, .gitconfig, and .npm).

Isolation details:

• Isolated (Real directories): Provider auth directories (e.g., ~/.claude, ~/.config/claude-code, $CODEX_HOME, ~/.gemini, ~/.config/opencode).
• Symlinked (Passthrough): .ssh, .gitconfig, .gnupg, .aws, .cargo, .npm, .local/bin, and most $XDG_CONFIG_HOME entries (e.g., gh, uv).
• Shared (Symlinked): Claude ~/.claude/skills, plugins, commands, and agents are symlinked so user tooling and skills are shared across sessions.
• Never passed through: ~/.local/share/caam (contains the vault).

Use this mode when you need two accounts running at the same time in different terminals.

# Add profiles for different accounts
caam profile add codex work@company.com
caam profile add codex personal@gmail.com

# Execute commands using specific profiles
caam exec codex work@company.com -- "implement feature X"
caam exec codex personal@gmail.com -- "review code"

The Distributed Auth Recovery system automates the process of handling Claude Code rate limits across multiple remote terminal sessions. It solves the problem of manually copying OAuth URLs from a remote server to a local browser and pasting challenge codes back.

Architecture

• Remote (Linux Server): Runs a caam auth-coordinator daemon. It polls WezTerm panes using wezterm cli, detects rate limit messages, injects /login commands, extracts OAuth URLs, and eventually injects the challenge code back into the pane.
• Local (Mac Mini): Runs a caam auth-agent daemon. It polls the remote coordinators, uses Playwright + Chrome to complete the OAuth flow (including Google account selection), and sends the challenge code back to the remote coordinator.

The Recovery State Machine

When a rate limit is detected in a WezTerm pane, the coordinator follows these steps:

1. IDLE $\rightarrow$ Detects "You've hit your limit".
2. RATE_LIMITED $\rightarrow$ Injects /login\n.
3. AWAITING_METHOD_SELECT $\rightarrow$ Detects "Select login method:" and injects 1\n.
4. AWAITING_URL $\rightarrow$ Extracts the OAuth URL via regex.
5. AUTH_IN_PROGRESS $\rightarrow$ Sends URL to local agent and waits for the code.
6. CODE_RECEIVED $\rightarrow$ Injects the code + \n.
7. AWAITING_CONFIRM $\rightarrow$ Detects email confirmation and injects a resumption prompt (e.g., proceed. Reread AGENTS.md...).
8. IDLE $\rightarrow$ Session resumes.

caam uses a health scoring system to indicate the status of your AI provider profiles. This helps you decide which accounts are ready for use and which need attention.

Health Status Indicators

Key Health Signals

When inspecting profiles via caam ls --json or caam status --json, you will see three additive signals per profile:

• refresh_due: true if caam should renew the credential soon. Note: This is false for self-refreshing Claude credentials and credentials without a refresh token.
• launch_usable: true if a new session can start on this account right now. Rotation controllers should use this signal.
• login_required: true if a human must re-authenticate (the credential has lapsed and cannot be renewed automatically).

Note on Rate Limits: An active rate-limit cooldown sets launch_usable to false, but login_required remains false because it is not a login problem.

Because a shallow profile's provider configuration (like .claude.json or .codex/config.toml) is a real, private file, it can diverge from your real HOME when you make changes within a session. To prevent stale configurations (e.g., old MCP server settings), you should sync them.

caam shallow-profile sync-config <name>|--all reconciles the profile with your real HOME using these rules:

• Unit Replacement: Sections (like [mcp_servers.*]) are replaced as a unit, not merged key-by-key. This prevents stale command/args from persisting alongside new url settings.
• Non-destructive: Nothing is deleted. If a profile has a table that your real HOME does not, that table is preserved.
• Codex Enforcement: cli_auth_credentials_store = "file" is re-enforced on every sync to prevent accidental use of shared keychains.

Note: caam shallow-spawn performs a sync automatically unless --no-sync-config is passed.

You can use caam sync to replicate profiles across machines, but you must be aware of provider-specific security constraints.

Rotating Refresh-Token Providers (e.g., Claude, Codex): These providers use a rotating refresh-token family. Replaying a stale token from another machine can revoke the entire account. By default, caam treats these as host-local: caam sync replicates the profile metadata so the machine knows the account exists, but it never replicates the credential payload. Each machine must perform its own caam add to maintain an independent grant.

Non-rotating Providers (e.g., Gemini, OpenCode, Cursor): These maintain the old bidirectional replicate behavior.

Customizing Sync Policy: You can override the sync behavior per provider or per profile in ~/.config/caam/config.json:

{
  "sync_policy": {
    "providers": { "codex": "replicate" },
    "profiles":  { "claude/build-host": "replicate" }
  }
}

Warning: Forcing replicate on a rotating provider will trigger a loud warning if machines have diverged, as converging them risks account revocation.