cc-walkie

Remote control Claude Code from your phone. One CLI ships everything:

• pair — interactive one-shot: prints a QR code and saves the pairing token.
• server — long-running bridge between Claude Code and your phone. Daemonizes by default.
• config — manage the connection mode, port, and other settings.
• relay — optional WebSocket proxy server for connecting over the internet / through NAT.

Install

Run on demand with npx (no install):

npx cc-walkie pair

Or install globally:

npm install -g cc-walkie

Quick start

cc-walkie config set workspace ~/codes      # where your projects live
cc-walkie pair                              # prints QR; scan with the phone app
# (the server daemon auto-starts after pairing)
cc-walkie logs -f                           # watch what's happening

After the first pair, the server keeps running in the background and the phone reconnects automatically every time it sees a familiar token. You only need pair again when re-pairing a different device.

Usage

cc-walkie <command> [options]

pair — pair a phone with this CLI

cc-walkie pair [options]

Starts a short-lived pairing endpoint (LAN server or relay registration), prints a QR for the phone to scan, persists the resulting permanentToken to ~/.cc-walkie/config.json, then automatically launches the server daemon unless --no-start is given. Re-running pair while a server daemon is running stops the daemon first to avoid port/room contention.

| Option | Description | Default | | --- | --- | --- | | -m, --mode <mode> | Connection mode: lan (direct) or relay | from config (fallback 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) | from config / cwd | | --no-start | Don't auto-launch the server after pairing | off |

server — run the bridge

cc-walkie server [options]

Reads the permanentToken from config and serves the paired device. Defaults to detaching into the background (PID + log under ~/.cc-walkie/). Pass -f to keep it in the foreground for debugging or systemd-style supervision.

| Option | Description | Default | | --- | --- | --- | | -f, --foreground | Stay in the foreground instead of daemonizing | off | | -m, --mode <mode> | Override the connection mode | from config | | -r, --relay <url> | Override the relay URL | from config | | -p, --port <port> | Override the LAN port | from config / 9210 | | -w, --workspace <path> | Override the workspace directory | from config |

If no pairing has happened yet, server exits with Not paired yet. Run: cc-walkie pair. A second background server while one is already alive is refused — use restart instead.

config — manage settings

cc-walkie config show
cc-walkie config set <key> <value>

Settable keys: mode (lan | relay), relayUrl (ws[s]://…), port (1-65535), workspace (path). show prints the current config with the permanentToken redacted.

stop / restart — manage the background server

cc-walkie stop        # SIGTERM the daemon (SIGKILL fallback), clean up the pid file
cc-walkie restart     # stop, then re-launch using the previously-recorded options

logs — view the background server log

cc-walkie logs [options]

| Option | Description | Default | | --- | --- | --- | | -f, --follow | Follow the log output (like tail -f) | off | | -n, --lines <n> | Number of trailing lines to show | 200 |

relay — run the proxy server

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

cc-walkie 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 CLI at it:

cc-walkie config set mode relay
cc-walkie config set relayUrl wss://relay.example.com
cc-walkie pair

License

MIT