Use ccdeck from a terminal or over SSH

Before you start

• A terminal on the machine where Claude Code runs, at the machine or over SSH, with Node.js 18 or newer for npx.
• ccdeck 3.48.0 or newer running there: signing in and Auto-switch go through it. npx ccdeck starts it.

Steps

1. Open the accounts screen

   Run npx ccdeck tui in the terminal. It fills the screen and stays up until you press q.

   Accounts lists each Claude account with its 5-hour and 7-day use and when each resets: ● marks the one in use, ⌂ Auto-switch’s home account. Under it, Waiting on you lists the sessions stopped on a permission prompt or a question, with the question. Press ? for every key.

   More about the screen

   It reads the accounts and sessions again every few seconds. It needs at least 40 columns and 12 rows, and from 120 columns the selected account’s detail sits beside the waiting sessions. It follows NO_COLOR, and draws in plain characters where the console cannot show its lines.

   With no deck running it reads claude-swap’s store, says so at the top right, and d starts a deck in the background. It does not start, resume or stop agents.

2. Switch to another account

   Move with ↑ and ↓, or the account’s slot number, then press Enter. Every running Claude Code session uses the new account from its next message, and the line above the keys says how many moved.

   Press b to select the account Auto-switch would pick, then Enter to switch to it.

   On an account whose login expired, Enter signs it in again instead of switching (step 4).

3. Turn Auto-switch on or off

   Press a. The bottom edge of the Accounts box says Auto-switch on, with its threshold and next-account rule, or Auto-switch off.

   The home account and the rule are set in the deck, as in Use your main Claude Code account first.

   Auto-switch runs inside the deck. With none running, press d first.

4. Sign an account in from any browser

   Press + to add an account, or Enter on one whose login expired, then Enter again for the sign-in link.

   Open the link in any browser, your own computer’s included, and approve. The page then shows a code: paste it into the terminal and press Enter. The account you are using stays active.

   Sign-in goes through the deck, so it needs one running. In a browser on the same machine, it finishes without a code.

5. Or ask with one command

   Each prints its answer and exits:

   • npx ccdeck accounts lists your Claude accounts with their 5-hour and 7-day use.
   • npx ccdeck switch work switches to the account with that slot number, e-mail or alias, or a part of one that names one account. With no account named, it shows a list to pick from.
   • npx ccdeck switch --best goes where Auto-switch would.
   • npx ccdeck usage shows every limit of the account in use.
   • npx ccdeck sessions lists what each Claude Code and Codex session is doing, the ones waiting on you first.
   More about the commands

   They ask the deck that is running, so a switch takes the same route as Switch in the Claude accounts panel. With no deck, accounts, switch and usage read and drive claude-swap’s store; sessions and open need a deck. status, stop and logs are --status, --stop and --logs.

   Every command but tui takes --json for a script, and every one takes --port to name a deck. They exit 0 when done, 1 on a failure, 2 when the command line was wrong and 3 when no deck is running. A misspelled command is refused and starts nothing.

6. Open the deck in your own browser

   Over SSH, npx ccdeck open opens nothing there and prints an ssh -N … -L 14317:127.0.0.1:4317 … line instead. Run that line on your own computer and keep it open, then open the address it prints: http://127.0.0.1:14317 for a deck on 4317.

   The deck still listens only on that machine’s 127.0.0.1: the tunnel is your SSH connection. Your end is not 4317, so it never lands on a deck of your own.

If something goes wrong

Something else? See Troubleshoot ccdeck: status, logs, port and hooks.