Claude Code account switcher for uninterrupted sessions.

cux is a CLI tool for Claude Code that pools multiple Pro/Max accounts behind a single live session. When the active account hits a rate limit, cux switches to a healthy account and continues the same conversation. For proactive threshold swaps, it waits for the current turn to finish first. No logout, no reload, no lost context.

$ cux
cux: rate limit on alice@example.com → swapped to bob@example.com, resuming…
> What number did I tell you to remember?
4729.

Install

Three install methods. Pick the one that fits your platform — they all install the same cux binary.

Option 1 — npm

Works on Linux, macOS and Windows. Requires Node.js 18 or newer.

npm install -g @inulute/cux

Option 2 — shell installer

Works on Linux, macOS, WSL and Git Bash on Windows.

curl -fsSL https://raw.githubusercontent.com/inulute/cux/main/scripts/install.sh | sh

Option 3 — manual binary

Works everywhere. Useful if you don't want Node.js and can't run shell scripts (e.g. native Windows PowerShell or cmd.exe).

Download the matching artefact from the releases page:
- cux-linux-amd64, cux-linux-arm64
- cux-darwin-amd64, cux-darwin-arm64
- cux-windows-amd64.exe
On Linux/macOS, chmod +x cux-<os>-<arch> and rename to cux.
Move it somewhere on your PATH:
- Linux/macOS: ~/.local/bin/cux
- Windows: any directory listed in your Path environment variable.

After install

Run cux setup once. That installs the /switch and /cux:* slash commands plus the four Claude Code hooks. Restart Claude Code afterwards so it picks them up.

What works on which platform

	Linux	macOS	WSL / Git Bash	native Windows
Account commands (`add`, `list`, `switch`, `status`, …)	✅	✅	✅	✅
Credential storage	file (0600)	Keychain	file (0600)	Credential Manager
Hooks + `/switch` and `/cux:*` slash commands	✅	✅	✅	✅
Auto-resume on swap	✅	✅	✅	✅ †
`npm install -g @inulute/cux`	✅	✅	✅	✅
`curl … \| sh` shell installer	✅	✅	✅	❌
Manual binary download	✅	✅	✅	✅

† On native Windows the wrapper hard-terminates claude on swap (Go can't send SIGINT cross-process there). The Stop hook still flushes the transcript before the wrapper acts, so the resumed conversation is intact — but if you see anything unexpected, please open an issue.

Quick start

Website: https://cux.inulute.com

cux setup           # install /switch, /cux:* + Claude Code hooks
cux add             # register the currently-logged-in account
claude logout && claude login   # log into your second account
cux add             # register it
cux                 # launch claude under cux instead of `claude` directly

After cux setup, restart Claude Code so it picks up the newly installed hooks. From then on:

/switch from inside a Claude Code session rotates accounts.
/switch <slot|email> switches to a specific one.
/cux:add, /cux:list, /cux:status, /cux:config, /cux:remove, /cux:switch, /cux:usage-refresh, and /cux:support run account-management commands in-session.
A rate-limit response from the API auto-triggers the same flow and does not wait for another Stop hook before reconnecting.

Verify your setup once

A 30-second check that proves end-to-end context preservation:

Send: "Please remember the number 4729."
Wait for the reply.
Send /switch.
After the ~2-second reconnect, ask: "What number did I tell you to remember?"

If the answer is 4729, swap-and-resume is working.

How it works

   user types     ┌────── claude (running, account A) ──────┐
   /switch ──────►│  hooks: UserPromptSubmit, Stop,         │
   or rate-limit  │         SessionStart, PostToolUseFailure│
   ───────────────┴──┬──────────────────────────────────────┘
                     │ writes signal files
                     │ runtime/signals/{wrapperPID}-{name}
                     ▼
             ┌──────────────────────────────────────┐
             │  cux wrapper                         │  polls signals
             │   on rate-limit OR threshold OR      │  every 100 ms
             │   /switch:                           │
             │     rate-limit/manual: exit now      │  avoids hard-limit stall
             │     threshold: wait for Stop signal  │  guarantees flush
             │     ask claude to exit cleanly       │
             │     swap creds (transactional)       │
             │     append history.Entry             │
             │     relaunch claude --resume <id>    │
             │       [optional auto_message]        │
             └──────────────────────────────────────┘

cux writes its hooks into ~/.claude/settings.json by signature, so it never modifies entries owned by other tools and cux uninstall-hooks removes only its own. Every cux-owned file goes through atomic writes (tmp + fsync + rename) and state mutations are serialised with file locks (flock / LockFileEx).

Daily usage

cux                          # launch claude under the wrapper
cux list                     # accounts with 5h / 7d utilisation
cux list --refresh           # refresh usage before listing
cux status                   # current login + cux state
cux switch <slot|email>      # manual swap (no auto-resume)
cux remove <slot|email>      # forget an account
cux history                  # recent swaps with reasons
cux usage refresh            # poll all account usage
cux config show              # current settings
cux config edit              # interactive settings editor
cux upgrade                  # update cux (npm or installer; auto-detects)

From inside a session started with cux:

/switch                      # rotate per the configured strategy
/switch 2                    # by slot number
/switch alt@example.com      # by email
/cux:switch 2                # same switch flow under the /cux namespace
/cux:add                     # add/refresh the current login
/cux:list --refresh          # list accounts from inside Claude Code
/cux:status                  # show live login + cux state
/cux:support                 # show support URL
/cux:config show             # show cux configuration
/cux:remove 2                # remove an account
/cux:usage-refresh           # refresh account usage

If Claude is already hard-blocked, /switch is handled by cux's UserPromptSubmit hook before Claude processes the prompt. If you are on an older session that was started before that hook was installed, run this from another terminal:

cux force-switch             # rotate the active cux-wrapped session
cux force-switch 2           # force a specific slot/email

Configuration

cux config keys                                      # discover everything
cux config show
cux config set thresholds.five_hour 85
cux config set strategy.kind balanced
cux config set strategy.order alice@x,bob@x         # drain priority
cux config set auto_message ""                      # silent resume
cux config set update_check.enabled true            # opt in to update checks

Key	Default	Description
`thresholds.five_hour`	`100`	Auto-swap when 5h utilisation hits this %. `100` = reactive only.
`thresholds.seven_day`	`100`	Auto-swap when 7d utilisation hits this %. `100` = reactive only.
`strategy.kind`	`drain`	`drain` / `balanced` / `manual`
`strategy.order`	`[]`	Drain mode priority (emails); empty = auto by highest 7d
`auto_switch_on_threshold`	`true`	Master toggle for pre-emptive threshold swap
`auto_switch_on_rate_limit`	`true`	Master toggle for swap on rate-limit hook
`auto_resume`	`true`	Pass `--resume <id>` to the relaunched claude
`auto_message`	`Go continue.`	First user turn after auto-swap; `""` = silent
`update_check.enabled`	`false`	Check GitHub for newer cux releases on startup
`update_check.cadence_hours`	`6`	Minimum hours between update checks (cached locally)

Config file: ~/.config/cux/config.json (XDG-aware).

Strategies

drain — Use one account until its 7-day cap is near, then move on. Set order for explicit priority, or leave empty to auto-drain the highest-7d account first.
balanced — Always pick the account with the lowest 7-day utilisation (tiebreak by lowest 5h).
manual — Never swap automatically. /switch and cux switch still work.

Swap history

$ cux history
2026-05-01 14:12:33  alice@x → bob@x  [threshold]
    reason: 7d utilization 95% ≥ threshold 95%
    usage: alice@x 5h:34% 7d:95% → bob@x 5h:8% 7d:30%
    session: 143eec0f-277e-4ce1-95f1-58eb56331874

2026-05-01 13:55:08  bob@x → alice@x  [manual]
    reason: user requested via /switch

cux history -n 5 for the last five, cux history --json to pipe, cux history --clear to wipe. History is capped at 1000 entries.

Data layout

~/.local/share/cux/                  (~/.cux/ on macOS/Windows)
├── state.json                      # accounts, sequence, active slot
├── .lock                           # flock target for state mutations
├── accounts/
│   └── 01-user@example.com/
│       ├── credentials.json        # Linux only; macOS/Win uses keystore
│       └── oauth.json              # the oauthAccount block, raw JSON
└── runtime/
    ├── signals/                    # hook → wrapper signal files
    ├── usage-cache.json            # per-account 5h / 7d snapshot
    ├── update-cache.json           # update-check cadence cache
    └── swap-history.json           # capped at 1000 entries

~/.config/cux/config.json           # XDG_CONFIG_HOME-aware
~/.claude/settings.json             # hooks upserted here
~/.claude/commands/switch.md        # /switch slash command
~/.claude/commands/cux/*.md         # /cux:* account commands

Security

Tokens are never logged. Credential blobs are opaque to logging; the helper that extracts a token never surfaces it in any error message.
All cux-owned directories and files are 0700 / 0600.
The installer refuses to run as root unless inside a container.
/switch is gated by CUX_WRAPPED — the slash command refuses to act unless cux is the parent process, so it cannot accidentally signal an unrelated claude.
Hook upsert is signature-keyed. cux install-hooks only ever modifies entries whose command field contains the literal string cux or /cux — every other tool's hooks are preserved.

Building from source

git clone https://github.com/inulute/cux
cd cux
go build -o cux ./cmd/cux
./cux help

Requires Go 1.21+.

License

GPL-3.0-only. Modifying and redistributing cux is welcome; if you do, your changes need to ship under GPL-3.0 too.

Socials

All inulute social channels live at socials.inulute.com — one place for updates, other projects, and how to reach me.

If cux saves you time, you can support development at support.inulute.com.

Contents