clauth 0.6.0

clauth is a terminal UI to switch between multiple Claude Code accounts without logging out, and to monitor Claude Code usage and rate limits in real time. It handles Claude Pro / Max / Team / Enterprise OAuth accounts and custom API endpoints, auto-switches to a fallback account when you hit the 5-hour limit, and runs parallel Claude Code sessions under different accounts. Linux, macOS, Windows.

Font is kinda off on the recording, I promise it looks better than this

How it works

Claude Code keeps session state in ~/.claude/.credentials.json (OAuth tokens) and the env block of ~/.claude/settings.json (base URL, API key). clauth snapshots both per profile. On switch it swaps .credentials.json and the API env keys in place and leaves everything else untouched. clauth start instead launches claude in a temporary ~/.claude mirrored via symlinks, so multiple accounts run simultaneously.

Install

Supported platforms: Linux, macOS, Windows (Git Bash / MSYS2).

Via cargo (recommended):

cargo install clauth

Via install script (no Rust toolchain required; --nocargo forces a binary download):

curl -fsSL https://raw.githubusercontent.com/uwuclxdy/clauth/mommy/install.sh | bash

Build from source:

git clone https://github.com/uwuclxdy/clauth
cd clauth
cargo build --release
# binary at ./target/release/clauth

Binary installs update themselves in the background; cargo installs upgrade with cargo install clauth. Every install and update path checks a checksum and signature before it runs, and CLAUTH_NO_UPDATE=1 turns updates off. Details in SECURITY.md.

On first TUI launch, clauth offers to install shell completions. It asks before touching your shell rc, and CLAUTH_NO_COMPLETIONS=1 skips it. Re-run any time with clauth completions install [shell].

Features

• One-key switching: pick a profile, ⏎, confirm. Or clauth <profile> straight from the shell.
• Automatic token refresh: OAuth refresh tokens are single-use, so rotation is lazy. A stale access token rotates the moment a usage query 401s, never proactively. t force-rotates every account.
• Live usage bars: 5h utilization from the Anthropic API on a configurable interval (default 90 s), color-coded with the next reset time. Max accounts also get a 7-day bar.
• Per-row activity: countdown to the next refresh, or a color-coded spinner (sapphire fetch, cyan token refresh, green auto-start).
• Plan detection: Pro, Max (5x / 20x), Team, Enterprise, identified via /api/oauth/profile.
• Per-account breakdown: the Usage tab lays out every window (5h, 7d, 7d sonnet, 7d opus, paid extra-usage spend) plus endpoint, fallback threshold, and merged env keys.
• Auto-switch on exhaustion: opt accounts into an ordered fallback chain. When the active one crosses its 5h threshold (95% default), clauth hops to the next member with headroom. Needs clauth open.
• Stale-data cues: account name underlines yellow when served from cache, red when there's no data.
• Account-change detection: if Claude Code signed into a different account while clauth was closed, you get a [Y/n] prompt before stored tokens are overwritten.
• Multi-instance safe: state writes serialize through a file lock, each instance reloads on external changes, and HTTP runs off the UI thread.
• Non-destructive: only the API keys plus the profile's declared env block in settings.json are touched.
• Isolated launch: clauth start <profile> [claude args...] runs claude in a per-call CLAUDE_CONFIG_DIR (symlink mirror; copies on Windows without symlink privilege), so account identity and billing caches never leak between profiles.
• Status-line aware: clauth which [--json] prints which profile owns the loaded credentials.json.
• Shell completions: clauth completions install [shell] wires bash, zsh, or fish.
• In-app help: ? opens a keybinding reference scoped to the current tab.
• Claude status feed: the Status tab pulls live incidents from status.claude.com, with per-component health (claude.ai, API, Claude Code, Cowork), severity, and timeline, cached to disk.
• API-equivalent cost: the Tokens tab prices recorded usage at live pay-as-you-go API rates — what your subscription usage would cost on the API. Rates are fetched from LiteLLM's price feed and disk-cached, computed per model (families differ up to 10×) and cache-aware (cache reads/writes priced at their own rates). Shown on the today and total cards, the per-model detail, and the top-models bars; — until rates load.

Quickstart

Capture your current Claude Code session as a profile:

clauth
# Select "+ new from current profile", enter a name, e.g. "work"

Repeat while logged in to a different account, then switch in the TUI (⏎ + confirm) or directly by name:

clauth work
# switched to 'work'

Run claude under a profile without touching the global config:

clauth start personal -- --model haiku
# spawns claude with personal's credentials in an isolated CLAUDE_CONFIG_DIR

The active profile is shown in orange. Usage bars are cached locally, so they stay visible even if the Anthropic API is rate-limited or offline. ←/→ move between the seven tabs: Overview (switch and reorder accounts), Usage (per-account window breakdown), Tokens (global Claude Code token stats + API-equivalent cost across all models), Setup (endpoint, key, env, auto-start), Fallback (chain editor), Config (theme, refresh interval, wrap-off, divergence default), and Status (Claude incident feed). ? shows the rest.

Dev-only: cargo test showcase -- --ignored --nocapture runs the real interactive TUI on fake data against a throwaway home dir (never built into the binary, no network). Handy for screenshots.

Profile types

Claude Pro / Max / Team / Enterprise (OAuth) — leave base URL blank. clauth captures the OAuth token from your running session and restores it on switch; the plan tier is detected automatically.

API endpoint — set a base URL and (optionally) an API key. Works with the official Anthropic API or any compatible proxy. URL and key are editable any time without losing stored credentials.

Auto-starting the 5-hour timer

The 5-hour usage window only starts after a real inference call. The OAuth refresh clauth runs at launch doesn't trigger it. To arm a profile's timer at clauth startup, toggle auto-start on the Setup tab, or set it in ~/.clauth/profiles/<name>/config.toml:

auto_start = true

When enabled, clauth sends a tiny Haiku ping (max_tokens = 1, fractions of a cent) on launch and on each refresh tick while there's no running window. On a cold start it fetches usage before the first kick, so it never pings blind over a window that might already be live; the timer can arm one tick late as a result. Default off, OAuth profiles only. The older field name kick_timer = true is still accepted on read.

The ping is a real, billed /v1/messages call under your own OAuth token, the same request Claude Code fires on startup (see what acts on your behalf). Leave auto-start off if you'd rather only the live claude process open a window.

Automatic account switching

The Fallback tab holds an ordered chain of profiles that clauth hops between when one runs out of 5-hour budget:

• Each member has its own threshold (5h utilization %, default 95%); edit inline (+/- or type).
• After each usage refresh (at startup and on every tick), if the active profile is a chain member at or above its threshold, clauth walks the chain (wrapping) and switches to the first member under its own threshold. The ◆ marker shifts in place.
• A 100% threshold marks a last-resort sink: chosen only when every other member is past its threshold. Claude Code surfaces its own "out of 5h limit" message after the switch lands.
• The chain-global wrap-off toggle (Config tab) decides what happens when everyone is exhausted and no sink exists: off = stay on the last account; on = switch off all accounts, then re-arm automatically once any member drops back under its threshold.
• No eligible target → clauth stays put. Active profile not in the chain → auto-switch disabled. Profiles outside the chain are never switched away from or to. It's opt-in.

Configuration lives in ~/.clauth/profiles.toml (fallback_chain, ordered) and per-profile config.toml (fallback_threshold); both are safe to hand-edit.

Storage layout

~/.clauth/
  profiles.toml          # profile order, active marker, fallback chain, wrap-off, theme, refresh interval
  price_cache.json       # cached model price table (LiteLLM rates) for the Tokens cost lens
  status_cache.json      # cached Claude status incident feed
  profiles/
    work/
      config.toml        # base_url, api_key, auto_start, fallback_threshold, [env]
      credentials.json   # OAuth token snapshot (credentials.json.pending while a rotation is mid-write)
      usage_cache.json   # last known utilization + plan info
      runtime/           # isolated CLAUDE_CONFIG_DIR tree for `clauth start`
      sessions/          # per-session PID files (ref-counting live launches)
    personal/
      ...

Alternatives

Most tools in this space do one half. clauth does both in one TUI, switching and live usage, connected by the auto-switch chain.

FAQ

How do I switch between multiple Claude Code accounts without logging out? Install clauth, save each logged-in session as a profile once, then switch with clauth <name> or a single keypress in the TUI. No browser, no re-login.

Can I run Claude Code with multiple accounts at the same time? Yes. clauth start <profile> launches claude in an isolated CLAUDE_CONFIG_DIR, so parallel sessions don't share identity, settings, or billing caches.

Can Claude Code switch accounts automatically when I hit the 5-hour limit? With clauth open, yes: put accounts in the fallback chain and clauth switches to the next member with headroom the moment the active one crosses its threshold.

How do I monitor Claude Code usage and rate limits? The Overview tab shows color-coded 5h (and 7-day) bars per account with reset times; the Usage tab breaks down every rate-limit window the API reports.

Does it work with Claude Pro, Max, Team, and Enterprise? Yes. OAuth profiles cover all paid tiers (plan auto-detected, including Max 5x / 20x). API-endpoint profiles cover the Anthropic API or any compatible proxy.

Where does clauth store my Claude Code credentials? Locally under ~/.clauth/, with 0600 permissions on Unix. Tokens are only ever sent to Anthropic. See SECURITY.md for the full breakdown.

Security

clauth handles live OAuth tokens and replaces its own binary over the network, so SECURITY.md lays out the trust model: where credentials live, every host clauth contacts, how updates get verified, and how to switch each behavior off. Found something exploitable? Report it privately through the repo's Security → Report a vulnerability.

License

MIT