claudex

Installation

Pick your platform, run the installer, save your recovery codes.

Prerequisites

  • Node 20+ and pnpm 9+.
  • The claude CLI, installed and logged in.
  • Either git already on PATH, or willingness to let the installer offer to install it.

The installer probes for each prerequisite. Anything missing is a prompt — never silent, never automatic. sudo is opt-in.

One-liner

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/ahaostudy/claudex/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/ahaostudy/claudex/main/install.ps1 | iex

The installer:

  1. Checks for git / Node 20 / pnpm 9 / the claude CLI and offers to install anything missing.
  2. Clones the repo to ~/claudex (override with --dir PATH).
  3. Builds the web bundle.
  4. Walks you through first-admin setup (username + password → TOTP QR → 10 recovery codes).
  5. Offers to register claudex as a user-scoped daemon: launchd on macOS, systemd --user on Linux, pm2 on Windows.

Flags

Flag / env var Effect
--dir PATH · CLAUDEX_HOME Where to clone claudex. Default ~/claudex.
--branch NAME Pick a non-main branch (e.g. --branch=next).
--yes · CLAUDEX_ASSUME_YES=1 Accept default for every prompt. Useful for unattended installs.
--skip-init Don't run the first-admin walkthrough — you'll do it manually later.
--skip-build Don't build the web bundle. Run pnpm --filter @claudex/web build when you're ready.
--skip-daemon · CLAUDEX_SKIP_DAEMON=1 Don't register a daemon. You'll start the server manually.

Manual

git clone https://github.com/ahaostudy/claudex.git
cd claudex
pnpm install
pnpm run init --username=you --password='set-a-strong-one'

First-run init prints your TOTP secret (QR + manual string) and 10 recovery codes — shown once, never again. Save them. Scan the QR into any TOTP app (1Password, Authy, Aegis, Google Authenticator).

save the recovery codes The recovery codes are written to disk only as bcrypt hashes. The plain codes are printed once during pnpm run init and then they're gone forever. If you lose both your TOTP device and your codes, you'll need to wipe ~/.claudex/db.sqlite and re-init.

Run

Foreground (development)

pnpm serve        # build + start server on 127.0.0.1:5179

Open http://127.0.0.1:5179 in any browser on the same machine. For phone access, see Remote access.

Background (daemon)

If you opted out of the daemon prompt during install, register it now:

macOS
launchctl bootstrap \
  gui/$(id -u) \
  ~/Library/LaunchAgents/\
com.claudex.server.plist
Linux
systemctl --user \
  enable --now \
  claudex.service
Windows
pm2 start ecosystem.config.cjs
pm2 save
pm2-startup install

What's next