clauth: Claude Code Account Switcher & Usage Monitor

How it works · Install · Features · Quickstart · Keys · Auto-switch · Alternatives · FAQ · Security

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

• 🔄 Switch accounts with one keypress, or clauth <name> from the shell
• 📊 Monitor live 5h / 7d usage bars, a global token dashboard, and API-equivalent cost
• 🤖 Auto-switch to the next account in a fallback chain when you run out of budget
• 🧩 Parallel sessions: run several accounts at once in isolated config dirs

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

How it works

Claude Code stores its session in ~/.claude/.credentials.json (OAuth tokens) and the env block of ~/.claude/settings.json (base URL, API key). clauth keeps a per-profile snapshot of both. A switch swaps those two in place and leaves the rest of ~/.claude/ untouched. clauth start takes a different route: it launches claude against a temporary ~/.claude mirror, so several accounts run at once.

flowchart LR
    P["profiles in<br/>~/.clauth"]
    P -->|"clauth work"| S["swap ~/.claude<br/>credentials + env, in place"]
    P -->|"clauth start work"| I["launch claude in an<br/>isolated config dir"]
    ANT["api.anthropic.com"] -. "poll usage, refresh tokens" .-> P
    P -. "auto-switch at your limit" .-> P

Installation

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 verifies a checksum and a signature before it runs, and CLAUTH_NO_UPDATE=1 turns updates off. Details in SECURITY.md.

On first 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

Switch accounts

• One-key switching: pick a profile, ⏎, confirm. Or clauth <profile> straight from the shell.
• 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.
• Non-destructive: a switch touches only the API keys and the profile's declared env block in settings.json. Nothing else moves.
• 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 up bash, zsh, or fish.

Monitor usage

• 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-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.
• Per-row activity: a 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.
• Stale-data cues: an account name underlines yellow when served from cache, red when there's no data.
• Token usage dashboard: the Tokens tab reads Claude Code's own token history (the stats cache, topped up from live session transcripts). It rolls that into per-model totals with a today panel, daily peak, busiest hour, and usage sparklines. Press c to count cache reads/writes in the totals; models past 1M tokens break out on their own.
• API-equivalent cost: the Tokens tab prices your recorded usage at live pay-as-you-go API rates, i.e. what those same tokens would cost on the API. Rates come from LiteLLM's price feed and are disk-cached, computed per model (families differ up to 10×) and cache-aware (reads and writes priced at their own rates). Cost shows on the today and total cards, the per-model detail, and the top-models bars. It stays blank until rates load.
• 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.

Automate & stay safe

• Automatic token refresh: OAuth refresh tokens are single-use, so rotation stays lazy. A stale access token rotates the moment a usage query 401s, never ahead of time. t force-rotates every account.
• 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.
• Multi-instance safe: state writes serialize through a file lock, each instance reloads on external changes, and HTTP runs off the UI thread.
• In-app help: ? opens a keybinding reference scoped to the current tab.

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 shows in orange. Usage bars are cached locally, so they stay on screen even when the Anthropic API is rate-limited or offline. ← → move between the seven tabs:

[!TIP]
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.

Keys

Keys are scoped to the current tab; ? lists every binding for the tab you're on.

Profile types

Claude Pro / Max / Team / Enterprise (OAuth): leave the base URL blank. clauth captures the OAuth token from your running session, restores it on switch, and detects the plan tier for you.

API endpoint: set a base URL and, optionally, an API key. Works with the official Anthropic API or any compatible proxy. Edit the URL or key 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 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 no window is running. On a cold start it fetches usage before the first ping, so it never fires 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 still works on read.

[!IMPORTANT]
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), clauth checks the active profile. If it's 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 then 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 keeps you on the last account; on switches off all accounts, then re-arms once any member drops back under its threshold.
• No eligible target keeps clauth put. If the active profile isn't in the chain, auto-switch is 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.

Alternatives

Most tools do one half. clauth does both in one TUI: switching and live usage, tied together 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; the Tokens tab adds a global token dashboard with API-equivalent cost.

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 only ever go to Anthropic. See SECURITY.md for the full breakdown.

~/.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/
      ...

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