cux

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 [email protected] → swapped to [email protected], resuming…
> What number did I tell you to remember?
4729.

Contents

• Contents
• Install
  • Option 1 — npm
  • Option 2 — shell installer
  • Option 3 — manual binary
  • After install
  • What works on which platform
• Quick start
  • Verify your setup once
• How it works
• Daily usage
• Configuration
  • Strategies
• Swap history
• Data layout
• Security
• Building from source
• License
• Socials

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).

1. Download the matching artefact from the
   releases page:
   • cux-linux-amd64, cux-linux-arm64
   • cux-darwin-amd64, cux-darwin-arm64
   • cux-windows-amd64.exe
2. On Linux/macOS, chmod +x cux-<os>-<arch> and rename to cux.
3. 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 three Claude Code hooks. Restart Claude Code
afterwards so it picks them up.

What works on which platform

† 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:support,
  /cux:remove, and /cux:switch, /cux:config, /cux:usage-refresh 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:

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

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 [email protected]      # 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

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/
│   └── [email protected]/
│       ├── 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.