Remote Runner for Claude

Disclaimer: This is an unofficial community project and is not affiliated with, endorsed by, or associated with Anthropic. "Claude" is a trademark of Anthropic.

A cross-platform CLI wrapper and Progressive Web App (PWA) that lets you control Claude Code remotely. Watch Claude code in real-time on your phone via WebRTC, get push notifications when it pauses for input, and respond directly from your mobile device.

Installation

Install globally via npm:

npm install -g @sohampawar1866/remote-claude

Note on Self-Hosting: By default, this connects to a pre-deployed frontend and signaling server (zero-config). If you prefer absolute data sovereignty, you can easily self-host both the PWA and the Appwrite signaling server. See the Self-Hosting section at the bottom of this README.

Usage

To start a remote session, simply run:

remote-claude

On first launch, the CLI prints a QR code. Scan it with your phone's native camera to instantly open the PWA and establish a live WebRTC peer connection.

Options

Flag	Description
-k, --keep-awake	Prevent the system from sleeping while Claude runs
-d, --debug	Enable debug logging for pause detection state transitions
--silence-threshold <ms>	Silence threshold in ms before fallback pause detection (default: 3000)
--pattern-debounce <ms>	Pattern match debounce in ms (default: 1500)
--no-hooks	Disable automatic Claude Code hook installation
-c, --command <cmd>	Command to run (default: claude)

Examples

# Basic usage — keep machine awake
remote-claude -k

# Debug mode — see state transitions in real time
remote-claude -d

Core Features

• Live Terminal Mirroring (WebRTC + xterm.js) - A pixel-perfect terminal mirror powered by xterm.js (the same engine behind VS Code). Cursor movements, colors, and TUI redraws render flawlessly. The terminal dynamically auto-resizes to your phone's exact dimensions.
• Instant QR Pairing & PWA - Scan the QR code to connect. The session persists to localStorage, allowing you to add the app to your iOS/Android home screen.
• Zero-Config Push Notifications (Deep Linked) - A 4-layer hybrid detection engine detects when Claude pauses. Simply tap the "🔔 Alerts" button in the PWA to instantly subscribe via deep link—no copying, pasting, or Appwrite configuration required!
• Zero-Trust Security - All peer-to-peer streams and Appwrite signaling payloads are secured with AES-256-GCM encryption.

Architecture & Security

Security is a core concern for this tool. See the full Security Architecture Guide for details on the zero-trust WebRTC model.

Here is how the v3.2.0 pipeline works:

1. remote-claude wraps the claude CLI using node-pty and monitors terminal output.
2. The CLI generates a random channelId and AES encryptionKey.
3. It creates a WebRTC Peer Connection, generates an encrypted SDP Offer, and posts it to Appwrite.
4. It prints a QR Code containing these credentials to your terminal.
5. You scan the QR code with your phone. The PWA opens, reads the key from the URL, persists it to localStorage, then cleans the URL to prevent key leakage.
6. The PWA decrypts the SDP Offer, generates an Answer, and posts it back to Appwrite.
7. The CLI securely polls for the Answer (to ensure stability in Node.js) and establishes a direct, zero-latency WebRTC P2P Data Channel.
8. The CLI sends a history burst (the current terminal buffer) so you see full context immediately.
9. The mobile sends its screen dimensions; the CLI resizes the PTY accordingly.
10. The terminal stream flows directly to your phone via JSON packets ({type: "stream"}), where the PWA's xterm.js terminal emulator renders cursor movements, colors, and TUI redraws with full fidelity.
11. If your phone goes to sleep and the WebRTC connection breaks, the CLI automatically falls back to Appwrite for push notifications. When you reopen the app, it auto-reconnects WebRTC.

WebRTC JSON Protocol

The Data Channel uses a structured JSON packet protocol:

Packet Type	Direction	Description
stream	CLI → Mobile	Real-time terminal output chunk
history	CLI → Mobile	Full terminal buffer burst for late joiners
input	Mobile → CLI	User response text
resize	Mobile → CLI	Terminal dimension sync (cols, rows)

Project Structure

claude-remote-runner/
├── bin/                         # CLI entry point
│   └── remote-claude.js         # Main executable (WebRTC + PTY orchestration)
├── docs/                        # Documentation
│   └── SECURITY.md              # Security architecture guide
├── src/                         # CLI source modules
│   ├── config/                  # Configuration and defaults
│   ├── detection/               # Pause detection engine (4-layer hybrid)
│   │   ├── PauseDetector.js     # Core state machine
│   │   ├── patterns.js          # Pattern catalog + prompt box parsing
│   │   ├── hookSetup.js         # Claude Code lifecycle hook integration
│   │   └── index.js             # Barrel export
│   ├── services/                # WebRTC, Appwrite, ntfy
│   │   ├── webrtc.js            # P2P session + JSON protocol + history burst
│   │   ├── appwrite.js          # Polling + signaling
│   │   └── ntfy.js              # Push notifications
│   └── utils/                   # Crypto and keep-awake utilities
├── mobile-app/                  # Self-contained PWA (deploy separately)
│   ├── src/
│   │   ├── components/          # XTermTerminal, ChatInput, PromptList
│   │   ├── hooks/               # useWebRTC (reconnect + resize), useRemoteSession (localStorage)
│   │   ├── services/            # Appwrite signaling