# cux

> cux pools your Claude Code Pro/Max accounts behind a single live session. When the active account hits a rate limit, cux auto-switches to a healthy account and continues the same conversation — no logout, no reload, no lost context.

cux is a free, open-source CLI wrapper for Anthropic's Claude Code. It solves the rate-limit problem for power users who run multiple Claude Code accounts by transparently rotating credentials mid-session.

- Install: `npm install -g @inulute/cux`
- Homepage: https://cux.inulute.com
- Source: https://github.com/inulute/cux
- npm: https://www.npmjs.com/package/@inulute/cux
- Author: inulute (https://inulute.com)
- License: open-source

## Installation

Three install methods are available:

### npm (Node 18+, Linux · macOS · Windows)
```
npm install -g @inulute/cux
```

### Shell installer (Linux · macOS · WSL · Git Bash)
```
curl -fsSL https://raw.githubusercontent.com/inulute/cux/main/scripts/install.sh | sh
```

### Manual binary (all platforms, no Node required)
Download `cux-<os>-<arch>` from the releases page, then:
```
chmod +x cux-darwin-arm64 && mv cux-darwin-arm64 ~/.local/bin/cux
```

### After install (required)
1. Run `cux setup` — interactive account setup
2. Restart Claude Code — hooks take effect
3. Verify: send "Remember 4729", then `/switch`, then ask "What number?" — if the answer is 4729, swap-and-resume is working.

## Platform support

| Platform | Auto-swap | Slash commands | Hooks |
|----------|-----------|----------------|-------|
| Linux    | ✓         | ✓              | ✓     |
| macOS    | ✓         | ✓              | ✓     |
| WSL      | ✓         | ✓              | ✓     |
| Windows  | ✓ (limited)| ✓             | partial |

## CLI commands

| Command | Description |
|---------|-------------|
| `cux` | Launch Claude under the cux wrapper |
| `cux list` | Show 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 history` | Recent swaps with reasons and usage |
| `cux config show` | View current settings |
| `cux config edit` | Interactive settings editor |
| `cux config set <key> <value>` | Set a config value |
| `cux upgrade` | Update cux (auto-detects npm or installer) |

## Slash commands (inside Claude Code)

| Command | Description |
|---------|-------------|
| `/switch` | Rotate per the configured strategy |
| `/switch 2` | Switch to slot 2 |
| `/switch alt@example.com` | Switch to a specific account |
| `/cux:add` | Add / refresh the current login |
| `/cux:list --refresh` | List accounts from inside Claude Code |
| `/cux:status` | Show live login + cux state |
| `/cux:config show` | Show cux configuration |
| `/cux:remove 2` | Remove account at slot 2 |
| `/cux:usage-refresh` | Refresh account usage |

## Configuration

Config file location: `~/.config/cux/config.json`

| Key | Default | Description |
|-----|---------|-------------|
| `thresholds.five_hour` | 90 | Auto-swap when 5h utilisation hits this %. 100 = reactive only. |
| `thresholds.seven_day` | 95 | Auto-swap when 7d utilisation hits this %. 100 = reactive only. |
| `strategy.kind` | drain | Swap strategy: 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 |

### Strategies

- **drain** — Use one account until its 7-day cap is near, then move on. Set `strategy.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.

### Quick config examples
```
cux config set thresholds.five_hour 85
cux config set strategy.kind balanced
cux config set auto_message ""
```

## How it works (architecture)

Hooks write signal files. The cux wrapper polls them every 100ms, waits for a clean exit when needed, swaps credentials transactionally, and relaunches `claude` with `--resume` on the same session id.

- **Atomic writes** — every state file goes through tmp + fsync + rename
- **File locks** — flock / LockFileEx serialise concurrent access
- **Signature-keyed hooks** — cux only modifies Claude Code hook entries whose command field contains `cux` or `/cux`; it never touches user hooks