<p align="center">
<img src="media/clauth.png" alt="clauth — Claude Code account switcher and usage monitor TUI" width="480" />
</p>
[](https://github.com/uwuclxdy/clauth/actions/workflows/release.yml)
[](https://crates.io/crates/clauth)
# Claude Code Account Switcher and Usage Monitor
**clauth** is a terminal UI to **switch between multiple Claude Code accounts** without logging out, and to monitor Claude 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 — everything else stays intact. `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):
```bash
cargo install clauth
```
**Via install script** (no Rust toolchain required; `--nocargo` forces a binary download):
```bash
**Build from source:**
```bash
git clone https://github.com/uwuclxdy/clauth
cd clauth
cargo build --release
# binary at ./target/release/clauth
```
Binary installs self-update in the background; cargo installs upgrade via `cargo install clauth`.
On the first TUI launch, clauth installs shell completions once for your detected shell (bash/zsh/fish): it appends a `source` line to your shell rc and drops `~/.clauth/.completions_installed` so it never repeats. Delete that file (or run `clauth completions install [shell]`) to redo it.
### Auto-update
On launch, a background thread checks GitHub for a newer release, verifies the SHA-256 against `sha256sums.txt` (fail-closed), and self-replaces on next launch. Cargo-installed builds are notified only; `CLAUTH_NO_UPDATE=1` disables all checks.
## 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; 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.
## Quickstart
Capture your current Claude Code session as a profile:
```bash
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:
```bash
clauth work
# switched to 'work'
```
Run claude under a profile without touching the global config:
```bash
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 six tabs — **Overview** (switch and reorder accounts), **Usage** (per-account window breakdown), **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`:
```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. A cold start fetches usage before the first kick — never pinging blind over a window that may already be live — so the timer can arm one tick late. Default off, OAuth profiles only. The older field name `kick_timer = true` is still accepted on read.
## 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
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's angle is both halves in one TUI — switching *and* live usage — connected by the auto-switch chain.
| [claude-swap](https://github.com/realiti4/claude-swap) | CLI account switcher (token backup/restore) | no usage view, no auto-switch |
| [CCSwitcher](https://github.com/XueshiQiao/CCSwitcher), [claude-account-switcher](https://github.com/Symbioose/claude-account-switcher) | macOS menu-bar switchers | macOS-only, no fallback chain |
| [cc-account-switcher](https://github.com/ming86/cc-account-switcher) | credential-swap scripts | no TUI, no usage |
| [Claude-Code-Usage-Monitor](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor) | real-time usage monitor with predictions | monitoring only, single account |
| [claude-code-statusline](https://github.com/ohugonnot/claude-code-statusline) | rate-limit status line inside Claude Code | in-session display, no switching |
| `CLAUDE_CONFIG_DIR` by hand | manual per-account config dirs | what `clauth start` automates |
## 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.
## License
MIT