claude-mobile

Remote control Claude Code from your phone. One CLI ships both halves of the system:

• agent — runs on the machine where Claude Code lives, bridges it to your phone.
• relay — an optional WebSocket proxy server for connecting over the internet / through NAT.

Install

Run on demand with npx (no install):

npx claude-mobile agent

Or install globally:

npm install -g claude-mobile

Usage

claude-mobile <command> [options]

agent — bridge Claude Code to your phone

claude-mobile agent [options]

| Option | Description | Default | | --- | --- | --- | | -m, --mode <mode> | Connection mode: lan (direct) or relay | lan | | -r, --relay <url> | Relay server URL (relay mode) | from config | | -p, --port <port> | Port to listen on (lan mode) | 9210 | | -w, --workspace <path> | Workspace directory (subdirectories = projects) | current dir |

Scan the printed QR code from the mobile app to pair.

relay — run the proxy server

Use this when the phone and the agent are not on the same LAN. Deploy it on a host with a public address (or run locally for testing).

claude-mobile relay [options]

| Option | Description | Default | | --- | --- | --- | | -p, --port <port> | Port to listen on | 9210 | | --public-url <url> | Public WebSocket URL advertised to clients (e.g. wss://relay.example.com) | $RELAY_PUBLIC_URL |

Health check: GET /health returns {"status":"ok", ...}.

Then point the agent at it:

claude-mobile agent --mode relay --relay wss://relay.example.com

License

MIT