Skip to content
Back to search

cux

Run multiple Claude Code accounts as one. Auto-switches on rate limits and resumes your session no lost context, no logout dance.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/inulute--cux/badge.svg)](/listings/inulute--cux)

HTML

<a href="/listings/inulute--cux"><img src="/api/listings/inulute--cux/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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](https://github.com/inulute/cux/releases): - `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 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](https://github.com/inulute/cux/issues).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 460 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="./assets/cux-banner.webp" alt="cux — Run multiple Claude Code Pro/Max accounts as one" width="100%">
  3. </p>
  4. <p align="center">
  5. Claude Code account switcher for uninterrupted sessions.
  6. </p>
  7. <p align="center">
  8. <a href="https://github.com/inulute/cux/releases/latest">
  9. <img alt="latest release"
  10. src="https://img.shields.io/github/v/release/inulute/cux?style=for-the-badge&label=Release&color=c8763a&labelColor=0e1116&logo=github&logoColor=f0ead6">
  11. </a>
  12. &nbsp;
  13. <a href="https://www.npmjs.com/package/@inulute/cux">
  14. <img alt="npm version"
  15. src="https://img.shields.io/npm/v/@inulute/cux?style=for-the-badge&label=npm&color=c8763a&labelColor=0e1116&logo=npm&logoColor=f0ead6">
  16. </a>
  17. &nbsp;
  18. <a href="https://github.com/inulute/cux/blob/main/LICENSE">
  19. <img alt="license"
  20. src="https://img.shields.io/badge/License-GPL--3.0-c8763a?style=for-the-badge&labelColor=0e1116&logo=gnu&logoColor=f0ead6">
  21. </a>
  22. &nbsp;
  23. <a href="https://support.inulute.com">
  24. <img alt="support"
  25. src="https://img.shields.io/badge/Support-%E2%99%A5-c8763a?style=for-the-badge&labelColor=0e1116&logo=githubsponsors&logoColor=f0ead6">
  26. </a>
  27. &nbsp;
  28. <a href="https://cux.inulute.com/docs">
  29. <img alt="docs"
  30. src="https://img.shields.io/badge/Docs-cux.inulute.com-c8763a?style=for-the-badge&labelColor=0e1116&logo=readthedocs&logoColor=f0ead6">
  31. </a>
  32. </p>
  33. ---
  34. **`cux`** is a CLI tool for Claude Code that pools multiple Pro/Max
  35. accounts behind a single live session. When the active account hits
  36. a rate limit, `cux` switches to a healthy account and continues the
  37. same conversation. For proactive threshold swaps, it waits for the
  38. current turn to finish first. No logout, no reload, no lost context.
  39. ```text
  40. $ cux
  41. cux: rate limit on alice@example.com → swapped to bob@example.com, resuming…
  42. > What number did I tell you to remember?
  43. 4729.
  44. ```
  45. ---
  46. ## Contents
  47. - [Install](#install)
  48. - [Option 1 — npm](#option-1--npm)
  49. - [Option 2 — shell installer](#option-2--shell-installer)
  50. - [Option 3 — manual binary](#option-3--manual-binary)
  51. - [After install](#after-install)
  52. - [What works on which platform](#what-works-on-which-platform)
  53. - [Quick start](#quick-start)
  54. - [Verify your setup once](#verify-your-setup-once)
  55. - [How it works](#how-it-works)
  56. - [Daily usage](#daily-usage)
  57. - [Watch & attach to running sessions](#watch--attach-to-running-sessions)
  58. - [Configuration](#configuration)
  59. - [Strategies](#strategies)
  60. - [Swap history](#swap-history)
  61. - [Data layout](#data-layout)
  62. - [Security](#security)
  63. - [Building from source](#building-from-source)
  64. - [License](#license)
  65. - [Socials](#socials)
  66. ## Install
  67. Three install methods. Pick the one that fits your platform — they
  68. all install the same `cux` binary.
  69. ### Option 1 — npm
  70. Works on Linux, macOS and Windows. Requires Node.js 18 or newer.
  71. ```bash
  72. npm install -g @inulute/cux
  73. ```
  74. ### Option 2 — shell installer
  75. Works on Linux, macOS, WSL and Git Bash on Windows.
  76. ```bash
  77. curl -fsSL https://raw.githubusercontent.com/inulute/cux/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 94 on GitHub
  78. ```
  79. ### Option 3 — manual binary
  80. Works everywhere. Useful if you don't want Node.js and can't run
  81. shell scripts (e.g. native Windows PowerShell or cmd.exe).
  82. 1. Download the matching artefact from the
  83. [releases page](https://github.com/inulute/cux/releases):
  84. - `cux-linux-amd64`, `cux-linux-arm64`
  85. - `cux-darwin-amd64`, `cux-darwin-arm64`
  86. - `cux-windows-amd64.exe`
  87. 2. On Linux/macOS, `chmod +x cux-<os>-<arch>` and rename to `cux`.
  88. 3. Move it somewhere on your `PATH`:
  89. - Linux/macOS: `~/.local/bin/cux`
  90. - Windows: any directory listed in your `Path` environment variable.
  91. ### After install
  92. Run `cux setup` once. That installs the `/switch` and `/cux:*` slash
  93. commands plus the four Claude Code hooks. Restart Claude Code
  94. afterwards so it picks them up.
  95. ### What works on which platform
  96. | | Linux | macOS | WSL / Git Bash | native Windows |
  97. |---|:---:|:---:|:---:|:---:|
  98. | Account commands (`add`, `list`, `switch`, `status`, …) | ✅ | ✅ | ✅ | ✅ |
  99. | Credential storage | file (0600) | Keychain | file (0600) | Credential Manager |
  100. | Hooks + `/switch` and `/cux:*` slash commands | ✅ | ✅ | ✅ | ✅ |
  101. | Auto-resume on swap | ✅ | ✅ | ✅ | ✅ † |
  102. | `npm install -g @inulute/cux` | ✅ | ✅ | ✅ | ✅ |
  103. | `curl … \| sh` shell installer | ✅ | ✅ | ✅ | ❌ |
  104. | Manual binary download | ✅ | ✅ | ✅ | ✅ |
  105. † On native Windows the wrapper hard-terminates `claude` on swap (Go
  106. can't send `SIGINT` cross-process there). The `Stop` hook still
  107. flushes the transcript before the wrapper acts, so the resumed
  108. conversation is intact — but if you see anything unexpected, please
  109. [open an issue](https://github.com/inulute/cux/issues).
  110. ## Quick start
  111. Website: https://cux.inulute.com
  112. ```bash
  113. cux setup # install /switch, /cux:* + Claude Code hooks
  114. cux add # register the currently-logged-in account
  115. claude login # log into your second account — just log in again, no logout
  116. cux add # register it
  117. cux # launch claude under cux instead of `claude` directly
  118. ```
  119. > **Don't run `claude logout` to switch accounts.** `claude login` on its
  120. > own re-authenticates and replaces the active credentials — that's all
  121. > cux needs to capture the next account. `claude logout` *clears and
  122. > revokes* the stored token, which invalidates the backup cux keeps for
  123. > that account (it will show up as `EXPRD` in `cux list`). Once both
  124. > accounts are added, let cux do all switching — it swaps credentials
  125. > directly and never logs out, so nothing gets revoked.
  126. After `cux setup`, restart Claude Code so it picks up the newly
  127. installed hooks. From then on:
  128. - `/switch` from inside a Claude Code session rotates accounts.
  129. - `/switch <slot|email>` switches to a specific one.
  130. - `/cux:add`, `/cux:list`, `/cux:status`, `/cux:config`, `/cux:remove`,
  131. `/cux:switch`, `/cux:usage-refresh`, and `/cux:support` run
  132. account-management commands in-session.
  133. - A rate-limit response from the API auto-triggers the same flow and
  134. does not wait for another Stop hook before reconnecting.
  135. ### Verify your setup once
  136. A 30-second check that proves end-to-end context preservation:
  137. 1. Send: *"Please remember the number 4729."*
  138. 2. Wait for the reply.
  139. 3. Send `/switch`.
  140. 4. After the ~2-second reconnect, ask: *"What number did I tell you to remember?"*
  141. If the answer is `4729`, swap-and-resume is working.
  142. ## How it works
  143. ```
  144. user types ┌────── claude (running, account A) ──────┐
  145. /switch ──────►│ hooks: UserPromptSubmit, Stop, │
  146. or rate-limit │ SessionStart, PostToolUseFailure│
  147. ───────────────┴──┬──────────────────────────────────────┘
  148. │ writes signal files
  149. │ runtime/signals/{wrapperPID}-{name}
  150. ▼
  151. ┌──────────────────────────────────────┐
  152. │ cux wrapper │ polls signals
  153. │ on rate-limit OR threshold OR │ every 100 ms
  154. │ /switch: │
  155. │ rate-limit/manual: exit now │ avoids hard-limit stall
  156. │ threshold: wait for Stop signal │ guarantees flush
  157. │ ask claude to exit cleanly │
  158. │ swap creds (transactional) │
  159. │ append history.Entry │
  160. │ relaunch claude <orig. flags> │
  161. │ --resume <id> [auto_message] │
  162. └──────────────────────────────────────┘
  163. ```
  164. `cux` writes its hooks into `~/.claude/settings.json` by signature,
  165. so it never modifies entries owned by other tools and
  166. `cux uninstall-hooks` removes only its own. Every cux-owned file goes
  167. through atomic writes (`tmp + fsync + rename`) and state mutations
  168. are serialised with file locks (`flock` / `LockFileEx`).
  169. ## Daily usage
  170. ```bash
  171. cux # launch claude under the wrapper
  172. cux list # accounts with 5h / 7d utilisation
  173. cux list --refresh # refresh usage before listing
  174. cux status # current login + cux state
  175. cux switch <slot|email> # manual swap (no auto-resume)
  176. cux remove <slot|email> # forget an account
  177. cux history # recent swaps with reasons
  178. cux sessions # running sessions, plus recently ended ones and how to resume them
  179. cux attach [pid] # attach to a running session — watch and control it
  180. cux usage refresh # poll all account usage
  181. cux config show # current settings
  182. cux config edit # interactive settings editor
  183. cux upgrade # update cux (npm or installer; auto-detects)
  184. ```
  185. From inside a session started with `cux`:
  186. ```text
  187. /switch # rotate per the configured strategy
  188. /switch 2 # by slot number
  189. /switch alt@example.com # by email
  190. /cux:switch 2 # same switch flow under the /cux namespace
  191. /cux:add # add/refresh the current login
  192. /cux:list --refresh # list accounts from inside Claude Code
  193. /cux:status # show live login + cux state
  194. /cux:support # show support URL
  195. /cux:config show # show cux configuration
  196. /cux:remove 2 # remove an account
  197. /cux:usage-refresh # refresh account usage
  198. ```
  199. If Claude is already hard-blocked, `/switch` is handled by cux's
  200. `UserPromptSubmit` hook before Claude processes the prompt. If you are
  201. on an older session that was started before that hook was installed,
  202. run this from another terminal:
  203. ```bash
  204. cux force-switch # rotate the active cux-wrapped session
  205. cux force-switch 2 # force a specific slot/email
  206. ```
  207. ### Watch & attach to running sessions
  208. `cux sessions` lists every running cux session on the machine — the ones
  209. you started in other terminals or left running overnight:
  210. ```text
  211. $ cux sessions
  212. [73820] review the pull request and tell me if its safe…
  213. /Users/you/code/app
  214. seat you@example.com session 1634fada running
  215. up 6h 12m, last change 0m ago
  216. Recently ended:
  217. fix the flaky integration test on CI…
  218. /Users/you/code/api · seat you@example.com · ended 2h 4m ago
  219. cux --resume 8f31c0a2-5d77-4c1e-9b0e-2a61d4e0c8bb
  220. ```
  221. Claude Code shows a session ID only inside its running UI, so a session
  222. that ends when you were not looking — a crash, a closed tab, a machine
  223. that rebooted — used to take the way back with it. cux keeps a record of
  224. each ended session for 30 days, so the resume line is always somewhere
  225. other than your scrollback.
  226. `cux attach [pid]` connects your terminal to one of them, tmux-style —
  227. you see its live output and can type into it (Ctrl+C, everything). With
  228. no pid it attaches to the only session, or shows a picker when several
  229. are running. Detach with `Ctrl+\` and the session keeps running.
  230. Multiple terminals can attach to the same session at once. Requires a
  231. session started with a build that has attach support (the wrapper serves
  232. the mirror over a local socket).
  233. ## Configuration
  234. ```bash
  235. cux config keys # discover everything
  236. cux config show
  237. cux config set thresholds.five_hour 85
  238. cux config set strategy.kind balanced
  239. cux config set strategy.order alice@x,bob@x # drain priority
  240. cux config set auto_message "" # silent resume
  241. cux config set model_fallback opus,sonnet # model cap? change model, keep the seat
  242. cux config set update_check.enabled true # opt in to update checks
  243. ```
  244. | Key | Default | Description |
  245. |---|---|---|
  246. | `thresholds.five_hour` | `100` | Auto-swap when 5h utilisation hits this %. `100` = reactive only. |
  247. | `thresholds.seven_day` | `100` | Auto-swap when 7d utilisation hits this %. `100` = reactive only. |
  248. | `strategy.kind` | `drain` | `drain` / `balanced` / `manual` |
  249. | `strategy.order` | `[]` | Drain mode priority (emails); empty = auto by highest 7d |
  250. | `auto_switch_on_threshold` | `true` | Master toggle for pre-emptive threshold swap |
  251. | `auto_switch_on_rate_limit` | `true` | Master toggle for swap on rate-limit hook |
  252. | `model_fallback` | `[]` | On a *model-specific* cap ("You've reached your Opus limit"), try these models in order on the same account before rotating to another one. Empty = always rotate the account. |
  253. | `poll_interval_seconds` | `60` | How often a quiet session re-checks its seat against the shared usage cache. Evaluation only — it does not change how often cux calls the usage API. |
  254. | `auto_swap_idle_after_seconds`| `900` | Migrate a session idle this long off an over-threshold account, instead of waiting for you to come back and type. `0` = off. Needs `auto_resume`. |
  255. | `auto_resume` | `true` | Pass `--resume <id>` to the relaunched claude |
  256. | `auto_message` | `Go continue.` | First user turn after auto-swap; `""` = silent |
  257. | `wait_for_reset` | `true` | When every account is exhausted and nobody is at the session, sleep until the earliest reset and resume. A session you are sitting at is kept open instead — claude keeps running and picks up the next free seat when you type. |
  258. | `retry_on_api_error` | `true` | Relaunch and auto-continue after a non-rate-limit API failure (fibonacci backoff, capped at 2 min) |
  259. | `update_check.enabled` | `false` | Check GitHub for newer cux releases on startup |
  260. | `update_check.cadence_hours` | `6` | Minimum hours between update checks (cached locally) |
  261. Config file: `~/.config/cux/config.json` (XDG-aware).
  262. ### Strategies
  263. - **drain** — Use one account until its 7-day cap is near, then move
  264. on. Set `order` for explicit priority, or leave empty to auto-drain
  265. the highest-7d account first.
  266. - **balanced** — Always pick the account with the lowest 7-day
  267. utilisation (tiebreak by lowest 5h).
  268. - **manual** — Never swap automatically. `/switch` and `cux switch`
  269. still work.
  270. Both automatic strategies also prefer accounts whose model-specific
  271. weekly windows (Opus/Sonnet, reported on some plans) still have room.
  272. A model-capped account is never made ineligible — cux cannot know
  273. which model the session will ask for next — it just sorts behind
  274. model-clear candidates, so a heavy-Opus session is not swapped onto a
  275. seat that would rate-limit its very next call.
  276. ## Projects
  277. A machine that hosts several codebases often wants them on different
  278. seats — one client's work billed to their org, a personal side project
  279. kept off the company pool — while related projects share accounts.
  280. Projects bind a directory to a subset of seats:
  281. ```bash
  282. cux project create clientwork --dir ~/code/client
  283. cux project assign clientwork 1 2 # seats by slot, email, or alias
  284. cux project create side --dir ~/code/side
  285. cux project assign side 2 3 # seat 2 is shared between both
  286. cux project list --refresh # projects + live usage per seat
  287. cux project unassign side 3
  288. cux project stats clientwork --days 7 # tokens & time from Claude Code transcripts
  289. cux project remove side # unbind only; accounts untouched
  290. ```
  291. When cux starts, the working directory picks the project (longest,
  292. path-boundary-aware match — nested projects work) and every automatic
  293. decision draws from that project's seats only: threshold and
  294. rate-limit swaps, rotation, and `wait_for_reset`'s availability math.
  295. - **No projects, or an unclaimed directory** → the full pool. Existing
  296. setups behave exactly as before.
  297. - **A project with no seats assigned yet** → the full pool, until you
  298. assign some.
  299. - **Explicit targets are never restricted** — `/switch <seat>` and
  300. `cux switch <seat>` go wherever you point them; a human naming a
  301. seat outranks the project boundary.
  302. - Removing an account (`cux remove`) also removes it from every
  303. project pool.
  304. `cux project stats` reads the session transcripts Claude Code already
  305. writes under `~/.claude/projects` — cux collects nothing itself — and
  306. sums sessions, active time, turns, and input/output/cache tokens for
  307. the project's directory tree, optionally windowed with `--days N`.
  308. ## Swap history
  309. ```text
  310. $ cux history
  311. 2026-05-01 14:12:33 alice@x → bob@x [threshold]
  312. reason: 7d utilization 95% ≥ threshold 95%
  313. usage: alice@x 5h:34% 7d:95% → bob@x 5h:8% 7d:30%
  314. session: 143eec0f-277e-4ce1-95f1-58eb56331874
  315. 2026-05-01 13:55:08 bob@x → alice@x [manual]
  316. reason: user requested via /switch
  317. ```
  318. `cux history -n 5` for the last five, `cux history --json` to pipe,
  319. `cux history --clear` to wipe. History is capped at 1000 entries.
  320. ## Data layout
  321. ```
  322. ~/.local/share/cux/ (~/.cux/ on macOS/Windows)
  323. ├── state.json # accounts, sequence, active slot
  324. ├── .lock # flock target for state mutations
  325. ├── accounts/
  326. │ └── 01-user@example.com/
  327. │ ├── credentials.json # Linux only; macOS/Win uses keystore
  328. │ └── oauth.json # the oauthAccount block, raw JSON
  329. └── runtime/
  330. ├── signals/ # hook → wrapper signal files
  331. ├── usage-cache.json # per-account 5h / 7d snapshot
  332. ├── update-cache.json # update-check cadence cache
  333. └── swap-history.json # capped at 1000 entries
  334. ~/.config/cux/config.json # XDG_CONFIG_HOME-aware
  335. ~/.claude/settings.json # hooks upserted here
  336. ~/.claude/commands/switch.md # /switch slash command
  337. ~/.claude/commands/cux/*.md # /cux:* account commands
  338. ```
  339. ## Security
  340. - **Tokens are never logged.** Credential blobs are opaque to
  341. logging; the helper that extracts a token never surfaces it in any
  342. error message.
  343. - **All cux-owned directories and files are 0700 / 0600.**
  344. - **The installer refuses to run as root** unless inside a container.
  345. - **`/switch` is gated by `CUX_WRAPPED`** — the slash command refuses
  346. to act unless cux is the parent process, so it cannot accidentally
  347. signal an unrelated `claude`.
  348. - **Hook upsert is signature-keyed.** `cux install-hooks` only ever
  349. modifies entries whose `command` field contains the literal string
  350. `cux ` or `/cux ` — every other tool's hooks are preserved.
  351. - **`cux attach` exposes a local control socket.** A session's mirror
  352. lives at `~/.cux/runtime/attach/<pid>.sock` (mode 0600 — your user
  353. only). Anything that can read it can control that session's terminal.
  354. Third-party tools that bridge this socket beyond your machine (tunnels,
  355. remote dashboards) are **outside cux's trust boundary** — review them
  356. before use. cux itself ships no such bridge.
  357. ## Building from source
  358. ```bash
  359. git clone https://github.com/inulute/cux
  360. cd cux
  361. go build -o cux ./cmd/cux
  362. ./cux help
  363. ```
  364. Requires Go 1.21+.
  365. `go test ./...` is safe to run next to a real cux setup: the suite
  366. redirects HOME/XDG into temp dirs and forces the file credential
  367. backend (`CUX_CREDS_BACKEND=file`), so it never touches your actual
  368. state, usage cache, or OS keychain.
  369. ## License
  370. [GPL-3.0-only](./LICENSE). Modifying and redistributing `cux` is
  371. welcome; if you do, your changes need to ship under GPL-3.0 too.
  372. ## Socials
  373. All inulute social channels live at
  374. **[socials.inulute.com](https://socials.inulute.com)** — one place
  375. for updates, other projects, and how to reach me.
  376. ---
  377. If `cux` saves you time, you can support development at
  378. [support.inulute.com](https://support.inulute.com).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.