@remotego/remotego 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# remotego
+
+Expose any CLI tool as a public web terminal via tunnel.
+
+## Install
+
+```bash
+npm install -g @zhanju/remotego
+```
+
+## Usage
+
+```bash
+remotego <command> [command-args...] [options]
+```
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--port <port>` | Port to listen on | `7681` |
+| `--cwd <dir>` | Working directory for the command | Current directory |
+| `--help, -h` | Show help | |
+
+### Examples
+
+```bash
+# Mirror Claude Code
+remotego claude
+
+# Mirror a bash shell
+remotego bash
+
+# Mirror Python REPL
+remotego python3 -i
+
+# Mirror vim editor
+remotego vim
+
+# Custom port
+remotego --port 9000 node
+
+# Pass flags to the command (use -- to separate)
+remotego -- git log --oneline
+```
+
+## How It Works
+
+1. Spawns the given command in a PTY (pseudo-terminal)
+2. Starts a local HTTP server with a browser-based terminal (xterm.js)
+3. Creates a public tunnel via localhost.run for remote access
+4. Opens the browser automatically
+
+### Security
+
+- A random session UUID is generated on each start
+- The session ID is embedded in the URL — only holders of the URL can connect
+- Clients must authenticate within 5 seconds of connecting
+
+## Claude Code Plugin
+
+This project also works as a Claude Code plugin. Install it and use the `/remoting` slash command to mirror your Claude Code session in a browser.
+
+## License
+
+MIT

package/bin/remotego.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+// remotego - Expose any CLI tool as a public web terminal
+// Usage: remotego <command> [args...] [--port <port>] [--cwd <dir>]
+
+import { spawn } from 'child_process';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Parse arguments: everything before flags is the command + its args
+function parseArgs(argv) {
+  const cmd = [];
+  const flags = {};
+  let i = 0;
+
+  // Collect command and args until we hit a --flag
+  while (i < argv.length && !argv[i].startsWith('--')) {
+    cmd.push(argv[i]);
+    i++;
+  }
+
+  // Parse flags
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === '--port' && argv[i + 1]) {
+      flags.port = argv[++i];
+    } else if (arg === '--cwd' && argv[i + 1]) {
+      flags.cwd = argv[++i];
+    } else if (arg === '--help' || arg === '-h') {
+      printHelp();
+      process.exit(0);
+    } else if (arg === '--') {
+      // Everything after -- is command args
+      i++;
+      while (i < argv.length) {
+        cmd.push(argv[i]);
+        i++;
+      }
+    } else {
+      console.error(`Unknown option: ${arg}`);
+      printHelp();
+      process.exit(1);
+    }
+    i++;
+  }
+
+  return { cmd, flags };
+}
+
+function printHelp() {
+  console.log(`
+remotego - Expose any CLI tool as a public web terminal
+
+Usage:
+  remotego <command> [command-args...] [options]
+  remotego --port 9000 --cwd ~/project vim
+  remotego bash
+  remotego python3 -i
+  remotego claude
+
+Options:
+  --port <port>   Port to listen on (default: 7681)
+  --cwd <dir>     Working directory for the command (default: current dir)
+  --help, -h      Show this help message
+
+Examples:
+  remotego claude              # Mirror Claude Code
+  remotego vim                 # Mirror vim editor
+  remotego bash                # Mirror a bash shell
+  remotego python3 -i          # Mirror Python REPL
+  remotego --port 9000 node    # Mirror Node.js REPL on port 9000
+  remotego -- --flagged-arg    # Use -- to separate flags from command args
+`);
+}
+
+const { cmd, flags } = parseArgs(process.argv.slice(2));
+
+if (cmd.length === 0) {
+  console.error('Error: No command specified.\n');
+  printHelp();
+  process.exit(1);
+}
+
+const serverDir = resolve(__dirname, '..', 'server');
+
+// Build environment for server.js
+const env = {
+  ...process.env,
+  REMOTE_CMD: cmd[0],
+  REMOTE_ARGS: JSON.stringify(cmd.slice(1)),
+  REMOTE_CWD: flags.cwd ? resolve(flags.cwd) : process.cwd(),
+};
+
+if (flags.port) {
+  env.PORT = flags.port;
+}
+
+// Install server dependencies if needed
+import { existsSync } from 'fs';
+if (!existsSync(resolve(serverDir, 'node_modules'))) {
+  console.log('Installing dependencies...');
+  const install = spawn('npm', ['install'], { cwd: serverDir, stdio: 'inherit' });
+  install.on('exit', (code) => {
+    if (code !== 0) {
+      console.error('Failed to install dependencies');
+      process.exit(1);
+    }
+    startServer();
+  });
+} else {
+  startServer();
+}
+
+function startServer() {
+  const server = spawn('node', [resolve(serverDir, 'server.js')], {
+    cwd: serverDir,
+    env,
+    stdio: 'inherit',
+  });
+
+  server.on('exit', (code) => {
+    process.exit(code || 0);
+  });
+
+  process.on('SIGINT', () => {
+    server.kill('SIGINT');
+  });
+
+  process.on('SIGTERM', () => {
+    server.kill('SIGTERM');
+  });
+}

package/commands/remoting-stop.md

@@ -0,0 +1,14 @@
+---
+description: "Stop the running remoting browser mirror session"
+allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/remoting-stop.sh:*)"]
+---
+
+# /remoting-stop
+
+Execute the stop script:
+
+```!
+"${CLAUDE_PLUGIN_ROOT}/scripts/remoting-stop.sh"
+```
+
+Then tell the user: The remoting session runs in the foreground. Press Ctrl+C to stop it, or type /exit in Claude Code.

package/commands/remoting.md

@@ -0,0 +1,19 @@
+---
+description: "Mirror your Claude Code terminal in a browser for remote viewing and interaction"
+argument-hint: "[port]"
+allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/remoting.sh:*)"]
+---
+
+# /remoting - Browser Terminal Mirror
+
+Execute the remoting script to launch a browser mirror of this terminal:
+
+```!
+"${CLAUDE_PLUGIN_ROOT}/scripts/remoting.sh" $ARGUMENTS
+```
+
+If the output contains `MISSING:`, tell the user which dependency is missing and how to install it, then stop.
+If the output contains `ERROR:`, show the error to the user and suggest troubleshooting steps.
+Otherwise, the script will print local and public URLs — share these with anyone who needs to view the terminal.
+
+To stop the session: press Ctrl+C in the terminal, or type /exit in Claude Code.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@remotego/remotego",
+  "version": "1.0.0",
+  "description": "Expose any CLI tool as a public web terminal via tunnel",
+  "bin": {
+    "remotego": "bin/remotego.js"
+  },
+  "files": [
+    "bin/",
+    "server/",
+    "scripts/",
+    "commands/",
+    "README.md"
+  ],
+  "keywords": [
+    "terminal",
+    "remote",
+    "tunnel",
+    "pty",
+    "web-terminal",
+    "cli"
+  ],
+  "author": "zhanju",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "homepage": "https://github.com/topcheer/claude-remoting#readme",
+  "bugs": {
+    "url": "https://github.com/topcheer/claude-remoting/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/topcheer/claude-remoting.git",
+    "directory": "."
+  }
+}

package/scripts/remoting-stop.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+# remoting-stop.sh - The remoting session runs in foreground
+# To stop: press Ctrl+C or exit Claude Code
+
+echo "The remoting session runs in the foreground."
+echo "To stop: press Ctrl+C in the terminal, or type /exit in Claude Code."
+echo "STOPPED"

package/scripts/remoting.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# remoting.sh - Mirror a CLI tool in a browser (Claude plugin default: claude)
+# Usage: remoting.sh [port]
+
+set -euo pipefail
+
+PORT="${1:-7681}"
+
+# Check Node.js
+if ! command -v node &>/dev/null; then
+  echo "MISSING:node:Visit https://nodejs.org/ to install"
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SERVER_DIR="$(dirname "$SCRIPT_DIR")/server"
+
+# Install dependencies if needed
+if [ ! -d "$SERVER_DIR/node_modules" ]; then
+  echo "Installing dependencies..."
+  (cd "$SERVER_DIR" && npm install)
+fi
+
+# Start server in foreground -- replaces this shell process
+# Default command is 'claude' for the Claude plugin
+# Save caller's cwd so the command starts in the right directory
+REMOTE_CWD="$(pwd)"
+cd "$SERVER_DIR"
+exec env PORT="$PORT" REMOTE_CMD="claude" REMOTE_ARGS="[]" REMOTE_CWD="$REMOTE_CWD" node server.js

package/server/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "remoting-server",
+  "version": "1.0.0",
+  "description": "WebSocket PTY server for remotego",
+  "main": "server.js",
+  "type": "module",
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "node-pty": "^1.2.0-beta.12",
+    "ws": "^8.18.0",
+    "express": "^4.21.2"
+  }
+}

package/server/public/index.html

@@ -0,0 +1,203 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Remotego</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/xterm@5.3.0/css/xterm.css" />
+  <script src="https://cdn.jsdelivr.net/npm/xterm@5.3.0/lib/xterm.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/xterm-addon-fit@0.8.0/lib/xterm-addon-fit.js"></script>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    body {
+      background: #0d1117;
+      height: 100vh;
+      display: flex;
+      flex-direction: column;
+    }
+    #terminal {
+      flex: 1;
+      padding: 4px;
+    }
+    #error-container {
+      color: #da3633;
+      padding: 20px;
+      font-family: system-ui, sans-serif;
+      font-size: 16px;
+      display: none;
+    }
+    .status {
+      position: fixed;
+      top: 10px;
+      right: 10px;
+      padding: 6px 12px;
+      border-radius: 4px;
+      font-size: 12px;
+      font-family: system-ui, sans-serif;
+      z-index: 100;
+    }
+    .status.connected {
+      background: #238636;
+      color: white;
+    }
+    .status.disconnected {
+      background: #da3633;
+      color: white;
+    }
+    .status.connecting {
+      background: #d29922;
+      color: white;
+    }
+  </style>
+</head>
+<body>
+  <div id="status" class="status connecting">Connecting...</div>
+  <div id="error-container"></div>
+  <div id="terminal"></div>
+
+  <script>
+    const statusEl = document.getElementById('status');
+    const terminalEl = document.getElementById('terminal');
+    const errorEl = document.getElementById('error-container');
+
+    // Extract session ID from URL
+    const urlParams = new URLSearchParams(window.location.search);
+    const sessionId = urlParams.get('session');
+
+    if (!sessionId) {
+      errorEl.textContent = 'Error: No session ID in URL. Use the URL shown in the terminal.';
+      errorEl.style.display = 'block';
+      statusEl.textContent = 'No Session';
+      statusEl.className = 'status disconnected';
+      throw new Error('No session ID');
+    }
+
+    // Initialize xterm.js
+    const terminal = new Terminal({
+      cursorBlink: true,
+      fontSize: 14,
+      fontFamily: 'Menlo, Monaco, "Courier New", monospace',
+      theme: {
+        background: '#0d1117',
+        foreground: '#c9d1d9',
+        cursor: '#c9d1d9',
+        black: '#484f58',
+        red: '#ff7b72',
+        green: '#3fb950',
+        yellow: '#d29922',
+        blue: '#58a6ff',
+        magenta: '#bc8cff',
+        cyan: '#39c5cf',
+        white: '#b1bac4',
+        brightBlack: '#6e7681',
+        brightRed: '#ffa198',
+        brightGreen: '#56d364',
+        brightYellow: '#e3b341',
+        brightBlue: '#79c0ff',
+        brightMagenta: '#d2a8ff',
+        brightCyan: '#56d4dd',
+        brightWhite: '#f0f6fc',
+      },
+    });
+
+    terminal.open(terminalEl);
+
+    // Fit addon for auto-sizing
+    let fitAddon = null;
+    try {
+      fitAddon = new FitAddon.FitAddon();
+      terminal.loadAddon(fitAddon);
+      fitAddon.fit();
+    } catch (_) {}
+
+    // WebSocket connection
+    const wsProtocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const wsUrl = `${wsProtocol}//${window.location.host}/ws`;
+    let activeWs = null;
+    let dead = false;
+
+    function connect() {
+      if (dead) return;
+
+      const ws = new WebSocket(wsUrl);
+
+      ws.onopen = () => {
+        ws.send(JSON.stringify({ type: 'auth', sessionId: sessionId }));
+      };
+
+      ws.onmessage = (event) => {
+        const msg = JSON.parse(event.data);
+
+        if (msg.type === 'auth_ok') {
+          activeWs = ws;
+          statusEl.textContent = 'Connected';
+          statusEl.className = 'status connected';
+          terminal.focus();
+          if (fitAddon) fitAddon.fit();
+          // Send initial terminal size to server PTY
+          if (terminal.cols && terminal.rows) {
+            ws.send(JSON.stringify({ type: 'resize', cols: terminal.cols, rows: terminal.rows }));
+          }
+          return;
+        }
+
+        if (msg.type === 'data') {
+          terminal.write(msg.data);
+          return;
+        }
+
+        if (msg.type === 'history') {
+          terminal.write(msg.data);
+          return;
+        }
+
+        if (msg.type === 'exit') {
+          terminal.write('\r\n\n[Session ended]');
+          statusEl.textContent = 'Session ended';
+          statusEl.className = 'status disconnected';
+          dead = true;
+          return;
+        }
+      };
+
+      ws.onclose = (event) => {
+        if (ws === activeWs) activeWs = null;
+        if (event.code === 4003 || event.code === 4001) {
+          statusEl.textContent = 'Session expired';
+          statusEl.className = 'status disconnected';
+          dead = true;
+          return;
+        }
+        statusEl.textContent = 'Reconnecting...';
+        statusEl.className = 'status connecting';
+        setTimeout(connect, 3000);
+      };
+
+      ws.onerror = () => {
+        // onclose handles reconnection
+      };
+    }
+
+    // Register input handler once, outside connect()
+    terminal.onData((data) => {
+      if (activeWs && activeWs.readyState === WebSocket.OPEN) {
+        activeWs.send(JSON.stringify({ type: 'input', data }));
+      }
+    });
+
+    connect();
+
+    // Handle window resize → notify PTY
+    window.addEventListener('resize', () => {
+      if (fitAddon) fitAddon.fit();
+      if (activeWs && activeWs.readyState === WebSocket.OPEN && terminal.cols && terminal.rows) {
+        activeWs.send(JSON.stringify({ type: 'resize', cols: terminal.cols, rows: terminal.rows }));
+      }
+    });
+  </script>
+</body>
+</html>

package/server/server.js

@@ -0,0 +1,256 @@
+import { spawn } from 'node-pty';
+import { WebSocketServer } from 'ws';
+import express from 'express';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { createServer } from 'http';
+import { randomUUID } from 'crypto';
+import { execFile } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const PORT = process.env.PORT || 7681;
+const SESSION_ID = randomUUID();
+const clients = new Set();
+
+// Command to run in PTY — configurable via env vars
+const REMOTE_CMD = process.env.REMOTE_CMD || 'claude';
+const REMOTE_ARGS = process.env.REMOTE_ARGS
+  ? JSON.parse(process.env.REMOTE_ARGS)
+  : [];
+
+// Buffer all PTY output so new clients can catch up
+const outputBuffer = [];
+
+// ============================================================
+// HTTP + WebSocket Server
+// ============================================================
+const app = express();
+app.use(express.static(join(__dirname, 'public')));
+const server = createServer(app);
+const wss = new WebSocketServer({ server, path: '/ws' });
+
+// ============================================================
+// WebSocket: Auth + Input forwarding
+// ============================================================
+wss.on('connection', (ws) => {
+  let authenticated = false;
+  const authTimeout = setTimeout(() => {
+    if (!authenticated) {
+      ws.close(4001, 'Auth timeout');
+    }
+  }, 5000);
+
+  ws.on('message', (message) => {
+    try {
+      const msg = JSON.parse(message);
+
+      // First message must be auth
+      if (!authenticated) {
+        if (msg.type === 'auth' && msg.sessionId === SESSION_ID) {
+          authenticated = true;
+          clearTimeout(authTimeout);
+          clients.add(ws);
+          ws.send(JSON.stringify({ type: 'auth_ok' }));
+          // Send all cached output to the new client
+          if (outputBuffer.length > 0) {
+            const history = JSON.stringify({ type: 'history', data: outputBuffer.join('') });
+            ws.send(history);
+          }
+        } else {
+          ws.close(4003, 'Invalid session');
+        }
+        return;
+      }
+
+      // After auth: forward input to PTY
+      if (msg.type === 'input') {
+        ptyProcess.write(msg.data);
+      }
+
+      // Handle resize from browser → update PTY size
+      if (msg.type === 'resize') {
+        ptyCols = msg.cols || 120;
+        ptyRows = msg.rows || 36;
+        try { ptyProcess.resize(ptyCols, ptyRows); } catch (_) {}
+      }
+    } catch (_) {
+      // Ignore malformed messages
+    }
+  });
+
+  ws.on('close', () => {
+    clients.delete(ws);
+    clearTimeout(authTimeout);
+  });
+
+  ws.on('error', () => {
+    clients.delete(ws);
+    clearTimeout(authTimeout);
+  });
+});
+
+// ============================================================
+// Singleton PTY: wraps the configured command
+// ============================================================
+// Track the largest viewport so PTY matches browser
+let ptyCols = 120;
+let ptyRows = 36;
+
+const ptyProcess = spawn(REMOTE_CMD, REMOTE_ARGS, {
+  name: 'xterm-256color',
+  cols: ptyCols,
+  rows: ptyRows,
+  cwd: process.env.REMOTE_CWD || process.cwd(),
+  env: { ...process.env },
+});
+
+// PTY output → local terminal + all WebSocket clients
+ptyProcess.onData((data) => {
+  // Cache output for new clients
+  outputBuffer.push(data);
+
+  // Local terminal
+  process.stdout.write(data);
+
+  // Broadcast to all authenticated browser clients
+  const msg = JSON.stringify({ type: 'data', data });
+  for (const client of clients) {
+    if (client.readyState === 1) { // WebSocket.OPEN
+      client.send(msg);
+    }
+  }
+});
+
+// PTY exit → cleanup and exit
+ptyProcess.onExit(({ exitCode }) => {
+  for (const client of clients) {
+    if (client.readyState === 1) {
+      client.send(JSON.stringify({ type: 'exit', code: exitCode }));
+      client.close();
+    }
+  }
+  cleanup();
+  process.exit(exitCode || 0);
+});
+
+// ============================================================
+// Local terminal: stdin raw mode → PTY
+// ============================================================
+if (process.stdin.isTTY) {
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (data) => {
+    ptyProcess.write(data);
+  });
+}
+
+// Note: PTY resize is controlled by browser viewport, not local terminal
+
+// ============================================================
+// Orphan detection: if parent dies, we should exit too
+// ============================================================
+setInterval(() => {
+  try {
+    process.kill(process.ppid, 0);
+  } catch {
+    // Parent process is dead — we're an orphan
+    ptyProcess.kill();
+    cleanup();
+    process.exit(0);
+  }
+}, 2000);
+
+// ============================================================
+// Signal handlers
+// ============================================================
+process.on('SIGINT', () => {
+  ptyProcess.kill('SIGINT');
+});
+
+process.on('SIGTERM', () => {
+  ptyProcess.kill();
+  cleanup();
+  process.exit(0);
+});
+
+// ============================================================
+// Cleanup
+// ============================================================
+function cleanup() {
+  try { process.stdin.setRawMode(false); } catch (_) {}
+  process.stdin.pause();
+  for (const client of clients) {
+    client.close();
+  }
+  server.close();
+}
+
+// ============================================================
+// Start server + auto-open browser + public tunnel
+// ============================================================
+server.listen(PORT, () => {
+  const localUrl = `http://localhost:${PORT}?session=${SESSION_ID}`;
+
+  // Show local URL in terminal
+  process.stderr.write(`\n[remoting] Command: ${REMOTE_CMD} ${REMOTE_ARGS.join(' ')}\n`);
+  process.stderr.write(`[remoting] ${localUrl}\n`);
+
+  // Start localhost.run tunnel for public access
+  // Browser opens only after tunnel is ready
+  startTunnel(localUrl);
+});
+
+function startTunnel(localUrl) {
+  const tunnel = spawn('ssh', [
+    '-o', 'StrictHostKeyChecking=no',
+    '-R', `80:localhost:${PORT}`,
+    'nokey@localhost.run',
+  ], {
+    name: 'xterm-256color',
+    cols: 120,
+    rows: 24,
+  });
+
+  let publicUrl = '';
+  let browserOpened = false;
+
+  tunnel.onData((data) => {
+    const text = data.toString();
+
+    // Match: "xxxxx.lhr.life tunneled with tls termination, https://xxxxx.lhr.life"
+    const match = text.match(/tunneled with tls termination,\s*(https:\/\/\S+)/);
+    if (match && !publicUrl) {
+      publicUrl = match[1];
+      const fullUrl = `${publicUrl}?session=${SESSION_ID}`;
+      process.stderr.write(`[remoting] ${fullUrl}\n\n`);
+
+      // Open browser with public URL (only once, after tunnel is ready)
+      if (!browserOpened) {
+        browserOpened = true;
+        const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
+        execFile(cmd, [fullUrl], (err) => {
+          if (err) {
+            process.stderr.write(`[remoting] Could not auto-open browser. Open manually: ${fullUrl}\n`);
+          }
+        });
+      }
+    }
+  });
+
+  tunnel.onExit(({ exitCode }) => {
+    if (!browserOpened) {
+      // Tunnel failed — fall back to opening local URL
+      process.stderr.write(`[remoting] Tunnel failed (code ${exitCode}). Opening local URL instead.\n`);
+      const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
+      execFile(cmd, [localUrl]);
+    }
+  });
+
+  // Clean up tunnel on exit
+  process.on('exit', () => {
+    try { tunnel.kill(); } catch (_) {}
+  });
+}