claude-relay 1.2.8 → 1.4.0

package/README.md

@@ -1,120 +1,121 @@
 # claude-relay
 
-Run `npx claude-relay` in any directory. Access Claude Code on that directory from any device.
+Claude Code on your phone with push notifications. One command, zero install.
 
 ![claude-relay demo](screenshot.gif)
 
+You start a long task in Claude Code. You step away. Claude needs permission to edit a file. It waits. You come back 30 minutes later to a stalled session.
+
+**claude-relay fixes this.** Run `npx claude-relay` and your phone gets push notifications when Claude needs you. Tap to approve. Claude keeps working. You keep living.
+
 ```
-$ cd ~/my-project
-$ npx claude-relay
-
-  ◆  Claude Relay
-  │
-  ▲  READ BEFORE CONTINUING
-  │
-  │  Anyone with access to the URL gets full Claude Code access
-  │  to this machine, including reading, writing, and executing
-  │  files with your user permissions.
-  │
-  ◆  PIN protection
-  │  6-digit PIN, or Enter to skip
-  │  ●●●●●●
-  ◇  PIN protection · Enabled
-  │
-  ◆  Keep awake
-  ◇  Keep awake · Yes
-  │
-  └  Starting relay...
-
-  Claude Relay running at http://100.64.1.5:2633
-  my-project · /Users/you/my-project
+npx claude-relay
 ```
 
-## Why?
-
-You can use Claude Code from the Claude app, but it requires a GitHub repo, runs in a sandboxed VM, and comes with limitations. No local tools, no custom skills, no access to your actual dev environment.
+No app to install. No cloud server. No account to create. Your data stays on your machine.
 
-**claude-relay** gives you the real thing. One command in any directory and you get full Claude Code on **your machine**, from any device. Your files, your tools, your skills, your environment. No GitHub required, no sandbox.
+## Use Claude Code from your phone
 
-## How it works
+claude-relay runs on your machine and connects Claude Code to a web UI over WebSocket. Open the URL on your phone, add it to your home screen, and you get push notifications whenever Claude needs input.
 
-claude-relay uses the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) and bridges it to a web UI over WebSocket. Your browser talks to the relay, the relay talks to Claude Code. Sessions persist across reconnects.
+Sessions are real-time synced across all connected devices. Type on your PC, see it on your phone. Approve on your phone, see it on your PC. Everything is live.
 
 ```
-Browser (any device)  <-->  claude-relay (your machine)  <-->  Claude Agent SDK
-        WebSocket                HTTP/HTTPS + WS
+Your phone/tablet  <-->  claude-relay (your machine)  <-->  Claude Code
+     browser               WebSocket + HTTPS
 ```
 
-## Features
+## Push notifications for Claude Code
 
-- **One command** — `npx claude-relay` and you're live
-- **Mobile-first UI** — designed for phones and tablets, works everywhere
-- **HTTPS** — automatic TLS via [mkcert](https://github.com/FiloSottile/mkcert), enabled by default
-- **PIN protection** — optional 6-digit PIN set at startup
-- **Permission control** — tool approval relayed to the browser (Allow / Allow for Session / Deny)
-- **Multi-session** — run multiple Claude Code sessions, switch between them
-- **Multi-device sync** — input, messages, and state sync across connected devices in real-time
-- **Streaming** — real-time token streaming, tool execution, thinking blocks
-- **Session persistence** — sessions survive server restarts and reconnects
-- **Tailscale-aware** — prefers Tailscale IP for secure remote access
-- **Slash commands** — full slash command support with autocomplete
-- **Keep awake** — optional macOS caffeinate to prevent sleep while running
-- **Zero config** — no API keys, no setup. Uses your local `claude` installation
+Get notified on your phone when Claude needs approval, finishes a task, or hits an error. Works even when the browser is closed. Tap the notification to jump straight in.
 
-## Requirements
+No app required. Add to your home screen and notifications work like a native app (PWA). The built-in setup wizard walks you through it in 3 steps.
 
-- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
-- Node.js 18+
-- [mkcert](https://github.com/FiloSottile/mkcert) (optional, for HTTPS)
+## Approve Claude Code permissions remotely
 
-## Install
+Kick off a refactoring task, go make coffee. Your phone buzzes: "Claude wants to edit `src/auth.ts`". Tap approve. Claude continues. No need to walk back to your desk.
 
-```bash
-# Run directly (no install needed)
-npx claude-relay@latest
-```
+Running tests, migrations, or multi-file changes? Watch the progress from your phone or tablet without staying at your desk.
+
+## Claude Code on iPad and tablets
+
+Full Claude Code access from any browser. No SSH terminal app, no GitHub repo required, no sandboxed VM. Your actual dev environment, your tools, your MCP servers, your CLAUDE.md, your files.
+
+## Session handoff between CLI and browser
+
+Start a session in the terminal. Pick it up on your phone. Hand it back to the terminal. Sessions survive server restarts, browser closes, and reconnects. Your conversation is never lost.
+
+## Run Claude Code remotely with Tailscale
+
+To access Claude Code from outside your local network, use [Tailscale](https://tailscale.com). Install it on your machine and your phone, sign in with the same account, and you are connected. claude-relay detects Tailscale automatically.
 
-## Usage
+Tailscale creates a private encrypted tunnel between your devices. No port forwarding, no cloud relay, no data leaving your control.
+
+## Features
+
+- **Push notifications** on permission requests, task completion, and errors
+- **Real-time sync** across all connected devices via WebSocket
+- **Session persistence** across server restarts and reconnects
+- **Mobile-first UI** with big tap targets for approve/deny
+- **Setup wizard** guides you through Tailscale, HTTPS, and push setup
+- **Multi-session** support with automatic port selection
+- **PIN protection** for access control
+- **HTTPS** via mkcert, automatic certificate generation
+- **Slash commands** with autocomplete
+- **Zero config** uses your local Claude Code installation as-is
+
+## Quick start
 
 ```bash
-# Start in current directory
+# 1. Run in your project directory
 npx claude-relay
 
-# Custom port (default: 2633)
-npx claude-relay -p 8080
+# 2. Scan the QR code with your phone
+#    or open the URL shown in the terminal
 
-# Disable HTTPS
-npx claude-relay --no-https
+# 3. Press 's' for the setup wizard
+#    to enable push notifications and remote access
 ```
 
-Then open the URL on any device connected to the same network, or scan the QR code shown in the terminal.
+## HTTPS setup for push notifications
 
-### HTTPS setup
-
-HTTPS is enabled by default when [mkcert](https://github.com/FiloSottile/mkcert) is installed. To set it up:
+Push notifications require HTTPS. claude-relay supports automatic HTTPS via [mkcert](https://github.com/FiloSottile/mkcert):
 
 ```bash
 brew install mkcert
 mkcert -install
 ```
 
-claude-relay will automatically generate certificates on first run. If mkcert is not installed, it falls back to HTTP.
+Certificates are generated automatically on first run. The setup wizard checks for mkcert and guides you if it is missing.
 
-### Remote access with Tailscale
+## CLI options
 
-claude-relay automatically detects [Tailscale](https://tailscale.com) and uses your Tailscale IP. Install Tailscale on your machine and phone, and you can access Claude Code from anywhere.
+```bash
+npx claude-relay              # Start with defaults
+npx claude-relay -p 8080      # Custom port (default: 2633)
+npx claude-relay --no-https   # Disable HTTPS
+npx claude-relay --no-update  # Skip auto-update check
+npx claude-relay --debug      # Enable debug panel
+```
 
-## Issues
+## Requirements
 
-Found a bug or have a feature request? [Open an issue](https://github.com/chadbyte/claude-relay/issues).
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+- Node.js 18+
+- [mkcert](https://github.com/FiloSottile/mkcert) (for HTTPS and push notifications)
+- [Tailscale](https://tailscale.com) (for remote access outside your network)
 
 ## Security
 
-**Anyone with access to the URL gets full Claude Code access to your machine**, including reading, writing, and executing files with your user permissions. PIN protection adds a layer of access control, but is not a substitute for network-level security.
+**Anyone with access to the URL gets full Claude Code access to your machine**, including reading, writing, and executing files with your user permissions.
 
-We strongly recommend using a private network layer such as [Tailscale](https://tailscale.com), WireGuard, or a VPN. claude-relay automatically detects Tailscale and prefers its IP for this reason.
+Use a private network. We strongly recommend [Tailscale](https://tailscale.com), WireGuard, or a VPN. PIN protection adds a layer of access control but is not a substitute for network-level security. Do not expose claude-relay to the public internet.
 
-If you choose to expose it beyond your private network, that's your call. **Entirely at your own risk.** The authors assume no responsibility for any damage, data loss, or security incidents.
+**Entirely at your own risk.** The authors assume no responsibility for any damage, data loss, or security incidents.
+
+## Issues
+
+Found a bug or have a feature request? [Open an issue](https://github.com/chadbyte/claude-relay/issues).
 
 ## Disclaimer
 

package/bin/cli.js

@@ -11,6 +11,7 @@ const args = process.argv.slice(2);
 let port = 2633;
 let useHttps = true;
 let skipUpdate = false;
+let debugMode = false;
 
 for (let i = 0; i < args.length; i++) {
   if (args[i] === "-p" || args[i] === "--port") {
@@ -24,13 +25,16 @@ for (let i = 0; i < args.length; i++) {
     useHttps = false;
   } else if (args[i] === "--no-update" || args[i] === "--skip-update") {
     skipUpdate = true;
+  } else if (args[i] === "--debug") {
+    debugMode = true;
   } else if (args[i] === "-h" || args[i] === "--help") {
-    console.log("Usage: claude-relay [-p|--port <port>] [--no-https] [--no-update]");
+    console.log("Usage: claude-relay [-p|--port <port>] [--no-https] [--no-update] [--debug]");
     console.log("");
     console.log("Options:");
     console.log("  -p, --port <port>  Port to listen on (default: 2633)");
     console.log("  --no-https         Disable HTTPS (enabled by default via mkcert)");
     console.log("  --no-update        Skip auto-update check on startup");
+    console.log("  --debug            Enable debug panel in the web UI");
     process.exit(0);
   }
 }
@@ -305,8 +309,276 @@ function promptToggle(title, desc, defaultValue, callback) {
   });
 }
 
+// --- Port availability check ---
+var net = require("net");
+
+function isPortFree(p) {
+  return new Promise(function (resolve) {
+    var srv = net.createServer();
+    srv.once("error", function () { resolve(false); });
+    srv.once("listening", function () { srv.close(function () { resolve(true); }); });
+    srv.listen(p);
+  });
+}
+
+async function findAvailablePort(startPort) {
+  var p = startPort;
+  var maxAttempts = 20;
+  for (var i = 0; i < maxAttempts; i++) {
+    var httpFree = await isPortFree(p);
+    var httpsFree = await isPortFree(p + 1);
+    if (httpFree && httpsFree) return p;
+    p += 2;
+  }
+  return null;
+}
+
+// --- Detect tools ---
+function getTailscaleIP() {
+  var interfaces = os.networkInterfaces();
+  for (var name in interfaces) {
+    if (/^(tailscale|utun)/.test(name)) {
+      for (var i = 0; i < interfaces[name].length; i++) {
+        var addr = interfaces[name][i];
+        if (addr.family === "IPv4" && !addr.internal && addr.address.startsWith("100.")) {
+          return addr.address;
+        }
+      }
+    }
+  }
+  for (var addrs of Object.values(interfaces)) {
+    for (var j = 0; j < addrs.length; j++) {
+      if (addrs[j].family === "IPv4" && !addrs[j].internal && addrs[j].address.startsWith("100.")) {
+        return addrs[j].address;
+      }
+    }
+  }
+  return null;
+}
+
+function hasTailscale() {
+  return getTailscaleIP() !== null;
+}
+
+function hasMkcert() {
+  try {
+    execSync("mkcert -CAROOT", { stdio: "pipe", encoding: "utf8" });
+    return true;
+  } catch (e) { return false; }
+}
+
+// --- Re-check / back key listener ---
+function listenForKey(keys, callback) {
+  if (!process.stdin.isTTY) return;
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.setEncoding("utf8");
+
+  var handler = function (ch) {
+    var lower = ch.toLowerCase();
+    if (ch === "\x03") { process.exit(0); return; }
+    if (keys[lower]) {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdin.removeListener("data", handler);
+      keys[lower]();
+    }
+  };
+  process.stdin.on("data", handler);
+}
+
+// --- Post-startup setup guide ---
+function showSetupGuide(serverIP, httpPort, httpsPort, showMainView) {
+  var wantRemote = false;
+  var wantPush = false;
+
+  function redraw(renderFn) {
+    console.clear();
+    printLogo();
+    log("");
+    log(sym.pointer + "  " + a.bold + "Setup Guide" + a.reset);
+    log(sym.bar);
+    if (wantRemote) log(sym.done + "  Access from outside your network? " + a.dim + "·" + a.reset + " " + a.green + "Yes" + a.reset);
+    else log(sym.done + "  Access from outside your network? " + a.dim + "· No" + a.reset);
+    log(sym.bar);
+    if (wantPush) log(sym.done + "  Want push notifications? " + a.dim + "·" + a.reset + " " + a.green + "Yes" + a.reset);
+    else log(sym.done + "  Want push notifications? " + a.dim + "· No" + a.reset);
+    log(sym.bar);
+    renderFn();
+  }
+
+  log("");
+  log(sym.pointer + "  " + a.bold + "Setup Guide" + a.reset);
+  log(sym.bar);
+
+  promptToggle("Access from outside your network?", "Requires Tailscale on both devices", false, function (remote) {
+    wantRemote = remote;
+    log(sym.bar);
+    promptToggle("Want push notifications?", "Requires HTTPS (mkcert certificate)", false, function (push) {
+      wantPush = push;
+      log(sym.bar);
+      afterToggles();
+    });
+  });
+
+  function showSetupQR() {
+    var tsIP = getTailscaleIP();
+    var setupUrl = "http://" + (tsIP || serverIP) + ":" + httpPort + "/setup";
+    log(sym.pointer + "  " + a.bold + "Continue on your device" + a.reset);
+    log(sym.bar + "  " + a.dim + "Scan the QR code or open:" + a.reset);
+    log(sym.bar + "  " + a.bold + setupUrl + a.reset);
+    log(sym.bar);
+    qrcode.generate(setupUrl, { small: true }, function (code) {
+      var lines = code.split("\n").map(function (l) { return "  " + sym.bar + "  " + l; }).join("\n");
+      console.log(lines);
+      log(sym.bar);
+      log(sym.bar + "  " + a.dim + "Can't connect?" + a.reset);
+      if (tsIP) {
+        log(sym.bar + "  " + a.dim + "Make sure Tailscale is installed on your phone too." + a.reset);
+      } else {
+        log(sym.bar + "  " + a.dim + "Your phone must be on the same Wi-Fi network." + a.reset);
+      }
+      log(sym.bar);
+      log(sym.done + "  " + a.dim + "Server setup complete." + a.reset);
+      log(sym.end);
+      log("");
+      listenForBackKey(showMainView);
+    });
+  }
+
+  function afterToggles() {
+    if (!wantRemote && !wantPush) {
+      log(sym.done + "  " + a.green + "All set!" + a.reset + a.dim + " · No additional setup needed." + a.reset);
+      log(sym.end);
+      log("");
+      listenForBackKey(showMainView);
+      return;
+    }
+    if (wantRemote) {
+      renderTailscale();
+    } else {
+      renderHttps();
+    }
+  }
+
+  function renderTailscale() {
+    var tsReady = hasTailscale();
+    var tsIP = tsReady ? getTailscaleIP() : null;
+
+    log(sym.pointer + "  " + a.bold + "Tailscale Setup" + a.reset);
+    if (tsReady && tsIP) {
+      log(sym.bar + "  " + a.green + "Tailscale is running" + a.reset + a.dim + " · " + tsIP + a.reset);
+      log(sym.bar);
+      log(sym.bar + "  On your phone/tablet:");
+      log(sym.bar + "  " + a.dim + "1. Install Tailscale (App Store / Google Play)" + a.reset);
+      log(sym.bar + "  " + a.dim + "2. Sign in with the same account" + a.reset);
+      log(sym.bar);
+      renderHttps();
+    } else if (tsReady) {
+      log(sym.bar + "  " + a.yellow + "Tailscale is installed but no IP found." + a.reset);
+      log(sym.bar + "  " + a.dim + "Run: tailscale up" + a.reset);
+      log(sym.bar);
+      log(sym.bar + "  " + a.dim + "Press " + a.reset + "r" + a.dim + " to re-check, " + a.reset + "h" + a.dim + " to go back." + a.reset);
+      log(sym.end);
+      log("");
+      listenForKey({ r: function () { redraw(renderTailscale); }, h: showMainView });
+    } else {
+      log(sym.bar + "  " + a.yellow + "Tailscale not found on this machine." + a.reset);
+      log(sym.bar + "  " + a.dim + "Install: https://tailscale.com/download" + a.reset);
+      log(sym.bar + "  " + a.dim + "Then run: tailscale up" + a.reset);
+      log(sym.bar);
+      log(sym.bar + "  On your phone/tablet:");
+      log(sym.bar + "  " + a.dim + "1. Install Tailscale (App Store / Google Play)" + a.reset);
+      log(sym.bar + "  " + a.dim + "2. Sign in with the same account" + a.reset);
+      log(sym.bar);
+      log(sym.bar + "  " + a.dim + "Press " + a.reset + "r" + a.dim + " to re-check, " + a.reset + "h" + a.dim + " to go back." + a.reset);
+      log(sym.end);
+      log("");
+      listenForKey({ r: function () { redraw(renderTailscale); }, h: showMainView });
+    }
+  }
+
+  function renderHttps() {
+    if (!wantPush) {
+      showSetupQR();
+      return;
+    }
+
+    var mcReady = hasMkcert();
+    var tsIP = getTailscaleIP();
+    log(sym.pointer + "  " + a.bold + "HTTPS Setup (for push notifications)" + a.reset);
+    if (mcReady) {
+      log(sym.bar + "  " + a.green + "mkcert is installed" + a.reset);
+      log(sym.bar);
+      showSetupQR();
+    } else {
+      log(sym.bar + "  " + a.yellow + "mkcert not found." + a.reset);
+      log(sym.bar + "  " + a.dim + "Install: brew install mkcert && mkcert -install" + a.reset);
+      log(sym.bar);
+      log(sym.bar + "  " + a.dim + "Press " + a.reset + "r" + a.dim + " to re-check, " + a.reset + "h" + a.dim + " to go back." + a.reset);
+      log(sym.end);
+      log("");
+      listenForKey({ r: function () { redraw(renderHttps); }, h: showMainView });
+    }
+  }
+}
+
+function listenForSetupKey(serverIP, httpPort, httpsPort, showMainView) {
+  if (!process.stdin.isTTY) return;
+  var bc = a.dim;
+  var rc = a.reset;
+  var msg1 = "Access from your phone or get notified when Claude is done?";
+  var msg2 = "Press " + a.cyan + a.bold + "s" + rc + " to set up.";
+  var w = msg1.length + 4;
+  var pad2 = " ".repeat(msg1.length - 18);
+  log(bc + "┌" + "─".repeat(w) + "┐" + rc);
+  log(bc + "│  " + rc + msg1 + bc + "  │" + rc);
+  log(bc + "│  " + rc + msg2 + pad2 + bc + "  │" + rc);
+  log(bc + "└" + "─".repeat(w) + "┘" + rc);
+  log("");
+
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.setEncoding("utf8");
+
+  process.stdin.on("data", function onKey(ch) {
+    if (ch === "s" || ch === "S") {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdin.removeListener("data", onKey);
+      console.clear();
+      printLogo();
+      log("");
+      showSetupGuide(serverIP, httpPort, httpsPort, showMainView);
+    } else if (ch === "\x03") {
+      process.exit(0);
+    }
+  });
+}
+
+function listenForBackKey(showMainView) {
+  if (!process.stdin.isTTY) return;
+  log(a.dim + "Press " + a.reset + "h" + a.dim + " to go back." + a.reset);
+  log("");
+
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.setEncoding("utf8");
+
+  process.stdin.on("data", function onBack(ch) {
+    if (ch === "h" || ch === "H") {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdin.removeListener("data", onBack);
+      showMainView();
+    } else if (ch === "\x03") {
+      process.exit(0);
+    }
+  });
+}
+
 // --- Server start ---
-function start(pin) {
+async function start(pin) {
   var ip = getLocalIP();
   var tlsOptions = null;
   var caRoot = null;
@@ -326,37 +598,46 @@ function start(pin) {
     }
   }
 
-  var result = createServer(cwd, tlsOptions, caRoot, pin, port);
+  var actualPort = await findAvailablePort(port);
+  if (actualPort === null) {
+    log(a.red + "No available port found (tried " + port + " to " + (port + 38) + ")." + a.reset);
+    process.exit(1);
+    return;
+  }
+  if (actualPort !== port) {
+    log(sym.warn + "  " + a.yellow + "Port " + port + " in use" + a.reset + a.dim + " · using " + actualPort + a.reset);
+    log(sym.bar);
+  }
+  port = actualPort;
+
+  var result = createServer(cwd, tlsOptions, caRoot, pin, port, debugMode);
   var entryServer = result.entryServer;
   var httpsServer = result.httpsServer;
 
   entryServer.on("error", function (err) {
-    if (err.code === "EADDRINUSE") {
-      log(a.red + "Port " + port + " is already in use." + a.reset);
-      log(a.dim + "Run: claude-relay -p <port>" + a.reset);
-    } else {
-      log(a.red + "Server error: " + err.message + a.reset);
-    }
+    log(a.red + "Server error: " + err.message + a.reset);
     process.exit(1);
   });
 
   var httpsPort = port + 1;
   if (httpsServer) {
     httpsServer.on("error", function (err) {
-      if (err.code === "EADDRINUSE") {
-        log(a.red + "HTTPS port " + httpsPort + " is already in use." + a.reset);
-      } else {
-        log(a.red + "HTTPS error: " + err.message + a.reset);
-      }
+      log(a.red + "HTTPS error: " + err.message + a.reset);
       process.exit(1);
     });
     httpsServer.listen(httpsPort);
   }
 
-  entryServer.listen(port, function () {
+  var hPort = httpsServer ? httpsPort : null;
+
+  function showMainView() {
     var project = path.basename(cwd);
     var url = "http://" + ip + ":" + port;
 
+    console.clear();
+    printLogo();
+    log("");
+
     if (ip !== "localhost") {
       qrcode.generate(url, { small: true }, function (code) {
         var lines = code.split("\n").map(function (l) { return "  " + l; }).join("\n");
@@ -365,13 +646,17 @@ function start(pin) {
         log(a.bold + "Claude Relay" + a.reset + " running at " + a.bold + url + a.reset);
         log(a.dim + project + " · " + cwd + a.reset);
         log("");
+        listenForSetupKey(ip, port, hPort, showMainView);
       });
     } else {
       log(a.bold + "Claude Relay" + a.reset + " running at " + a.bold + url + a.reset);
       log(a.dim + project + " · " + cwd + a.reset);
       log("");
+      listenForSetupKey(ip, port, hPort, showMainView);
     }
-  });
+  }
+
+  entryServer.listen(port, showMainView);
 }
 
 const { checkAndUpdate } = require("../lib/updater");