@akshaymemane/remote-cli

Control Claude Code sessions on any of your machines from your phone.

remote-cli is a self-hosted mobile control plane for Claude Code. Pair your laptop, desktop, or server with a lightweight relay, then open the PWA on your phone to start sessions, send prompts, and approve tool calls — all from wherever you are.

Phone / PWA  ──▶  Relay (self-hosted)  ──▶  Agent on each machine  ──▶  claude CLI

Agents connect outbound to the relay. No inbound ports needed on your machines.

Install

npm install -g @akshaymemane/remote-cli

Installs a launcher that downloads the matching remote-cli binary for your platform:

| Platform | Architecture | |---|---| | macOS | arm64, amd64 | | Linux | arm64, amd64 |

Quick Start

1. Set up the relay (once)

On the machine that will act as the hub:

remote-cli setup

This creates config, generates a JWT secret, and asks you for an admin password. The relay serves the mobile PWA and brokers connections between your phone and agents.

Tip: Use a Tailscale hostname, LAN IP, or public HTTPS domain — not localhost — so your phone and all machines can reach it.

2. Start the relay

remote-cli relay start

3. Open the PWA on your phone

Navigate to your relay URL in a mobile browser and sign in with the admin password.

4. Pair each machine you want to control

On every machine:

remote-cli pair --relay http://YOUR_RELAY_URL

Scan the QR code from the PWA or type the 6-digit code. The agent starts automatically after pairing.

5. Keep agents running in the background

remote-cli service install
remote-cli service start

Agents reconnect automatically after reboots and network changes.

Command Reference

# First-run wizard
remote-cli setup

# Relay
remote-cli relay init            # create config without interactive setup
remote-cli relay start           # start the relay server
remote-cli relay status          # check relay status
remote-cli relay open            # open PWA in browser
remote-cli relay reset-password  # change admin password

# Agent
remote-cli pair --relay <url>    # pair this machine and start agent
remote-cli run                   # start agent manually (foreground)
remote-cli status                # show agent status and relay connection
remote-cli unpair                # remove this machine from the relay

# Service (background autostart)
remote-cli service install
remote-cli service uninstall
remote-cli service start
remote-cli service stop
remote-cli service status
remote-cli service logs

# Utilities
remote-cli doctor                # diagnose common setup problems
remote-cli version               # show binary version

Requirements

• Node.js 18+ for this npm launcher
• Claude Code installed and authenticated on every machine you want to control
• A relay URL reachable by your phone and all agent machines (LAN IP, Tailscale, or public domain)
• Modern mobile browser (HTTPS recommended for QR camera scanning)

How It Works

| Component | Role | |---|---| | Relay | Go HTTP/WebSocket server. Login, pairing, device presence, session routing, SQLite state, embedded PWA. | | Agent | Runs on each machine. Connects outbound to relay, spawns claude for sessions. | | PWA | React mobile app. Embedded in the binary, served by the relay. |

The relay is the only component that needs a stable URL. Agents and the phone both connect to it — your machines never need inbound ports.

Tool approval requests from Claude flow agent → relay → phone. You approve or deny from the PWA before the tool runs.

Tailscale

If you have Tailscale on all devices, setup is one command per machine:

remote-cli relay init --url http://your-machine.tailnet-name.ts.net:8080

No port forwarding, no dynamic DNS. See the Tailscale guide in the docs.

Security

remote-cli is self-hosted. The relay sees plaintext prompts, responses, tool calls, and device names. Run it only on infrastructure you trust, and use TLS for anything beyond your local network.

• Phone ↔ relay: HS256 JWT (24h), set by admin password
• Agent ↔ relay: random device token, bcrypt-hashed at rest
• No end-to-end encryption in v1

Documentation

Full docs: akshaymemane.github.io/remote-cli

• Quickstart
• Choosing Your Relay URL
• Tailscale Setup
• Relay Deployment
• Agent Install
• Service & Autostart
• Troubleshooting
• Architecture

License

MIT © akshaymemane