anyagent-bridge 0.5.0 → 0.7.0

package/README.md

@@ -7,15 +7,20 @@ Control your local computer's terminal — and **any** CLI AI coding agent you'v
 ## Quick start
 
 ```bash
-# Fastest — run it with one command (Node 18+):
+# New here? A guided, first-timer setup (checks prerequisites, helps you go mobile):
+npx anyagent-bridge setup
+
+# Or run it directly (Node 18+):
 npx anyagent-bridge
 
 # Or self-host with Docker:
 docker compose up -d --build && docker compose logs bridge
 ```
 
-Open the printed URL, paste the access token from the banner, and you're in. Full
-install paths (npx · from source · Docker) and per-OS notes are in
+Open the printed URL, paste the access token from the banner, and you're in. To open
+it on a phone or another PC, click **"📱 Connect a device"** in the top bar and scan
+the QR. New to all this? Start with **[docs/GETTING-STARTED.md](docs/GETTING-STARTED.md)**.
+Full install paths (npx · from source · Docker) and per-OS notes are in
 **[docs/INSTALL.md](docs/INSTALL.md)**; read **[docs/SECURITY.md](docs/SECURITY.md)**
 before exposing the bridge beyond localhost, and
 **[docs/WALKTHROUGH.md](docs/WALKTHROUGH.md)** for a guided tour.
@@ -34,6 +39,7 @@ before exposing the bridge beyond localhost, and
 - Persistent sessions that survive reconnects, with automatic PTY respawn and backoff.
 - Heartbeat + dead-connection detection so stale viewers get cleaned up.
 - File management API: browse, read, write, rename, move, delete, upload, download — all behind a path whitelist.
+- Add projects by **browsing folders** in the UI (the 📁 Projects button) — no typing full paths.
 - Crash guards (uncaught exceptions, signals) so the server stays up.
 - Constant-time token comparison and basic rate limiting.
 - Optional **login**: Google/GitHub OAuth, TOTP 2FA, and signed expiring sessions on top of the token (Stage 3).

package/bin/anyagent-bridge.js

@@ -28,6 +28,7 @@ function printHelp() {
     '',
     'Usage:',
     '  anyagent-bridge [options]',
+    '  anyagent-bridge setup            Guided, first-timer setup (recommended to start).',
     '',
     'Options:',
     '  -p, --port <n>           Port to listen on (default 3001).',
@@ -53,6 +54,11 @@ function fail(msg) {
   process.exit(1);
 }
 
+// Subcommand: `anyagent-bridge setup` launches the guided first-timer wizard.
+// Anything else is the normal flag-parse + boot below.
+if (argv[0] === 'setup') {
+  require(path.join(__dirname, 'setup.js'));
+} else {
 for (let i = 0; i < argv.length; i++) {
   let arg = argv[i];
   // Support the `--flag=value` form for long options. Splitting it out here also
@@ -125,3 +131,4 @@ for (let i = 0; i < argv.length; i++) {
 // Boot the server in-process. ROOT inside the server resolves relative to its own
 // __dirname, so config.json and .data live alongside the installed package.
 require(path.join(__dirname, '..', 'server', 'index.js'));
+}

package/bin/setup.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * anyagent-bridge setup — a friendly, first-timer guided launcher.
+ *
+ * Invoked as `npx anyagent-bridge setup` (the launcher dispatches the `setup`
+ * subcommand here). It asks a few plain questions, checks prerequisites, helps
+ * you pick where you'll open the bridge (this computer / same Wi-Fi / phone over
+ * the internet), then boots the normal server with the matching settings — it
+ * only sets the same PORT / HOST / BRIDGE_* env vars the launcher already uses,
+ * so nothing here changes how the server runs. The scannable phone QR lives in
+ * the browser UI ("Connect a device" → Phone); this wizard points you to it.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const crypto = require('crypto');
+const readline = require('readline');
+const pkg = require('../package.json');
+
+// ── tiny ANSI helpers (no dependency) ─────────────────────────────────────────
+const useColor = process.stdout.isTTY && process.env.NO_COLOR === undefined;
+const c = (code, s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+const bold = (s) => c('1', s);
+const dim = (s) => c('2', s);
+const cyan = (s) => c('36', s);
+const green = (s) => c('32', s);
+const yellow = (s) => c('33', s);
+const out = (s = '') => process.stdout.write(s + '\n');
+const rule = () => out(dim('─'.repeat(63)));
+
+// ── prerequisite helpers ──────────────────────────────────────────────────────
+// Cross-platform "is this command on PATH?" without spawning the command itself.
+function onPath(bin) {
+  const exts = process.platform === 'win32'
+    ? (process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';')
+    : [''];
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const p = path.join(dir, bin + ext);
+      try { fs.accessSync(p, fs.constants.X_OK); return true; } catch (_) { /* keep looking */ }
+    }
+  }
+  return false;
+}
+
+function firstLanIPv4() {
+  const ifaces = os.networkInterfaces();
+  for (const name of Object.keys(ifaces)) {
+    for (const ni of ifaces[name] || []) {
+      if (ni.family === 'IPv4' && !ni.internal) return ni.address;
+    }
+  }
+  return null;
+}
+
+// ── interactive prompt (degrades gracefully without a TTY) ─────────────────────
+let rl = null;
+function ask(question, choices) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) { resolve(choices ? choices[0].key : ''); return; }
+    if (!rl) rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => resolve(answer.trim()));
+  });
+}
+
+async function pick(title, choices) {
+  out();
+  out(bold(title));
+  for (const ch of choices) out(`  ${cyan(ch.key)}) ${ch.label}${ch.hint ? dim('  — ' + ch.hint) : ''}`);
+  if (!process.stdin.isTTY) {
+    out(dim('  (no interactive terminal — defaulting to option ' + choices[0].key + ')'));
+    return choices[0];
+  }
+  for (;;) {
+    const a = (await ask(`${dim('choose')} [${choices[0].key}]: `)) || choices[0].key;
+    const found = choices.find((ch) => ch.key === a.toLowerCase());
+    if (found) return found;
+    out(yellow(`  "${a}" isn't one of the choices — try again.`));
+  }
+}
+
+async function confirm(question, def = true) {
+  if (!process.stdin.isTTY) return def;
+  const a = (await ask(`${question} ${dim(def ? '[Y/n]' : '[y/N]')} `)).toLowerCase();
+  if (!a) return def;
+  return a.startsWith('y');
+}
+
+// ── main flow ─────────────────────────────────────────────────────────────────
+(async function main() {
+  out();
+  rule();
+  out('  ' + bold('AnyAgent Bridge') + dim(`  ·  setup  ·  v${pkg.version}`));
+  out('  ' + dim('Run your terminal + AI agents from a browser, phone, or another PC.'));
+  rule();
+
+  // 1) prerequisites -----------------------------------------------------------
+  out();
+  out(bold('1. Checking what you have'));
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  out(`  ${nodeMajor >= 18 ? green('✓') : yellow('!')} Node.js ${process.version}` +
+      (nodeMajor >= 18 ? '' : yellow('  (needs 18+; please upgrade)')));
+  const agents = [
+    { id: 'claude', label: 'Claude Code (claude)' },
+    { id: 'codex', label: 'Codex (codex)' },
+  ].map((a) => ({ ...a, found: onPath(a.id) }));
+  for (const a of agents) {
+    out(`  ${a.found ? green('✓') : dim('·')} ${a.label}${a.found ? '' : dim('  — not found on PATH')}`);
+  }
+  if (!agents.some((a) => a.found)) {
+    out();
+    out(yellow('  No AI agent CLI was found. The bridge still runs (you get a plain shell),'));
+    out(yellow('  but to launch an agent install one first, e.g. Claude Code:'));
+    out('    ' + cyan('npm install -g @anthropic-ai/claude-code') + dim('   then run `claude` once to log in.'));
+    out(dim('  (Any CLI works — register it under "agents" in config.json.)'));
+  }
+
+  // 2) where will you open it? --------------------------------------------------
+  const where = await pick('2. Where do you want to open the bridge?', [
+    { key: '1', label: 'This computer', hint: "open it in this machine's browser" },
+    { key: '2', label: 'Another device on the same Wi-Fi', hint: 'a phone or PC on your network' },
+    { key: '3', label: 'Your phone / anywhere over the internet', hint: 'via a free tunnel' },
+  ]);
+
+  // settings we will hand to the server (same env the launcher uses)
+  const port = process.env.PORT || '3001';
+  const token = process.env.BRIDGE_AUTH_TOKEN || crypto.randomBytes(32).toString('hex');
+  let host = '127.0.0.1';
+  let tunnelProvider = null;
+  const nextSteps = [];
+
+  if (where.key === '1') {
+    host = '127.0.0.1';
+    nextSteps.push(`Open ${cyan(`http://127.0.0.1:${port}/?token=…`)} in your browser (the full link with the token prints below).`);
+    nextSteps.push(`Only this computer can reach it. Nothing is exposed to your network or the internet.`);
+  } else if (where.key === '2') {
+    host = '0.0.0.0';
+    const ip = firstLanIPv4();
+    nextSteps.push(ip
+      ? `On the other device's browser, go to ${cyan(`http://${ip}:${port}/`)} and paste the access token.`
+      : `Find this computer's local IP (e.g. ${dim('System Settings → Network')}), then visit ${cyan(`http://<that-ip>:${port}/`)} on the other device.`);
+    nextSteps.push(`${yellow('Heads up:')} on your Wi-Fi the access token is the only lock. Keep it private; only people on your network can even reach the page.`);
+    nextSteps.push(`Easiest on a phone: open the page on this computer, click ${bold('"Connect a device" → Phone')}, and scan the QR.`);
+  } else {
+    host = '127.0.0.1'; // the tunnel reaches in; we don't bind to the network directly
+    out();
+    out(yellow('  ⚠  Going over the internet means anyone with the link could reach the page.'));
+    out(yellow('     The access token still gates it, but before you rely on this you should'));
+    out(yellow('     turn on login / 2FA / OAuth — see docs/SECURITY.md.'));
+    const ok = await confirm('  Understood — set up an internet tunnel now?', true);
+    if (ok) {
+      const prov = await pick('   Which free tunnel?', [
+        { key: '1', label: 'Microsoft Dev Tunnels', hint: 'needs a one-time `devtunnel user login`' },
+        { key: '2', label: 'Cloudflare Quick Tunnel', hint: 'no account; testing-grade URL' },
+      ]);
+      tunnelProvider = prov.key === '2' ? 'cloudflare-quick' : 'devtunnel';
+      const cli = tunnelProvider === 'cloudflare-quick' ? 'cloudflared' : 'devtunnel';
+      if (!onPath(cli)) {
+        out(yellow(`   The "${cli}" command isn't installed yet.`));
+        out(`   Install it, then re-run setup. Docs: ${cyan('docs/INSTALL.md')} (Remote access).`);
+        out(dim('   Continuing anyway — the server will fall back to localhost-only if the tunnel cannot start.'));
+      }
+      nextSteps.push(`When the tunnel connects, its public ${bold('https://…')} URL prints in the banner below and shows in the UI.`);
+      nextSteps.push(`Open that URL on your phone, or use ${bold('"Connect a device" → Phone')} in the UI to scan a QR.`);
+      nextSteps.push(`${yellow('Before sharing it:')} open the UI, enable login/2FA, and read docs/SECURITY.md.`);
+    } else {
+      host = '127.0.0.1';
+      nextSteps.push(`No tunnel started — running on this computer only. Re-run ${cyan('anyagent-bridge setup')} when you're ready to go remote.`);
+    }
+  }
+
+  // 3) summary + launch ---------------------------------------------------------
+  out();
+  out(bold('3. Starting the bridge'));
+  out(`  ${dim('mode   ')} ${where.label}`);
+  out(`  ${dim('listen ')} ${host}:${port}`);
+  out(`  ${dim('tunnel ')} ${tunnelProvider || 'off'}`);
+  out();
+  out(bold('  Next:'));
+  for (const s of nextSteps) out(`   ${green('→')} ${s}`);
+  out();
+  out(dim('  Full beginner guide: docs/GETTING-STARTED.md   ·   Security: docs/SECURITY.md'));
+  rule();
+  out();
+
+  if (rl) rl.close();
+
+  // Hand the chosen settings to the real server via the same env vars the
+  // launcher uses, then boot it in-process. Its own banner (URL, token, and any
+  // tunnel URL) prints next.
+  process.env.PORT = port;
+  process.env.HOST = host;
+  process.env.BRIDGE_AUTH_TOKEN = token;
+  if (tunnelProvider) {
+    process.env.BRIDGE_TUNNEL_ENABLED = 'true';
+    process.env.BRIDGE_TUNNEL_PROVIDER = tunnelProvider;
+  }
+  require(path.join(__dirname, '..', 'server', 'index.js'));
+})().catch((e) => {
+  process.stderr.write('setup failed: ' + (e && e.stack ? e.stack : e) + '\n');
+  process.exit(1);
+});

package/client/index.html

@@ -105,6 +105,75 @@
     select, button, input { font-size: 12px; padding: 7px 9px; }
     #status { margin-left: auto; }
   }
+
+  /* Connect-a-device onboarding */
+  #onboard {
+    position: fixed; inset: 0; z-index: 60;
+    background: rgba(13,17,23,.96);
+    display: none; align-items: center; justify-content: center; padding: 18px;
+  }
+  #onboard.open { display: flex; }
+  #onboard .card {
+    position: relative;
+    background: var(--bar); border: 1px solid var(--border); border-radius: 12px;
+    width: 100%; max-width: 460px; max-height: 90vh; overflow-y: auto;
+    padding: 20px 22px; box-shadow: 0 12px 40px rgba(0,0,0,.5);
+  }
+  #onboard h2 { margin: 0 0 2px; font-size: 17px; }
+  #onboard h2 .dot { color: var(--accent); }
+  #onboard .sub { margin: 0 0 14px; color: var(--muted); font-size: 12.5px; line-height: 1.5; }
+  #onboard .ob-close {
+    position: absolute; top: 12px; right: 14px;
+    background: transparent; border: none; color: var(--muted);
+    font-size: 22px; line-height: 1; cursor: pointer; padding: 2px 6px;
+  }
+  #onboard .ob-close:hover { color: var(--fg); }
+  #onboard .qrbox {
+    display: flex; align-items: center; justify-content: center;
+    background: #fff; border-radius: 10px; padding: 14px;
+    margin: 0 auto 8px; width: max-content;
+  }
+  #onboard .qrbox img, #onboard .qrbox canvas { display: block; }
+  #onboard .qrcap { color: var(--muted); font-size: 12px; text-align: center; margin: 0 0 6px; }
+  #onboard .blk { border-top: 1px solid var(--border); padding: 12px 0 4px; }
+  #onboard .blk:first-of-type { border-top: none; }
+  #onboard .blk h3 { margin: 0 0 6px; font-size: 13px; }
+  #onboard .blk p { margin: 0 0 8px; font-size: 12.5px; color: var(--fg); line-height: 1.55; }
+  #onboard code {
+    background: #0d1117; border: 1px solid var(--border); border-radius: 5px;
+    padding: 1px 6px; font-size: 12px; word-break: break-all;
+  }
+  #onboard .warn { color: var(--yellow); }
+  #onboard .row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; margin-bottom: 6px; }
+  #onboard .muted { color: var(--muted); font-size: 12px; }
+
+  /* Projects — folder-browser picker */
+  #projModal { position: fixed; inset: 0; z-index: 60; background: rgba(13,17,23,.96); display: none; align-items: center; justify-content: center; padding: 18px; }
+  #projModal.open { display: flex; }
+  #projModal .card { position: relative; background: var(--bar); border: 1px solid var(--border); border-radius: 12px; width: 100%; max-width: 480px; max-height: 90vh; overflow-y: auto; padding: 20px 22px; box-shadow: 0 12px 40px rgba(0,0,0,.5); }
+  #projModal h2 { margin: 0 0 2px; font-size: 17px; }
+  #projModal .sub { margin: 0 0 12px; color: var(--muted); font-size: 12.5px; line-height: 1.5; }
+  #projModal .pm-close { position: absolute; top: 12px; right: 14px; background: transparent; border: none; color: var(--muted); font-size: 22px; line-height: 1; cursor: pointer; padding: 2px 6px; }
+  #projModal .pm-close:hover { color: var(--fg); }
+  #projModal .pm-list { list-style: none; margin: 0 0 12px; padding: 0; }
+  #projModal .pm-list li { display: flex; align-items: center; gap: 8px; padding: 6px 8px; border: 1px solid var(--border); border-radius: 7px; margin-bottom: 6px; }
+  #projModal .pm-nm { font-size: 13px; font-weight: 600; white-space: nowrap; }
+  #projModal .pm-pa { font-size: 11px; color: var(--muted); word-break: break-all; flex: 1; }
+  #projModal .pm-del { background: transparent; border: none; color: var(--red); cursor: pointer; font-size: 14px; padding: 0 4px; }
+  #projModal .pm-empty { color: var(--muted); font-size: 12.5px; margin: 0 0 12px; }
+  #projModal .pm-add { border-top: 1px solid var(--border); padding-top: 12px; }
+  #projModal .pm-add h3 { margin: 0 0 8px; font-size: 13px; }
+  #projModal .pm-crumb { font-size: 12px; color: var(--accent); word-break: break-all; margin: 0 0 6px; }
+  #projModal .pm-browser { border: 1px solid var(--border); border-radius: 7px; max-height: 190px; overflow-y: auto; margin-bottom: 8px; background: #0d1117; }
+  #projModal .pm-row { display: flex; align-items: center; gap: 8px; padding: 7px 10px; cursor: pointer; font-size: 13px; border-bottom: 1px solid rgba(48,54,61,.5); }
+  #projModal .pm-row:last-child { border-bottom: none; }
+  #projModal .pm-row:hover { background: #161b22; }
+  #projModal .pm-row.up { color: var(--muted); }
+  #projModal .pm-sel { font-size: 12px; color: var(--fg); margin: 0 0 8px; word-break: break-all; }
+  #projModal .pm-sel b { color: var(--green); }
+  #projModal .pm-fields { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }
+  #projModal .pm-fields input { flex: 1; min-width: 150px; }
+  #projModal .pm-err { color: var(--red); font-size: 12px; min-height: 15px; margin: 6px 0 0; }
 </style>
 </head>
 <body>
@@ -113,7 +182,9 @@
     <span class="title">AnyAgent<span class="dot">·</span>Bridge</span>
     <select id="agentSel" title="Agent"></select>
     <button id="startBtn">Start</button>
+    <button id="connectBtn" title="Open on a phone or another device">📱 Connect a device</button>
     <select id="projectSel" title="Project" style="display:none"></select>
+    <button id="projBtn" title="Add or manage projects by browsing folders">📁 Projects</button>
     <span class="spacer"></span>
     <span id="status" class="disconnected"><span class="led"></span><span id="statusText">disconnected</span></span>
   </div>
@@ -140,6 +211,53 @@
   </div>
 </div>
 
+<div id="onboard">
+  <div class="card">
+    <button class="ob-close" id="obClose" aria-label="Close">×</button>
+    <h2>Connect a device</h2>
+    <p class="sub">Open this bridge on your phone or another computer. Scan the code, or follow the steps below.</p>
+    <div class="qrbox" id="obQrBox"><div id="obQr"></div></div>
+    <p class="qrcap" id="obQrCap"></p>
+    <div class="blk" id="obPhone">
+      <h3>📱 On your phone</h3>
+      <p id="obPhoneMsg">Preparing…</p>
+      <div class="row" id="obTunnelRow"></div>
+    </div>
+    <div class="blk">
+      <h3>💻 This computer</h3>
+      <p>Open <code id="obLocalUrl">…</code> in this machine's browser.</p>
+    </div>
+    <div class="blk">
+      <h3>🖥 Another PC on the same Wi-Fi</h3>
+      <p id="obLanMsg">…</p>
+    </div>
+    <div class="blk">
+      <p class="warn">Beyond this computer, the access token is the only lock until you turn on login — set up login / 2FA / OAuth and read <code>docs/SECURITY.md</code> before exposing it.</p>
+    </div>
+  </div>
+</div>
+
+<div id="projModal">
+  <div class="card">
+    <button class="pm-close" id="pmClose" aria-label="Close">×</button>
+    <h2>Projects</h2>
+    <p class="sub">A project scopes an agent session to a folder. Add one by browsing — no typing the full path.</p>
+    <ul class="pm-list" id="pmList"></ul>
+    <p class="pm-empty" id="pmEmpty" style="display:none">No projects yet.</p>
+    <div class="pm-add">
+      <h3>Add a project</h3>
+      <p class="pm-crumb" id="pmCrumb">…</p>
+      <div class="pm-browser" id="pmBrowser"></div>
+      <p class="pm-sel">Selected folder: <b id="pmSel">…</b></p>
+      <div class="pm-fields">
+        <input id="pmName" type="text" placeholder="project name" autocomplete="off" autocapitalize="off" spellcheck="false" />
+        <button class="primary" id="pmAdd">Add project</button>
+      </div>
+      <p class="pm-err" id="pmErr"></p>
+    </div>
+  </div>
+</div>
+
 <script src="https://cdn.jsdelivr.net/npm/@xterm/xterm@5.5.0/lib/xterm.min.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-fit@0.10.0/lib/addon-fit.min.js"></script>
 <script>
@@ -483,6 +601,205 @@
     } catch (_) {}
   }
 
+  // ---------- Connect-a-device onboarding ----------
+  const connectBtn = $("connectBtn"), onboard = $("onboard"), obClose = $("obClose");
+  let qrLibPromise = null, tunnelPolling = false;
+  function loadQrLib() {
+    if (window.QRCode) return Promise.resolve();
+    if (qrLibPromise) return qrLibPromise;
+    qrLibPromise = new Promise((resolve, reject) => {
+      const s = document.createElement("script");
+      s.src = "https://cdn.jsdelivr.net/npm/qrcodejs@1.0.0/qrcode.min.js";
+      s.onload = () => resolve();
+      s.onerror = () => reject(new Error("QR library failed to load"));
+      document.head.appendChild(s);
+    });
+    return qrLibPromise;
+  }
+  // The QR carries the access token so the device logs in by scanning. With a
+  // cookie-only (OAuth) session there is no JS token, so it links to the page
+  // and the device logs in there.
+  function loginQuery() { return token ? ("/?token=" + encodeURIComponent(token)) : "/"; }
+  async function showQr(url) {
+    const box = $("obQrBox"), holder = $("obQr");
+    try {
+      await loadQrLib();
+      holder.innerHTML = "";
+      new window.QRCode(holder, { text: url, width: 196, height: 196, correctLevel: window.QRCode.CorrectLevel.M });
+      box.style.display = "flex";
+    } catch (e) {
+      box.style.display = "none";
+    }
+  }
+  async function openOnboard() {
+    onboard.classList.add("open");
+    const port = location.port || (location.protocol === "https:" ? "443" : "80");
+    $("obLocalUrl").textContent = location.origin + "/";
+    $("obLanMsg").innerHTML =
+      'Restart the bridge so it listens on your network — run <code>anyagent-bridge setup</code> and pick ' +
+      '"same Wi-Fi", or add <code>--host 0.0.0.0</code> — then on the other device open ' +
+      '<code>http://&lt;this-computer-ip&gt;:' + port + '/</code> and paste the token.';
+    const phoneMsg = $("obPhoneMsg"), tunnelRow = $("obTunnelRow"), qrCap = $("obQrCap");
+    tunnelRow.innerHTML = "";
+    let sys = null;
+    try { sys = await api("/api/system/status"); } catch (_) {}
+    const tunnelUrl = sys && sys.tunnel && sys.tunnel.url;
+    const isLocalHost = location.hostname === "127.0.0.1" || location.hostname === "localhost";
+    if (tunnelUrl) {
+      phoneMsg.textContent = "A live internet tunnel is running. Scan to open it from anywhere:";
+      qrCap.textContent = "Point your phone's camera at this code.";
+      showQr(tunnelUrl.replace(/\/+$/, "") + loginQuery());
+    } else if (!isLocalHost) {
+      phoneMsg.textContent = "Your phone must be on the same Wi-Fi as this computer. Scan to open:";
+      qrCap.textContent = "Point your phone's camera at this code.";
+      showQr(location.origin + loginQuery());
+    } else {
+      qrCap.textContent = "";
+      $("obQrBox").style.display = "none";
+      phoneMsg.innerHTML = "This bridge is only listening on this computer, so a phone can't reach it yet. Start a free internet tunnel:";
+      const btn = document.createElement("button");
+      btn.textContent = "Start internet tunnel";
+      btn.className = "primary";
+      btn.addEventListener("click", () => startTunnel(btn));
+      tunnelRow.appendChild(btn);
+      const note = document.createElement("span");
+      note.className = "muted";
+      note.textContent = "Turn on login/2FA first if anyone else could reach it.";
+      tunnelRow.appendChild(note);
+    }
+  }
+  async function startTunnel(btn) {
+    if (tunnelPolling) return;            // ignore a second click while one poll is in flight
+    tunnelPolling = true;
+    btn.disabled = true; btn.textContent = "Starting…";
+    try {
+      await fetch("/api/tunnel/start", { method: "POST", credentials: "include", headers: token ? { Authorization: "Bearer " + token } : {} });
+    } catch (_) {}
+    for (let i = 0; i < 20; i++) {
+      await new Promise((r) => setTimeout(r, 1500));
+      if (!onboard.classList.contains("open")) { tunnelPolling = false; return; } // panel closed — stop polling
+      let sys; try { sys = await api("/api/system/status"); } catch (_) { continue; }
+      const url = sys && sys.tunnel && sys.tunnel.url;
+      if (url) {
+        tunnelPolling = false;
+        btn.textContent = "Tunnel ready ✓";
+        $("obPhoneMsg").textContent = "Scan to open over the internet:";
+        $("obQrCap").textContent = "Point your phone's camera at this code.";
+        showQr(url.replace(/\/+$/, "") + loginQuery());
+        return;
+      }
+    }
+    tunnelPolling = false;
+    btn.disabled = false; btn.textContent = "Start internet tunnel";
+    $("obPhoneMsg").innerHTML = "The tunnel didn't come up — the tunnel CLI may not be installed. See <code>docs/INSTALL.md</code> (Remote access).";
+  }
+  function closeOnboard() { onboard.classList.remove("open"); }
+  connectBtn.addEventListener("click", openOnboard);
+  obClose.addEventListener("click", closeOnboard);
+  onboard.addEventListener("click", (e) => { if (e.target === onboard) closeOnboard(); });
+  document.addEventListener("keydown", (e) => { if (e.key === "Escape" && onboard.classList.contains("open")) closeOnboard(); });
+
+  // ---------- Projects: folder-browser picker (reuses GET /api/browse) ----------
+  const projBtn = $("projBtn"), projModal = $("projModal"), pmClose = $("pmClose");
+  let pmCurrent = null;
+  function pmBasename(p) { return p.replace(/[\/\\]+$/, "").split(/[\/\\]/).pop() || p; }
+  async function pmBrowse(p) {
+    const browser = $("pmBrowser"), err = $("pmErr");
+    err.textContent = "";
+    // Raw fetch (not api()) so the server's own message survives a 403 — e.g. a
+    // folder outside the configured allowedPaths returns "Access denied", which is
+    // far more useful than a generic "unauthorized".
+    let res, data;
+    try {
+      res = await fetch("/api/browse" + (p ? "?path=" + encodeURIComponent(p) : ""),
+        { credentials: "include", headers: token ? { Authorization: "Bearer " + token } : {} });
+      data = await res.json().catch(() => ({}));
+    } catch (e) { err.textContent = "Could not reach the server."; return; }
+    if (res.status === 401) { err.textContent = "Session expired — reload to log in again."; return; }
+    if (!res.ok || data.error) { err.textContent = data.error || ("Could not open that folder (HTTP " + res.status + ")."); return; }
+    pmCurrent = data.current;
+    $("pmCrumb").textContent = data.current;
+    $("pmSel").textContent = data.current;
+    // keep the name field in sync with the folder until the user types their own
+    if ($("pmName").dataset.auto !== "0") {
+      $("pmName").value = pmBasename(data.current);
+      $("pmName").dataset.auto = "1";
+    }
+    browser.innerHTML = "";
+    if (data.parent) {
+      const up = document.createElement("div");
+      up.className = "pm-row up"; up.textContent = "⬆  ..";
+      up.addEventListener("click", () => pmBrowse(data.parent));
+      browser.appendChild(up);
+    }
+    if (!data.folders.length) {
+      const none = document.createElement("div");
+      none.className = "pm-row"; none.style.cursor = "default"; none.textContent = "(no subfolders here)";
+      browser.appendChild(none);
+    }
+    for (const f of data.folders) {
+      const row = document.createElement("div");
+      row.className = "pm-row"; row.textContent = "📁  " + f.name;
+      row.addEventListener("click", () => pmBrowse(f.path));
+      browser.appendChild(row);
+    }
+  }
+  async function pmLoadList() {
+    const ul = $("pmList");
+    ul.innerHTML = "";
+    let list = [];
+    try { const d = await api("/api/projects"); list = d.projects || []; } catch (_) {}
+    $("pmEmpty").style.display = list.length ? "none" : "";
+    for (const p of list) {
+      const li = document.createElement("li");
+      const nm = document.createElement("span"); nm.className = "pm-nm"; nm.textContent = p.name;
+      const pa = document.createElement("span"); pa.className = "pm-pa"; pa.textContent = p.path;
+      const del = document.createElement("button"); del.className = "pm-del"; del.textContent = "✕"; del.title = "Remove";
+      del.addEventListener("click", () => pmDelete(p.name));
+      li.appendChild(nm); li.appendChild(pa); li.appendChild(del);
+      ul.appendChild(li);
+    }
+  }
+  async function pmAddProject() {
+    const err = $("pmErr"), name = $("pmName").value.trim();
+    if (!pmCurrent) { err.textContent = "Pick a folder first."; return; }
+    if (!name) { err.textContent = "Give the project a name."; return; }
+    err.textContent = "";
+    let res, data;
+    try {
+      res = await fetch("/api/projects", { method: "POST", credentials: "include",
+        headers: Object.assign({ "Content-Type": "application/json" }, token ? { Authorization: "Bearer " + token } : {}),
+        body: JSON.stringify({ name: name, path: pmCurrent }) });
+      data = await res.json().catch(() => ({}));
+    } catch (e) { err.textContent = "Network error."; return; }
+    if (!res.ok || data.error) { err.textContent = data.error || ("HTTP " + res.status); return; }
+    $("pmName").value = ""; $("pmName").dataset.auto = "1";
+    await pmLoadList();
+    try { await loadProjects(); } catch (_) {}   // refresh the toolbar dropdown
+  }
+  async function pmDelete(name) {
+    try {
+      await fetch("/api/projects/" + encodeURIComponent(name), { method: "DELETE", credentials: "include",
+        headers: token ? { Authorization: "Bearer " + token } : {} });
+    } catch (_) {}
+    await pmLoadList();
+    try { await loadProjects(); } catch (_) {}
+  }
+  function openProjects() {
+    projModal.classList.add("open");
+    $("pmErr").textContent = "";
+    $("pmName").value = ""; $("pmName").dataset.auto = "1";
+    pmLoadList();
+    pmBrowse(null);   // start at the server's home / first allowed base
+  }
+  function closeProjects() { projModal.classList.remove("open"); }
+  $("pmName").addEventListener("input", () => { $("pmName").dataset.auto = "0"; });
+  projBtn.addEventListener("click", openProjects);
+  pmClose.addEventListener("click", closeProjects);
+  projModal.addEventListener("click", (e) => { if (e.target === projModal) closeProjects(); });
+  $("pmAdd").addEventListener("click", pmAddProject);
+  document.addEventListener("keydown", (e) => { if (e.key === "Escape" && projModal.classList.contains("open")) closeProjects(); });
+
   // ---------- Bootstrap ----------
   (async function boot() {
     const params = new URLSearchParams(location.search);

package/docs/GETTING-STARTED.md

@@ -0,0 +1,108 @@
+# Getting started (for first-timers)
+
+New to the terminal or to AI coding agents? This is the gentlest path to running
+anyagent-bridge and opening it on your computer, another PC, or your phone. If you
+just want the short version, the [README](../README.md) Quick start has it; for the
+full reference see [INSTALL.md](INSTALL.md), and **before you let anything but your
+own computer reach the bridge, read [SECURITY.md](SECURITY.md).**
+
+## What this is, in one line
+
+anyagent-bridge puts your computer's terminal — and any AI coding agent you've
+installed (like Claude Code) — onto a web page, so you can drive it from a browser
+on the same computer, another PC, or your phone.
+
+## What you need first
+
+1. **Node.js 18 or newer.** Check by opening a terminal and running `node -v`. No
+   Node? Install it from <https://nodejs.org> (the "LTS" button).
+2. **An AI agent CLI, optional but recommended.** e.g. Claude Code:
+   `npm install -g @anthropic-ai/claude-code`, then run `claude` once to log in.
+   Without one you still get a normal shell in the browser; you just can't launch
+   an agent until one is installed.
+
+## Step 1 — Run the guided setup
+
+In a terminal, run:
+
+```bash
+npx anyagent-bridge setup
+```
+
+The first time, npm asks to download the package — say yes. Then a friendly wizard:
+
+- checks your Node version and which agents (`claude`, `codex`) it can find,
+- asks **where you want to open the bridge**, and
+- starts the server with the right settings and prints your access link.
+
+That's it — you do **not** need to edit any config files to get going.
+
+## Step 2 — Pick where you'll open it
+
+The wizard asks this; here's what each choice means.
+
+### 💻 On this same computer (simplest)
+
+Choose "This computer". When it starts, it prints a line like
+`URL: http://127.0.0.1:3001/?token=…`. Open that whole link (including the
+`?token=…` part) in your browser. You're in. Nothing is exposed to your network
+or the internet.
+
+### 🖥 Another PC or your phone on the same Wi-Fi
+
+Choose "same Wi-Fi". The bridge starts listening on your network and the wizard
+prints your computer's address, like `http://192.168.0.8:3001/`. On the other
+device's browser, open that address and paste the access token (the long string
+the wizard printed). Both devices must be on the same Wi-Fi.
+
+> On your network, **the token is the only lock.** Keep it private.
+
+### 📱 Your phone from anywhere (over the internet)
+
+Choose "phone / anywhere". The wizard helps you turn on a free **tunnel** (a safe
+public web address that points back to your computer). When it connects, a public
+`https://…` address appears. Open it on your phone, or use the QR (next step).
+
+> Going over the internet means the page is reachable by anyone with the link. The
+> token still gates it, but **turn on login / 2FA before you rely on it** — see
+> [SECURITY.md](SECURITY.md).
+
+## Step 3 — Open it on your phone by scanning a QR
+
+Once the bridge is open in a browser on your computer, click
+**"📱 Connect a device"** in the top bar. A panel pops up with a **QR code** —
+point your phone's camera at it and it opens the bridge on your phone, already
+logged in. The same panel shows the steps for "this computer", "same Wi-Fi", and
+starting an internet tunnel, so you never have to type the long token on a phone.
+
+## Step 4 — Launch an AI agent
+
+In the web terminal you have a real shell. To start an agent, pick it from the
+dropdown in the top bar (e.g. **Claude Code**) and click **Start** — it runs inside
+the session, streamed live to your browser. Detaching the browser keeps it alive;
+reconnect and you're back with full scrollback.
+
+To run the agent inside a specific **project folder**, click **📁 Projects** in the
+top bar and *browse* to the folder — no typing the full path. It's saved and shows
+up in the toolbar's project dropdown; pick one before launching.
+
+## If something goes wrong
+
+- **`node -v` says command not found** — install Node.js (above), then reopen the
+  terminal.
+- **The agent dropdown is empty** — the agent CLI isn't installed or isn't on your
+  PATH. Verify it runs in the same terminal (e.g. type `claude`).
+- **"Port already in use"** — something else uses port 3001. Run
+  `npx anyagent-bridge --port 8080` (any free number) or re-run `setup`.
+- **The phone QR / tunnel didn't work** — the tunnel CLI may not be installed; see
+  [INSTALL.md](INSTALL.md) → Remote access. On the same Wi-Fi you don't need a
+  tunnel at all — use the "same Wi-Fi" address instead.
+- **Lost the token** — it's printed in the terminal banner; scroll up, or stop and
+  re-run. You can also pin your own with `--token`.
+
+## Where to go next
+
+- [INSTALL.md](INSTALL.md) — every install path (npx, source, Docker), per-OS notes.
+- [SECURITY.md](SECURITY.md) — what to turn on before exposing the bridge. **Read
+  this before going remote.**
+- [WALKTHROUGH.md](WALKTHROUGH.md) — a screenshot tour of the whole thing.

package/docs/INSTALL.md

@@ -32,7 +32,9 @@ npx anyagent-bridge
 ```
 
 This downloads and runs the bridge in one step, then prints an access URL with a
-token. Open it in your browser. Useful flags:
+token. Open it in your browser. New to this? Run `npx anyagent-bridge setup` for a
+guided, first-timer flow (prerequisite checks + help opening it on a phone or
+another PC); see [GETTING-STARTED.md](GETTING-STARTED.md). Useful flags:
 
 ```bash
 npx anyagent-bridge --port 8080            # listen on a different port

package/docs/WALKTHROUGH.md

@@ -7,6 +7,7 @@ A guided tour of using anyagent-bridge end to end. The screenshots below live in
 ## 1. Start the bridge
 
 ```bash
+npx anyagent-bridge setup    # guided first-timer setup (recommended), or:
 npx anyagent-bridge          # or: npm start  /  docker compose up -d --build
 ```
 
@@ -45,6 +46,10 @@ as you would in your own terminal — streamed live to the browser. Type prompts
 send keys, and watch output in real time. Detaching the browser keeps the session
 alive; reconnecting reattaches with full scrollback.
 
+To scope a session to a folder, click **📁 Projects** in the top bar and *browse* to
+it — no typing the path. Saved projects appear in the toolbar dropdown; pick one
+before you launch the agent.
+
 ![Claude Code running inside a bridge session](screenshots/03-agent-running.png)
 
 ## 4. Browse and edit files
@@ -61,6 +66,13 @@ at startup (`--tunnel devtunnel`) or at runtime via the tunnel controls
 ready. Before exposing anything, read [SECURITY.md](SECURITY.md) and turn on
 login / 2FA / OAuth.
 
+The easiest way onto a phone: click **"📱 Connect a device"** in the top bar. It
+shows a scannable QR for your current address (or a live tunnel), the localhost
+link, step-by-step same-Wi-Fi instructions, and a one-click "Start internet
+tunnel" — so you never type the long token on a phone.
+
+![The "Connect a device" panel with a scannable QR](screenshots/05-connect-device.png)
+
 ![The bridge UI at a phone-sized viewport](screenshots/04-mobile.png)
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anyagent-bridge",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Control your local terminal and any CLI AI coding agent from a browser, anywhere.",
   "license": "MIT",
   "author": "elon-choo",