uwuclxdy/clauth

<p align="center" <img src="media/clauth.png" alt="clauth: Claude Code account switcher and usage monitor TUI" width="480" / </p

<h1 align="center"Claude Code multi-account manager & MCP Plugin</h1

<p align="center" <a href="https://github.com/uwuclxdy/clauth/actions/workflows/release.yml"<img src="https://github.com/uwuclxdy/clauth/actions/workflows/release.yml/badge.svg" alt="Release build status" /</a <a href="https://crates.io/crates/clauth"<img src="https://shields.uwuclxdy.dev/github/v/release/uwuclxdy/clauth?sort=semver&logo=rust&label=version&color=orange" alt="latest version" /</a <a href="https://github.com/uwuclxdy/clauth/releases"<img src="https://shields.uwuclxdy.dev/github/downloads/uwuclxdy/clauth/total?label=downloads&color=blue" alt="GitHub release downloads" /</a <img src="https://shields.uwuclxdy.dev/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-2b90d9" alt="Linux, macOS, Windows" / <a href="LICENSE"<img src="https://shields.uwuclxdy.dev/badge/license-MIT-green" alt="MIT license" /</a </p

<p align="center" <a href="#features"Features</a · <a href="#how-it-works"How it works</a · <a href="#install"Install</a · <a href="#quickstart"Quickstart</a · <a href="#keys"Keys</a · <a href="#configuration"Configuration</a · <a href="#claude-code-plugin"Plugin</a · <a href="#alternatives"Alternatives</a · <a href="#faq"FAQ</a · <a href="#security"Security</a </p

Juggle every Claude Code account from one terminal: switch in a keypress, track live 5h / 7d usage, auto-switch before a limit stops you, even hand a task to another account from inside Claude.

Most account tools do one half. clauth pairs instant switching between multiple Claude Code accounts with a live usage monitor, then wires the two together so a fallback chain moves you off an exhausted account before Claude Code ever blocks. Works with Claude Pro, Max, Team, Enterprise OAuth accounts or any custom API endpoint. Linux, macOS, Windows.

• 🔄 Switch accounts in one keypress or clauth <name: OAuth (Pro / Max / Team / Enterprise) or a custom API endpoint, plan tier detected for you
• 📊 Monitor live 5h / 7d rate-limit bars, a global token dashboard with API-equivalent cost, plus a live Claude status-incident feed
• 🤖 Auto-switch down a fallback chain the moment an account hits its limit, so a long run never stalls
• 🧩 Run in parallel: several accounts at once in isolated config dirs, or a clean headless session with none of your global memory, plugins, or hooks
• 🔌 From inside Claude: an MCP plugin lets a live session list, switch, or delegate a whole prompt (even headless) to another account
• 🛠️ Quality-of-life: per-profile model routing, shell completions, signed self-updates, multi-instance safe

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

Features

<details <summary<bFull feature list</b</summary

Switch accounts

• One-key switching: pick a profile, <kbd⏎</kbd, confirm. Or clauth <profile straight from the shell.
• Log in an account: clauth login <profile [--model <id] opens your browser for a real Claude Code OAuth login (the same PKCE flow Claude Code uses) and writes the minted tokens straight into a new profile, without touching the session you're already logged into. Pass an existing profile name to re-authenticate it in place; clauth asks to confirm before replacing that profile's saved login. Works identically on every desktop platform (Linux, macOS, Windows), unlike running Claude Code's own /login, which on macOS lands only in a per-config-dir Keychain item and leaves the profile empty. --model sets the profile's default model (a preset alias or a full model id). Pass --base-url <url and --api-key <key instead to add or rotate an API-key account (DeepSeek, Z.ai, any Anthropic-compatible endpoint) with no browser. Any value a flag omits is prompted; the key is read echo-off so it stays out of shell history. Pass --setup-token to capture a claude setup-token mint instead: the pasted token (echo-off, or piped on stdin) becomes the profile's long-lived session-token.json, so its sessions run on a static ~1-year login that never races clauth's token refresher — the Setup tab then shows a token row counting down to the re-mint (--yes replaces an existing one unprompted). The split engages only for a genuinely long-lived token (no refresh token in the sidecar) — a mis-filled rotating pair is ignored, called out on the card, and switches keep installing the normal credentials.
• Delete an account: clauth delete <profile [--yes|-y] [--force] removes a profile and all its credentials (OAuth tokens or API key, caches, the on-disk profile dir; a deleted active account is also unwired from live ~/.claude). Confirms [y/N] on a TTY unless --yes (-y). Delete is irreversible, so a non-TTY run must pass --yes; it never deletes unprompted. A profile with a live clauth start session is refused unless you pass --force (--yes alone will not override it).
• Account-change detection: if Claude Code logged 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 [--isolated] <profile [claude args...] runs claude in a per-profile CLAUDECONFIGDIR (symlink mirror; copies on Windows without symlink privilege), so account identity and billing caches never leak between profiles. Add --isolated for a clean session that keeps the account's auth but drops your global CLAUDE.md memory, plugins, and hooks, for headless or blind runs (run it in an empty directory to skip project memory too).

• Status-line aware: clauth which [--json] prints which profile owns the loaded credentials.json, and with --json adds its plan tier and the endpoint it routes to.
• Per-profile model routing: each account can carry its own model overrides on the Setup tab (a default model plus per-tier opus / sonnet / haiku / subagent ids), so a switch or clauth start pins which models that account drives.
• 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: on the Overview tab, an account's refresh countdown turns yellow when showing last-known numbers (cache or rate limit), red when the fetch failed. A × marks an account whose login broke and needs a re-login.
• 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 charts that grow with the terminal. Press <kbdc</kbd to count cache reads/writes in the totals; models past 1M tokens break out on their own. The <kbda</kbd actions menu narrows the model bars and the per-model breakdown to Claude models only, or to everything else. <kbdt</kbd cycles a period lens (lifetime, today, this week, this month), re-scoping the dashboard cards and the per-model breakdown to that window (figures older days can't back, like cache splits, fall back to lifetime with a badge, and costs show as $X+ floors).

• 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.
• Plugin wiring check: the Plugin tab confirms clauth is hooked into Claude Code (clauth on PATH, the mcpServers entry or plugin install, a working claude --version) next to each profile's runtime state. One-key fixes cover the writes clauth can safely make itself: wire mcpServers, repair a diverged credential link. Plugin install stays guided.

Automate & stay safe

• Automatic token refresh: clauth rotates each account's OAuth pair ahead of expiry, early enough that the running claude never reaches its own refresh threshold and clauth's copy stays the live one. A stale access token still rotates the moment a usage query 401s. Because a dead login often surfaces as an HTTP 429 rather than a 401, a 429 on an already clock-expired token still chases the refresh, so a revoked token is seen rather than masked behind stale cached usage forever. A refresh that fails terminally quarantines the account as authbroken: it is excluded from every fallback-chain walk and refused as a switch target (installing a dead token would sign out every running claude), until clauth login <name, or any later successful refresh, clears it. The active account shares its single-use chain with the running claude, and whoever refreshes first revokes the other side, so clauth never bets on winning that race. When Claude Code rotates first — on any platform — clauth adopts CC's fresher pair from its file mirror (identity-guarded: a login belonging to a different account is never captured unattended) instead of spending a revoked refresh token; when clauth rotates on macOS, it mirrors the fresh pair straight into the Keychain so the running claude never lapses (rotation coherence, #1). The Config tab's rotation setting drops back to lazy (refresh only once a request rejects the token) if you'd rather. <kbdt</kbd force-rotates every account (on macOS, one with a running clauth start session is skipped: its login lives in a keychain entry clauth can't write, so rotating would sign the session out).
• 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. Headroom means BOTH windows: past the weekly line (7d, default 98%, tunable on the Config tab — and per-account via the Fallback tab's weekly at override, which keeps the Config-tab value as the chain-wide default) an account counts as exhausted, and the active one switches away while there is still room to land the hop (topping out the week bricks an account for days, not hours). The walk never picks such a member (one marked last resort still accepts, as the chain's parking spot) nor "recovers" it on a 5h rollover. Per-model weekly windows (e.g. "7d fable") gate the same way: an account whose scoped week is past the line stays out of rotation — a session of the capped model landed there would strand, and the walk can't know which model the next session runs. Both checks are per-account toggles on the Fallback tab: flip an account's scoped gate off to keep rotating to it for other models, or its weekly gate off to ignore the soft weekly line there (the 100% hard cap always blocks). An opt-in burn-aware mode (Config tab) switches on projected usage instead: heavy burn hops early, light burn rides closer to 100% before moving. An opt-in allow extra usage lets a spent chain fall back to an account's pay-as-you-go billing rather than stopping: it needs the Config-tab toggle and a per-account max spend ceiling (Fallback tab, $0 and off by default) and billing actually enabled on that account, so nothing is ever spent by default, and an account with subscription quota left always wins over one that costs money. The ceiling is a real cap, not just a gate on starting: once an account has spent it, clauth stops using that account, parking on your last resort if you named one and otherwise switching off. That halt is its own extra usage spent setting rather than quota spent, since staying put costs nothing when quota runs out and costs money when a budget does. Runs in the TUI, or unattended via clauth daemon with the TUI closed. A dead login is a switch trigger too: an active account flagged authbroken can never report fresh usage again, so the daemon walks to the next healthy member instead of wedging on the corpse. Wrap-off (halt everything) still keys on real usage exhaustion only, never on the flag alone.
• Headless daemon + status feed: clauth daemon runs the usage-refresh + auto-switch loop with no TUI, writing ~/.clauth/status.json (atomic, 0600, schema-versioned, additive evolution; the read contract lives in wiki/daemon.md) each tick for external readers like a menu-bar app. clauth status --json prints the same shape on demand, no daemon required. A single-instance lock keeps two daemons from double-firing: a second clauth daemon exits on the spot by default, so a spawner that fires repeatedly can't pile up idle daemons. clauth daemon --status answers "is one already up?" (exit 0/1) without starting anything; --standby instead parks and takes over when the first dies (for a launchd/systemd unit paired with a manual run); --replace terminates the running daemon and takes over, for an in-place upgrade. An anti-wedge watchdog aborts a stuck loop for a clean supervisor restart, and a TUI opened alongside detects the daemon (singleton-lock + feed-freshness probe, re-checked every tick) and stands its own refresher down (one fetcher, one rotation writer, one switch decision-maker), re-arming within a tick of the daemon exiting.
• Multi-instance safe: state writes serialize through a file lock, each instance reloads on external changes, HTTP runs off the UI thread.
• In-app help: <kbd?</kbd opens a keybinding reference scoped to the current tab.