claude-relay 2.3.1 → 2.4.1

package/README.md

@@ -6,7 +6,7 @@
 
 <h3 align="center">Web UI for Claude Code. Any device. Push notifications.</h3>
 
-[![npm version](https://img.shields.io/npm/v/claude-relay)](https://www.npmjs.com/package/claude-relay) [![npm downloads](https://img.shields.io/npm/dw/claude-relay)](https://www.npmjs.com/package/claude-relay) [![GitHub stars](https://img.shields.io/github/stars/chadbyte/claude-relay)](https://github.com/chadbyte/claude-relay)
+[![npm version](https://img.shields.io/npm/v/claude-relay)](https://www.npmjs.com/package/claude-relay) [![npm downloads](https://img.shields.io/npm/dw/claude-relay)](https://www.npmjs.com/package/claude-relay) [![GitHub stars](https://img.shields.io/github/stars/chadbyte/claude-relay)](https://github.com/chadbyte/claude-relay) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/chadbyte/claude-relay/blob/main/LICENSE)
 
 Claude Code. Anywhere.  
 Same session. Same files. Same machine.  
@@ -86,7 +86,7 @@ Scan the QR code with your phone to connect instantly, or open the URL displayed
 ## Key Features
 
 * **Push Approvals** - Approve or reject from your phone while away, so Claude Code does not get stuck waiting.
-* **Multi Project Daemon** - Manage all projects via a single port.
+* **Multi Project Daemon** - Manage all projects via a single port. Add and remove projects from the browser.
 * **Usage and Model Switching** - View token usage, rate limit bars, and switch models from the browser.
 * **Session Search** - Full-text search across all session messages with hit timeline.
 * **Auto Session Logs (JSONL)** - Conversations and execution history are always saved locally. No data loss on crashes or restarts. Location: `./.claude-relay/sessions/`
@@ -105,10 +105,10 @@ Scan the QR code with your phone to connect instantly, or open the URL displayed
 
 **Projects and Sessions**
 
-* **Multi Project** - Single port management for all projects.
+* **Multi Project** - Single port management for all projects. Add and remove projects from the browser with path autocomplete.
 * **Project Names** - Custom names make it easy to distinguish tabs.
 * **Session Persistence** - Sessions survive server restarts, browser crashes, and network drops.
-* **Session Handoff** - Start in the terminal, continue on your phone, pass back to desktop.
+* **Session Handoff** - Start in the terminal, continue on your phone, pass back to desktop. Browse and resume CLI sessions directly from the web UI.
 * **Session Search** - Full-text search across all session content with highlighted results and a rewind-style hit timeline.
 * **Rewind (Native Claude Code)** - Accessible directly from the browser UI.
 * **Draft Persistence** - Unsent messages are saved per session and restored when you switch back.
@@ -183,7 +183,7 @@ If push registration fails: check whether your browser trusts HTTPS and whether
 ```bash
 npx claude-relay              # Default (port 2633)
 npx claude-relay -p 8080      # Specify port
-npx claude-relay -y           # Skip interactive prompts (accept defaults)
+npx claude-relay --yes        # Skip interactive prompts (accept defaults)
 npx claude-relay -y --pin 123456
                               # Non-interactive with PIN (for scripts/CI)
 npx claude-relay --no-https   # Disable HTTPS
@@ -196,6 +196,7 @@ npx claude-relay --list       # List registered projects
 npx claude-relay --shutdown   # Stop the running daemon
 npx claude-relay --dangerously-skip-permissions
                               # Bypass all permission prompts (PIN required during setup)
+npx claude-relay --dev        # Development mode (foreground, auto-restart on lib/ changes, port 2635)
 ```
 
 ## Requirements
@@ -205,6 +206,20 @@ npx claude-relay --dangerously-skip-permissions
 * [mkcert](https://github.com/FiloSottile/mkcert) - For push notifications (optional)
 * [Tailscale](https://tailscale.com) - For remote access (optional)
 
+## Why claude-relay?
+
+**Why not just use tmux + Termius?**
+You can monitor the terminal remotely, but there are no push notifications and no way to approve permission requests without switching back to the terminal. On a phone, navigating a raw terminal session is clunky. You end up checking manually instead of getting notified, and the experience never feels native.
+
+**Why not just add hooks to send notifications?**
+Hooks with ntfy or Pushover can get you push notifications, but you still need shell scripts, config files, and third-party accounts just to get alerts. And once you get the notification, there is no UI to approve or reject from. You are back to opening a terminal. claude-relay gives you notifications, a one-tap approval UI, and a full web interface with a single command.
+
+**Why not use Claude Code Desktop?**
+The desktop app works great on your computer, but there is no mobile version. To access sessions from your phone, you need remote sessions on Anthropic's cloud, which requires pushing your code to GitHub first. claude-relay runs entirely on your machine and lets you connect from any device on your network.
+
+**Why not use Happy Coder?**
+Happy Coder requires installing a native app and routes through its own relay server with end-to-end encryption. claude-relay *is* the relay server, running on your machine. Open a URL and you are in. No app install, no signup, nothing leaves your network.
+
 ## Architecture
 
 claude-relay is not a wrapper that intercepts standard input/output.

package/bin/cli.js

@@ -8,7 +8,7 @@ var qrcode = require("qrcode-terminal");
 var net = require("net");
 
 // Detect dev mode before loading config (env must be set before require)
-var _isDev = process.argv[1] && path.basename(process.argv[1]) === "claude-relay-dev";
+var _isDev = (process.argv[1] && path.basename(process.argv[1]) === "claude-relay-dev") || process.argv.includes("--dev");
 if (_isDev) {
   process.env.CLAUDE_RELAY_HOME = path.join(os.homedir(), ".claude-relay-dev");
 }
@@ -40,6 +40,8 @@ var addPath = null;
 var removePath = null;
 var listMode = false;
 var dangerouslySkipPermissions = false;
+var headlessMode = false;
+var watchMode = false;
 
 for (var i = 0; i < args.length; i++) {
   if (args[i] === "-p" || args[i] === "--port") {
@@ -53,6 +55,10 @@ for (var i = 0; i < args.length; i++) {
     useHttps = false;
   } else if (args[i] === "--no-update" || args[i] === "--skip-update") {
     skipUpdate = true;
+  } else if (args[i] === "--dev") {
+    // Already handled above for CLAUDE_RELAY_HOME, just skip
+  } else if (args[i] === "--watch" || args[i] === "-w") {
+    watchMode = true;
   } else if (args[i] === "--debug") {
     debugMode = true;
   } else if (args[i] === "-y" || args[i] === "--yes") {
@@ -70,6 +76,9 @@ for (var i = 0; i < args.length; i++) {
     i++;
   } else if (args[i] === "--list") {
     listMode = true;
+  } else if (args[i] === "--headless") {
+    headlessMode = true;
+    autoYes = true;
   } else if (args[i] === "--dangerously-skip-permissions") {
     dangerouslySkipPermissions = true;
   } else if (args[i] === "-h" || args[i] === "--help") {
@@ -89,12 +98,19 @@ for (var i = 0; i < args.length; i++) {
     console.log("  --add <path>       Add a project directory (use '.' for current)");
     console.log("  --remove <path>    Remove a project directory");
     console.log("  --list             List all registered projects");
+    console.log("  --headless         Start daemon and exit immediately (implies --yes)");
     console.log("  --dangerously-skip-permissions");
     console.log("                     Bypass all permission prompts (requires --pin)");
     process.exit(0);
   }
 }
 
+// Dev mode implies debug + skip update
+if (_isDev) {
+  debugMode = true;
+  skipUpdate = true;
+}
+
 // --- Handle --shutdown before anything else ---
 if (shutdownMode) {
   var shutdownConfig = loadConfig();
@@ -393,9 +409,13 @@ async function restartDaemonFromConfig() {
   newConfig.pid = child.pid;
   saveConfig(newConfig);
 
-  // Wait and verify
-  await new Promise(function (resolve) { setTimeout(resolve, 1200); });
-  var alive = await isDaemonAliveAsync(newConfig);
+  // Wait and verify (retry up to 5 seconds)
+  var alive = false;
+  for (var rc = 0; rc < 10; rc++) {
+    await new Promise(function (resolve) { setTimeout(resolve, 500); });
+    alive = await isDaemonAliveAsync(newConfig);
+    if (alive) break;
+  }
   if (!alive) {
     log(a.red + "     Restart failed. Check logs: " + a.reset + logFile);
     process.exit(1);
@@ -1175,7 +1195,7 @@ function setup(callback) {
 // ==============================
 // Fork the daemon process
 // ==============================
-async function forkDaemon(pin, keepAwake, extraProjects) {
+async function forkDaemon(pin, keepAwake, extraProjects, addCwd) {
   var ip = getLocalIP();
   var hasTls = false;
 
@@ -1197,12 +1217,18 @@ async function forkDaemon(pin, keepAwake, extraProjects) {
     return;
   }
 
-  var slug = generateSlug(cwd, []);
-  var allProjects = [{ path: cwd, slug: slug, addedAt: Date.now() }];
+  var allProjects = [];
+  var usedSlugs = [];
+
+  // Only include cwd if explicitly requested
+  if (addCwd) {
+    var slug = generateSlug(cwd, []);
+    allProjects.push({ path: cwd, slug: slug, addedAt: Date.now() });
+    usedSlugs.push(slug);
+  }
 
   // Add restored projects (from ~/.clayrc)
   if (extraProjects && extraProjects.length > 0) {
-    var usedSlugs = [slug];
     for (var ep = 0; ep < extraProjects.length; ep++) {
       var rp = extraProjects[ep];
       if (rp.path === cwd) continue; // skip if same as cwd
@@ -1247,11 +1273,13 @@ async function forkDaemon(pin, keepAwake, extraProjects) {
   config.pid = child.pid;
   saveConfig(config);
 
-  // Wait for daemon to start
-  await new Promise(function (resolve) { setTimeout(resolve, 800); });
-
-  // Verify daemon is alive
-  var alive = await isDaemonAliveAsync(config);
+  // Wait for daemon to start (retry up to 5 seconds)
+  var alive = false;
+  for (var attempt = 0; attempt < 10; attempt++) {
+    await new Promise(function (resolve) { setTimeout(resolve, 500); });
+    alive = await isDaemonAliveAsync(config);
+    if (alive) break;
+  }
   if (!alive) {
     log(a.red + "Failed to start daemon. Check logs:" + a.reset);
     log(a.dim + logFile + a.reset);
@@ -1260,10 +1288,181 @@ async function forkDaemon(pin, keepAwake, extraProjects) {
     return;
   }
 
+  // Headless mode — print status and exit immediately
+  if (headlessMode) {
+    var protocol = config.tls ? "https" : "http";
+    var url = protocol + "://" + ip + ":" + config.port;
+    console.log("  " + sym.done + "  Daemon started (PID " + config.pid + ")");
+    console.log("  " + sym.done + "  " + url);
+    console.log("  " + sym.done + "  Headless mode — exiting CLI");
+    process.exit(0);
+    return;
+  }
+
   // Show success + QR
   showServerStarted(config, ip);
 }
 
+// ==============================
+// Dev mode — foreground daemon with file watching
+// ==============================
+async function devMode(pin, keepAwake, existingPinHash) {
+  var ip = getLocalIP();
+  var hasTls = false;
+
+  if (useHttps) {
+    var certPaths = ensureCerts(ip);
+    if (certPaths) hasTls = true;
+  }
+
+  var portFree = await isPortFree(port);
+  if (!portFree) {
+    console.log("\x1b[31m[dev] Port " + port + " is already in use.\x1b[0m");
+    process.exit(1);
+    return;
+  }
+
+  var slug = generateSlug(cwd, []);
+  var allProjects = [{ path: cwd, slug: slug, addedAt: Date.now() }];
+
+  // Restore previous projects
+  var rc = loadClayrc();
+  var restorable = (rc.recentProjects || []).filter(function (p) {
+    return p.path !== cwd && fs.existsSync(p.path);
+  });
+  var usedSlugs = [slug];
+  for (var ri = 0; ri < restorable.length; ri++) {
+    var rp = restorable[ri];
+    var rpSlug = generateSlug(rp.path, usedSlugs);
+    usedSlugs.push(rpSlug);
+    allProjects.push({ path: rp.path, slug: rpSlug, title: rp.title || undefined, addedAt: rp.addedAt || Date.now() });
+  }
+
+  var config = {
+    pid: null,
+    port: port,
+    pinHash: existingPinHash || (pin ? generateAuthToken(pin) : null),
+    tls: hasTls,
+    debug: true,
+    keepAwake: keepAwake || false,
+    dangerouslySkipPermissions: dangerouslySkipPermissions,
+    projects: allProjects,
+  };
+
+  ensureConfigDir();
+  saveConfig(config);
+
+  var daemonScript = path.join(__dirname, "..", "lib", "daemon.js");
+  var libDir = path.join(__dirname, "..", "lib");
+  var child = null;
+  var intentionalKill = false;
+  var debounceTimer = null;
+
+  function spawnDaemon() {
+    child = spawn(process.execPath, [daemonScript], {
+      stdio: ["ignore", "inherit", "inherit"],
+      env: Object.assign({}, process.env, {
+        CLAUDE_RELAY_CONFIG: configPath(),
+      }),
+    });
+
+    child.on("exit", function (code) {
+      child = null;
+      if (intentionalKill) {
+        intentionalKill = false;
+        return;
+      }
+      // Exit code 120 = update restart — respawn daemon with current dev code
+      if (code === 120) {
+        console.log("\x1b[36m[dev]\x1b[0m Update restart — respawning daemon...");
+        console.log("");
+        setTimeout(spawnDaemon, 500);
+        return;
+      }
+      // Unexpected exit — auto restart
+      console.log("\x1b[33m[dev] Daemon exited (code " + code + "), restarting...\x1b[0m");
+      setTimeout(spawnDaemon, 500);
+    });
+  }
+
+  function restartDaemon() {
+    intentionalKill = true;
+    if (child) {
+      child.kill("SIGTERM");
+      // Give it a moment to shut down, then spawn
+      setTimeout(spawnDaemon, 300);
+    } else {
+      intentionalKill = false;
+      spawnDaemon();
+    }
+  }
+
+  console.log("\x1b[36m[dev]\x1b[0m Starting relay on port " + port + "...");
+  if (watchMode) {
+    console.log("\x1b[36m[dev]\x1b[0m Watching lib/ for changes (excluding lib/public/)");
+  }
+  console.log("");
+
+  spawnDaemon();
+
+  // Wait for daemon to be ready, then show CLI menu
+  config.pid = child ? child.pid : null;
+  saveConfig(config);
+
+  var daemonReady = false;
+  for (var da = 0; da < 10; da++) {
+    await new Promise(function (resolve) { setTimeout(resolve, 500); });
+    daemonReady = await isDaemonAliveAsync(config);
+    if (daemonReady) break;
+  }
+  if (daemonReady) {
+    showServerStarted(config, ip);
+  }
+
+  // Watch lib/ for server-side file changes (only with --watch)
+  var watcher = null;
+  if (watchMode) {
+    watcher = fs.watch(libDir, { recursive: true }, function (eventType, filename) {
+      if (!filename) return;
+      // Skip client-side files — they're served from disk
+      if (filename.startsWith("public" + path.sep) || filename.startsWith("public/")) return;
+      // Skip non-JS files
+      if (!filename.endsWith(".js")) return;
+
+      if (debounceTimer) clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(function () {
+        console.log("\x1b[36m[dev]\x1b[0m File changed: lib/" + filename);
+        console.log("\x1b[36m[dev]\x1b[0m Restarting...");
+        console.log("");
+        restartDaemon();
+      }, 300);
+    });
+  }
+
+  // Clean exit on Ctrl+C
+  var shuttingDown = false;
+  process.on("SIGINT", function () {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    console.log("\n\x1b[36m[dev]\x1b[0m Shutting down...");
+    if (watcher) watcher.close();
+    if (debounceTimer) clearTimeout(debounceTimer);
+    intentionalKill = true;
+    if (child) {
+      child.kill("SIGTERM");
+      child.on("exit", function () {
+        clearStaleConfig();
+        process.exit(0);
+      });
+      // Force kill after 3s
+      setTimeout(function () { process.exit(0); }, 3000);
+    } else {
+      clearStaleConfig();
+      process.exit(0);
+    }
+  });
+}
+
 // ==============================
 // Restart daemon with TLS enabled
 // ==============================
@@ -1324,9 +1523,12 @@ async function restartDaemonWithTLS(config, callback) {
   newConfig.pid = child.pid;
   saveConfig(newConfig);
 
-  await new Promise(function (resolve) { setTimeout(resolve, 800); });
-
-  var alive = await isDaemonAliveAsync(newConfig);
+  var alive = false;
+  for (var ra = 0; ra < 10; ra++) {
+    await new Promise(function (resolve) { setTimeout(resolve, 500); });
+    alive = await isDaemonAliveAsync(newConfig);
+    if (alive) break;
+  }
   if (!alive) {
     log(sym.warn + "  " + a.yellow + "Failed to restart with HTTPS, falling back to HTTP..." + a.reset);
     // Re-fork without TLS so the server is at least running
@@ -1345,7 +1547,11 @@ async function restartDaemonWithTLS(config, callback) {
     fs.closeSync(logFd2);
     newConfig.pid = child2.pid;
     saveConfig(newConfig);
-    await new Promise(function (resolve) { setTimeout(resolve, 800); });
+    for (var rb = 0; rb < 10; rb++) {
+      await new Promise(function (resolve) { setTimeout(resolve, 500); });
+      var retryAlive = await isDaemonAliveAsync(newConfig);
+      if (retryAlive) break;
+    }
     startDaemonWatcher();
     callback(newConfig);
     return;
@@ -1998,6 +2204,28 @@ var currentVersion = require("../package.json").version;
   var updated = await checkAndUpdate(currentVersion, skipUpdate);
   if (updated) return;
 
+  // Dev mode — foreground daemon with file watching
+  if (_isDev) {
+    var devConfig = loadConfig();
+    var devAlive = devConfig ? await isDaemonAliveAsync(devConfig) : false;
+    if (devAlive) {
+      console.log("\x1b[36m[dev]\x1b[0m Shutting down existing daemon...");
+      await sendIPCCommand(socketPath(), { cmd: "shutdown" });
+      clearStaleConfig();
+      await new Promise(function (resolve) { setTimeout(resolve, 500); });
+    }
+    // First run — go through setup (disclaimer, port, PIN, etc.)
+    if (!devConfig) {
+      setup(function (pin, keepAwake) {
+        devMode(pin, keepAwake, null);
+      });
+    } else {
+      // Reuse existing PIN hash from previous config
+      await devMode(cliPin || null, devConfig.keepAwake || false, devConfig.pinHash || null);
+    }
+    return;
+  }
+
   var config = loadConfig();
   var alive = config ? await isDaemonAliveAsync(config) : false;
 
@@ -2008,6 +2236,17 @@ var currentVersion = require("../package.json").version;
   }
 
   if (alive) {
+    // Headless mode — daemon already running, just report and exit
+    if (headlessMode) {
+      var protocol = config.tls ? "https" : "http";
+      var ip = getLocalIP();
+      var url = protocol + "://" + ip + ":" + config.port;
+      console.log("  " + sym.done + "  Daemon already running (PID " + config.pid + ")");
+      console.log("  " + sym.done + "  " + url);
+      process.exit(0);
+      return;
+    }
+
     // Daemon is running — auto-add cwd if needed, then show menu
     var ip = getLocalIP();
 
@@ -2079,7 +2318,8 @@ var currentVersion = require("../package.json").version;
       if (autoRestorable.length > 0) {
         console.log("  " + sym.done + "  Restoring " + autoRestorable.length + " previous project(s)");
       }
-      await forkDaemon(pin, false, autoRestorable.length > 0 ? autoRestorable : undefined);
+      var hasRestorable = autoRestorable.length > 0;
+      await forkDaemon(pin, false, hasRestorable ? autoRestorable : undefined, !hasRestorable);
     } else {
       setup(function (pin, keepAwake) {
         if (dangerouslySkipPermissions && !pin) {
@@ -2088,6 +2328,7 @@ var currentVersion = require("../package.json").version;
           process.exit(1);
           return;
         }
+
         // Check ~/.clayrc for previous projects to restore
         var rc = loadClayrc();
         var restorable = (rc.recentProjects || []).filter(function (p) {
@@ -2096,13 +2337,13 @@ var currentVersion = require("../package.json").version;
 
         if (restorable.length > 0) {
           promptRestoreProjects(restorable, function (selected) {
-            forkDaemon(pin, keepAwake, selected);
+            forkDaemon(pin, keepAwake, selected, false);
           });
         } else {
           log(sym.bar);
           log(sym.end + "  " + a.dim + "Starting relay..." + a.reset);
           log("");
-          forkDaemon(pin, keepAwake);
+          forkDaemon(pin, keepAwake, undefined, true);
         }
       });
     }