claudex

First run

Admin setup, TOTP enrollment, recovery codes, and your first session.

The first time you open http://127.0.0.1:5179, claudex is a single locked door. There is no dev-mode backdoor and no anonymous access — the only way in is to finish initial setup.

Step 1 — create the admin user

You can do this interactively or non-interactively. Both flows print the TOTP secret and the recovery codes at the same point in the process; both flows persist the recovery codes only after you've had a chance to save them.

Interactive

pnpm run init

You'll be prompted for a username and a password (echoed as •). When the TOTP QR + recovery codes are printed, the prompt waits for you to press Enter — that's your cue to scan the QR and copy the codes before they're persisted.

Non-interactive (CI / scripts)

CLAUDEX_INIT_USERNAME=you \
CLAUDEX_INIT_PASSWORD='strong-pw' \
pnpm run init

Or pass --username= / --password= directly. With non-interactive stdin, the Enter confirmation is skipped, but print → flush → persist still happens in that order.

Step 2 — scan the TOTP QR

Open any TOTP app: 1Password, Authy, Aegis, Google Authenticator. Scan the ASCII-art QR printed in the terminal. The Issuer is claudex and the Account is your username.

printed in your terminal
Below the QR, the secret string is also printed for manual entry. Either path enrols the same TOTP key.
JBSWY3DPEHPK3PXP…

Step 3 — save your recovery codes

shown once. never again. Recovery codes are bcrypt-hashed before they hit disk. The plain codes are printed once and then are gone forever. Lose them along with your TOTP device and your only path back is to delete ~/.claudex/db.sqlite and start over.

A safe move: paste them into your password manager as a secure note titled claudex recovery, or print them to paper and tape them to the back of your monitor. Each code is single-use.

Step 4 — sign in

Open http://127.0.0.1:5179 on the same machine (or, after setting up remote access, on your phone).

  1. Enter your username + password.
  2. Enter the 6-digit TOTP code your authenticator shows.
  3. You land on the Home screen with an empty session list.

Step 5 — start your first session

Click + New session. Pick a project directory (claudex remembers your last few). If the directory is a git repo, the Use git worktree toggle is on by default — claudex will spawn a fresh claude/<slug> branch in an isolated worktree so this session can't step on others.

Type your first prompt. The Agent SDK starts the claude subprocess, and the WebSocket starts streaming structured events (tool calls, partial assistant messages, plan steps, permission asks). Welcome aboard.

Where to next