claudex

Introduction

What claudex is, what it isn't, and when you'd want it.

claudex is a remote control for the claude CLI on your own machine. It runs a small self-hosted service that exposes a polished browser interface — designed mobile-first — and drives the real claude CLI as a subprocess via the Agent SDK.

That means everything you've already configured for the CLI — ~/.claude/ config, MCP servers, plugins, skills, your CLAUDE.md files, your OAuth token or API key — is inherited automatically. claudex never touches Anthropic's API directly. It is the driver, never the agent.

What claudex is

  • A self-hosted browser cockpit for a long-running Claude Code session.
  • Designed mobile-first: 390 px viewport is the home turf, desktop is an adaptive expansion.
  • Auth from day one — username + password + TOTP, with one-shot recovery codes.
  • Stateful: SQLite under ~/.claudex/, so a server restart never loses your transcripts.
  • Honest: no fake streaming, no fabricated progress bars, no telemetry, no analytics.

What claudex isn't

  • Not a hosted service. You run it on your own laptop, NAS, or VPS. We don't run it for you.
  • Not a re-implementation of Claude Code. We spawn the CLI; we don't reach for the Anthropic SDK.
  • Not internet-facing by default. The server refuses to bind anything other than 127.0.0.1.
  • Not telemetry-bearing. Zero outbound traffic from claudex itself.

When you'd want it

A few patterns that come up often:

scenario
Approve a permission while waiting for coffee.
A long refactor pings you for a write. Phone in hand, one tap to allow.
scenario
Queue prompts from the train.
Batch the next three prompts, send them to claude, then close the tab.
scenario
Review a diff at midnight.
File-by-file diffs render the same on phone and desktop, with inline comments either way.

How it fits together

┌────────────────┐    HTTPS via your tunnel    ┌──────────────────────────────────────────┐
│ phone · laptop │ ────────────────────────▶   │ claudex server (127.0.0.1:5179)          │
│   browser UI   │ ◀────────────────────────   │ Fastify · SQLite · WebSocket             │
└────────────────┘     JWT + TOTP gate         │                                          │
                                               │   spawns as subprocess ▼                 │
                                               │  ┌────────────────────────────────────┐  │
                                               │  │   claude CLI                       │  │
                                               │  │   @anthropic-ai/claude-agent-sdk   │  │
                                               │  │   · ~/.claude/ config              │  │
                                               │  │   · MCP servers, skills, plugins   │  │
                                               │  │   · your API creds / OAuth token   │  │
                                               │  └──────────────┬─────────────────────┘  │
                                               └─────────────────┼────────────────────────┘
                                                                 ▼
                                                       api.anthropic.com

The only outbound connection beyond your tunnel is the one the claude CLI already made before you installed claudex.

Where to next