claude-relay 1.4.0 → 1.5.0

package/README.md

@@ -1,125 +1,129 @@
 # claude-relay
 
-Claude Code on your phone with push notifications. One command, zero install.
+<p align="center">
+  <img src="media/phone.gif" alt="claude-relay on phone" width="300">
+</p>
 
-![claude-relay demo](screenshot.gif)
+<h3 align="center">Claude Code on your phone. Push notifications. Zero install.</h3>
 
-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.
+[![npm](https://img.shields.io/npm/v/claude-relay)](https://www.npmjs.com/package/claude-relay) [![downloads](https://img.shields.io/npm/dw/claude-relay)](https://www.npmjs.com/package/claude-relay)
 
-**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.
+You step away. Claude Code stops.
 
-```
-npx claude-relay
-```
+> "A 10-second approval can block it for hours if you're not at your desk."
+> — [#25115](https://github.com/anthropics/claude-code/issues/25115)
 
-No app to install. No cloud server. No account to create. Your data stays on your machine.
+> "I don't need to write code on my phone. I need to approve, reject, continue, stop. That's it."
+> — [#18189](https://github.com/anthropics/claude-code/issues/18189)
 
-## Use Claude Code from your phone
+**claude-relay fixes this.** Your phone buzzes when Claude needs you. Tap approve. Claude keeps working. You keep doing whatever you were doing.
 
-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.
+No app. No cloud. No account. Your code never touches a third-party server.
 
-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.
+Runs a Claude Code session on your machine via the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) and streams it to your browser over WebSocket. Nothing is proxied through external servers.
 
-```
-Your phone/tablet  <-->  claude-relay (your machine)  <-->  Claude Code
-     browser               WebSocket + HTTPS
-```
+---
 
 ## Push notifications for Claude Code
 
-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.
-
-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.
+Permission request. Task done. Error. Question. Your phone buzzes. Browser can be closed.
 
-## Approve Claude Code permissions remotely
+Add to home screen → PWA → push notifications work like a native app. Setup wizard handles everything.
 
-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.
+<p align="center">
+  <img src="media/push-notification.jpg" alt="push notification" width="300">
+</p>
 
-Running tests, migrations, or multi-file changes? Watch the progress from your phone or tablet without staying at your desk.
+## Use Claude Code from any device
 
-## Claude Code on iPad and tablets
+Open claude-relay on your phone, tablet, or any browser. Type a prompt, watch Claude work, review code — all in real time. Every connected device sees the same session live.
 
-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.
+Permission prompt? Approve from whichever device is closest. The session updates everywhere instantly.
 
-## Session handoff between CLI and browser
+## Quick start
 
-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.
+```bash
+# Run in your project directory
+npx claude-relay
 
-## Run Claude Code remotely with Tailscale
+# Scan the QR code with your phone — opens Claude Code in your browser
 
-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.
+# Press 's' → setup wizard → push + remote access in 3 steps
+```
 
-Tailscale creates a private encrypted tunnel between your devices. No port forwarding, no cloud relay, no data leaving your control.
+<p align="center">
+  <img src="media/start.gif" alt="npx claude-relay" width="600">
+</p>
 
-## Features
+## All 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
+- **Push notifications** — permission requests, completions, errors, questions. Works with browser closed.
+- **Real-time sync** — every device sees the same session live via WebSocket. Type on desktop, see it on phone.
+- **Session persistence** — server restarts, browser crashes, network drops. Session survives. Conversation is never lost.
+- **Session handoff** — start in the terminal, pick it up on your phone, hand it back. Seamless.
+- **Conversation rewind** — click any previous message to roll back conversation and files together, with full diffs
+- **Mobile-first UI** — big approve/deny buttons, one-handed use
+- **iPad and tablet support** — full Claude Code from any browser. Your actual machine, your tools, your MCP servers, your files.
+- **Setup wizard** — Tailscale, HTTPS, push. Step by step.
+- **Multi-session** — multiple projects, automatic port selection
+- **PIN protection** — access control beyond network security
+- **HTTPS** — automatic certs via mkcert
+- **Slash commands** — with autocomplete
+- **Zero config** — works with your existing Claude Code setup
 
-## Quick start
+## Network access
 
-```bash
-# 1. Run in your project directory
-npx claude-relay
+On the same Wi-Fi? It just works. Open the URL shown in the terminal from any device on your network.
 
-# 2. Scan the QR code with your phone
-#    or open the URL shown in the terminal
+Outside your network? [Tailscale](https://tailscale.com) creates an encrypted tunnel between your devices. No port forwarding. No cloud relay. Your code never leaves your control.
 
-# 3. Press 's' for the setup wizard
-#    to enable push notifications and remote access
-```
+Install on both devices. Same account. Done. claude-relay detects it automatically. Free for personal use.
 
-## HTTPS setup for push notifications
+## HTTPS for push notifications
 
-Push notifications require HTTPS. claude-relay supports automatic HTTPS via [mkcert](https://github.com/FiloSottile/mkcert):
+Push needs HTTPS. [mkcert](https://github.com/FiloSottile/mkcert) makes it painless:
 
 ```bash
 brew install mkcert
 mkcert -install
 ```
 
-Certificates are generated automatically on first run. The setup wizard checks for mkcert and guides you if it is missing.
+Certificates generate automatically. Setup wizard handles the rest.
 
 ## CLI options
 
 ```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
+npx claude-relay              # defaults
+npx claude-relay -p 8080      # custom port (default: 2633)
+npx claude-relay --no-https   # disable HTTPS
+npx claude-relay --no-update  # skip update check
+npx claude-relay --debug      # debug panel
 ```
 
 ## Requirements
 
 - [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)
+- [mkcert](https://github.com/FiloSottile/mkcert) for HTTPS and push
+- [Tailscale](https://tailscale.com) for remote access
 
 ## 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.
+**Anyone with the URL gets full Claude Code access to your machine.** Read, write, execute — your user permissions.
+
+PIN protection is enabled during setup — every new device must enter the PIN shown in your terminal before accessing any session. This prevents casual shoulder-surfing of the QR code, but is not a substitute for network-level security.
 
-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.
+Private network only. [Tailscale](https://tailscale.com), WireGuard, or a VPN. Never expose to the public internet.
 
-**Entirely at your own risk.** The authors assume no responsibility for any damage, data loss, or security incidents.
+**Entirely at your own risk.**
 
-## Issues
+## Contributing
 
-Found a bug or have a feature request? [Open an issue](https://github.com/chadbyte/claude-relay/issues).
+Bug fixes and typos — PR welcome. Feature ideas — [open an issue](https://github.com/chadbyte/claude-relay/issues) first. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Disclaimer
 
-claude-relay is an independent, unofficial project. It is not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" is a trademark of Anthropic.
+Independent project. Not affiliated with Anthropic. "Claude" is a trademark of Anthropic.
 
 ## License
 

package/bin/cli.js

@@ -3,7 +3,7 @@
 const os = require("os");
 const fs = require("fs");
 const path = require("path");
-const { execSync } = require("child_process");
+const { execSync, execFileSync } = require("child_process");
 const qrcode = require("qrcode-terminal");
 const { createServer } = require("../lib/server");
 
@@ -116,10 +116,21 @@ function startCaffeinate() {
 
 // --- Certs ---
 function ensureCerts(ip) {
-  var certDir = path.join(cwd, ".claude-relay", "certs");
+  var homeDir = process.env.HOME || process.env.USERPROFILE || os.homedir();
+  var certDir = path.join(homeDir, ".claude-relay", "certs");
   var keyPath = path.join(certDir, "key.pem");
   var certPath = path.join(certDir, "cert.pem");
 
+  // Migrate from legacy per-project certs to shared home dir
+  var legacyDir = path.join(cwd, ".claude-relay", "certs");
+  var legacyKey = path.join(legacyDir, "key.pem");
+  var legacyCert = path.join(legacyDir, "cert.pem");
+  if (!fs.existsSync(keyPath) && fs.existsSync(legacyKey) && fs.existsSync(legacyCert)) {
+    fs.mkdirSync(certDir, { recursive: true });
+    fs.copyFileSync(legacyKey, keyPath);
+    fs.copyFileSync(legacyCert, certPath);
+  }
+
   var caRoot = null;
   try {
     caRoot = path.join(
@@ -130,7 +141,15 @@ function ensureCerts(ip) {
   } catch (e) { }
 
   if (fs.existsSync(keyPath) && fs.existsSync(certPath)) {
-    return { key: keyPath, cert: certPath, caRoot: caRoot };
+    // Re-generate if current IP is not in the cert's SAN
+    var needRegen = false;
+    if (ip && ip !== "localhost") {
+      try {
+        var certText = execFileSync("openssl", ["x509", "-in", certPath, "-text", "-noout"], { encoding: "utf8" });
+        if (certText.indexOf(ip) === -1) needRegen = true;
+      } catch (e) { /* openssl not available, skip check */ }
+    }
+    if (!needRegen) return { key: keyPath, cert: certPath, caRoot: caRoot };
   }
 
   fs.mkdirSync(certDir, { recursive: true });