claude-relay 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# claude-relay
+
+Run `npx claude-relay` in any directory. Access Claude Code on that directory from any device.
+
+```
+$ cd ~/my-project
+$ npx claude-relay
+
+  Claude Relay running at http://100.64.1.5:3456
+  Project: my-project
+  Directory: /Users/you/my-project
+
+  Open the URL on your phone to start chatting.
+```
+
+## Why?
+
+Yes, 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.
+
+**claude-relay** gives you the real thing. One command in any directory — even `~` — 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.
+
+## How it works
+
+claude-relay spawns `claude` CLI processes and bridges them to a web UI over WebSocket. Your browser talks to the relay, the relay talks to Claude Code. Sessions persist across reconnects.
+
+```
+Browser (any device)  <-->  claude-relay (your machine)  <-->  claude CLI
+        WebSocket                HTTP + WS                    stdin/stdout
+```
+
+## Features
+
+- **One command** — `npx claude-relay` and you're live
+- **Mobile-first UI** — designed for phones and tablets, works everywhere
+- **Multi-session** — run multiple Claude Code sessions, switch between them
+- **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
+- **Zero config** — no API keys, no setup. Uses your local `claude` installation
+
+## Requirements
+
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+- Node.js 18+
+
+## Install
+
+```bash
+# Run directly (no install needed)
+npx claude-relay
+
+# Or install globally
+npm install -g claude-relay
+claude-relay
+```
+
+## Usage
+
+```bash
+# Start in current directory
+npx claude-relay
+
+# Custom port
+npx claude-relay -p 8080
+```
+
+Then open the URL on any device connected to the same network.
+
+### Remote access with Tailscale
+
+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 — coffee shop, commute, couch.
+
+## Limitations
+
+- Permission prompts (tool approval) are not yet relayed to the browser
+- Image/file attachments from the browser are not yet supported
+- Session persistence is unstable
+
+These are planned for future releases. Contributions welcome.
+
+## Security
+
+**claude-relay has no built-in authentication or encryption.** Anyone with access to the URL gets full Claude Code access to your machine — 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.
+
+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.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+const os = require("os");
+const { createServer } = require("../lib/server");
+
+const args = process.argv.slice(2);
+let port = 3456;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "-p" || args[i] === "--port") {
+    port = parseInt(args[i + 1], 10);
+    if (isNaN(port)) {
+      console.error("Invalid port number");
+      process.exit(1);
+    }
+    i++;
+  } else if (args[i] === "-h" || args[i] === "--help") {
+    console.log("Usage: claude-relay [-p|--port <port>]");
+    console.log("");
+    console.log("Options:");
+    console.log("  -p, --port <port>  Port to listen on (default: 3456)");
+    process.exit(0);
+  }
+}
+
+const cwd = process.cwd();
+
+function getLocalIP() {
+  const interfaces = os.networkInterfaces();
+
+  // Prefer Tailscale IP
+  for (const [name, addrs] of Object.entries(interfaces)) {
+    if (/^(tailscale|utun)/.test(name)) {
+      for (const addr of addrs) {
+        if (addr.family === "IPv4" && !addr.internal && addr.address.startsWith("100.")) {
+          return addr.address;
+        }
+      }
+    }
+  }
+
+  // Check all interfaces for Tailscale CGNAT range (100.64.0.0/10)
+  for (const addrs of Object.values(interfaces)) {
+    for (const addr of addrs) {
+      if (addr.family === "IPv4" && !addr.internal && addr.address.startsWith("100.")) {
+        return addr.address;
+      }
+    }
+  }
+
+  // Fall back to LAN IP
+  for (const addrs of Object.values(interfaces)) {
+    for (const addr of addrs) {
+      if (addr.family === "IPv4" && !addr.internal) {
+        return addr.address;
+      }
+    }
+  }
+
+  return "localhost";
+}
+
+function confirm(callback) {
+  const readline = require("readline");
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  console.log("");
+  console.log("  \x1b[1;33m⚠  WARNING — READ BEFORE CONTINUING\x1b[0m");
+  console.log("");
+  console.log("  claude-relay has \x1b[1mno built-in authentication or encryption.\x1b[0m");
+  console.log("  Anyone with access to the URL gets \x1b[1mfull Claude Code access\x1b[0m to");
+  console.log("  this machine — reading, writing, and executing files with your");
+  console.log("  user permissions.");
+  console.log("");
+  console.log("  We strongly recommend using a private network layer such as");
+  console.log("  Tailscale, WireGuard, or a VPN.");
+  console.log("");
+  console.log("  If you choose to expose it beyond your private network, that's");
+  console.log("  your call. \x1b[1mEntirely at your own risk.\x1b[0m The authors assume no");
+  console.log("  responsibility for any damage, data loss, or security incidents.");
+  console.log("");
+
+  rl.question("  Do you understand and accept? (type \x1b[1my\x1b[0m to continue): ", (answer) => {
+    rl.close();
+    if (/^(y|yes)$/i.test(answer.trim())) {
+      callback();
+    } else {
+      console.log("\n  Aborted.\n");
+      process.exit(0);
+    }
+  });
+}
+
+function start() {
+  const server = createServer(cwd);
+
+  server.on("error", (err) => {
+    if (err.code === "EADDRINUSE") {
+      console.error(`\n  Port ${port} is already in use.`);
+      console.error(`  Run with a different port: claude-relay -p <port>`);
+      console.error(`  Or kill the existing process: lsof -ti :${port} | xargs kill\n`);
+    } else {
+      console.error(`\n  Server error: ${err.message}\n`);
+    }
+    process.exit(1);
+  });
+
+  server.listen(port, () => {
+    const ip = getLocalIP();
+    const project = require("path").basename(cwd);
+    console.log("");
+    console.log(`  Claude Relay running at http://${ip}:${port}`);
+    console.log(`  Project: ${project}`);
+    console.log(`  Directory: ${cwd}`);
+    console.log("");
+    console.log("  Open the URL on your phone to start chatting.");
+    console.log("");
+  });
+}
+
+confirm(start);