itwillsync 1.0.6 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # itwillsync
 
-Sync any terminal-based coding agent to your phone over local network. Open source, agent-agnostic, zero cloud.
+Sync any terminal-based coding agent to your phone. Local network or Tailscale. Open source, agent-agnostic, zero cloud.
 
 ```
 npx itwillsync -- claude
@@ -15,8 +15,6 @@ npx itwillsync -- bash
 3. Scan it on your phone — opens a terminal in your browser
 4. Control your agent from your phone (or both phone and laptop simultaneously)
 
-All data stays on your local network. No cloud, no relay, no account needed.
-
 ## Requirements
 
 - Node.js 20+
@@ -33,94 +31,56 @@ npm install -g itwillsync
 itwillsync -- aider --model gpt-4
 ```
 
-## Options
-
-```
---port <number>   Port to listen on (default: 3456)
---localhost        Bind to 127.0.0.1 only (no LAN access)
---no-qr           Don't display QR code
--h, --help        Show help
--v, --version     Show version
-```
-
-## Remote Access
-
-By default, itwillsync is accessible on your local network (same WiFi). For remote access from anywhere:
-
-- **Tailscale** (recommended): Install on both devices, access via Tailscale IP
-- **WireGuard / VPN**: Any VPN that puts devices on the same network
-- **SSH tunnel**: `ssh -L 3456:localhost:3456 your-machine`
-
-## Security
-
-- Each session generates a random 64-character token
-- Token is embedded in the QR code URL
-- All WebSocket connections require the token
-- No data leaves your network
-
-## Architecture
-
-```
-Your Machine                          Your Phone
-┌─────────────────────┐              ┌──────────────┐
-│ itwillsync          │   WiFi/LAN   │  Browser     │
-│ ├─ PTY (your agent) │◄────────────►│  xterm.js    │
-│ ├─ HTTP server      │  WebSocket   │  terminal    │
-│ └─ WS server        │              └──────────────┘
-└─────────────────────┘
-```
-
-## Session Behavior
+On first run, a setup wizard asks how you want to connect — local WiFi or Tailscale. Your choice is saved for future sessions.
 
-- **No timeout**: Sessions live as long as the agent process runs. No TTL, no idle disconnect.
-- **Multiple devices**: Connect from phone, tablet, and laptop simultaneously — all see the same terminal.
-- **Reconnect**: If your phone disconnects (WiFi switch, screen lock), it auto-reconnects and catches up with recent output.
-- **Keepalive**: WebSocket pings every 30s prevent routers from closing idle connections.
-- **One session per instance**: Run multiple `itwillsync` instances on different ports for multiple agents.
+## Connect from Anywhere with Tailscale
 
-## Development
+By default, your phone needs to be on the same WiFi. With [Tailscale](https://tailscale.com), you can connect from anywhere — coffee shop, cellular, different network.
 
 ```bash
-# 1. Clone and enter the project
-git clone https://github.com/your-username/itwillsync
-cd itwillsync
-
-# 2. Use Node 22 (required for node-pty native bindings)
-nvm use  # reads .nvmrc
+# First time: the setup wizard will detect Tailscale automatically
+itwillsync -- claude
 
-# 3. Install dependencies
-pnpm install
+# Or use Tailscale for a single session
+itwillsync --tailscale -- claude
 
-# 4. Build everything (web client first, then CLI)
-pnpm build
+# Switch back to local WiFi for a session
+itwillsync --local -- claude
 
-# 5. Test it
-node packages/cli/dist/index.js -- bash
+# Re-run setup anytime
+itwillsync setup
 ```
 
-### Project Structure
+**Setup:** Install Tailscale on both your computer and phone. That's it — itwillsync detects it automatically.
+
+## Options
 
 ```
-packages/
-├── cli/           # Main npm package — PTY, server, auth, CLI
-└── web-client/    # Browser terminal — xterm.js, mobile-friendly CSS
+Commands:
+  setup              Run the setup wizard (change networking mode)
+
+Options:
+  --port <number>    Port to listen on (default: 3456)
+  --localhost         Bind to 127.0.0.1 only (no LAN access)
+  --tailscale         Use Tailscale for this session
+  --local             Use local WiFi for this session
+  --no-qr            Don't display QR code
+  -h, --help         Show help
+  -v, --version      Show version
 ```
 
-### Contributing
+## Security
 
-1. Fork the repo
-2. Create a feature branch
-3. Make your changes
-4. Run `pnpm build` to verify
-5. Open a PR
+- Each session generates a random 64-character token
+- Token is embedded in the QR code URL
+- All WebSocket connections require the token
+- No data leaves your network (local mode) or your Tailscale tailnet
 
-## Roadmap
+## Links
 
-- [ ] Chat-style input bar + quick action buttons on mobile
-- [ ] Agent detection + structured view for Claude Code
-- [ ] React Native mobile app
-- [ ] VS Code extension adapter
-- [ ] Agent Sync Protocol specification
+- **Website**: https://shrijayan.github.io/itwillsync/
+- **GitHub**: https://github.com/shrijayan/itwillsync
+- **Demo**: https://youtu.be/Zc0Tb98CXh0
 
 ## License
 

package/dist/index.js

@@ -3759,6 +3759,70 @@ function validateToken(provided, expected) {
 // src/network.ts
 import { networkInterfaces } from "os";
 import { createServer } from "net";
+
+// src/tailscale.ts
+import { execFile } from "child_process";
+function execCommand(cmd, args) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: 5e3 }, (error, stdout, stderr) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve({ stdout: stdout.trim(), stderr: stderr.trim() });
+      }
+    });
+  });
+}
+function getTailscalePaths() {
+  const paths = ["tailscale"];
+  if (process.platform === "darwin") {
+    paths.push("/Applications/Tailscale.app/Contents/MacOS/Tailscale");
+  }
+  return paths;
+}
+async function tryExec(args) {
+  let lastError = null;
+  for (const bin of getTailscalePaths()) {
+    try {
+      const result = await execCommand(bin, args);
+      return { status: "success", ...result };
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        continue;
+      }
+      lastError = err;
+    }
+  }
+  if (lastError) {
+    return { status: "error", error: lastError };
+  }
+  return { status: "not_found" };
+}
+async function getTailscaleStatus() {
+  const result = await tryExec(["ip", "-4"]);
+  if (result.status === "not_found") {
+    return { installed: false, running: false, ip: null, hostname: null };
+  }
+  if (result.status === "error") {
+    return { installed: true, running: false, ip: null, hostname: null };
+  }
+  const ip = result.stdout.split("\n")[0]?.trim();
+  if (!ip || !/^100\./.test(ip)) {
+    return { installed: true, running: false, ip: null, hostname: null };
+  }
+  let hostname = null;
+  try {
+    const statusResult = await tryExec(["status", "--json"]);
+    if (statusResult.status === "success") {
+      const json = JSON.parse(statusResult.stdout);
+      hostname = json?.Self?.HostName ?? null;
+    }
+  } catch {
+  }
+  return { installed: true, running: true, ip, hostname };
+}
+
+// src/network.ts
 function getLocalIP() {
   const interfaces = networkInterfaces();
   for (const addresses of Object.values(interfaces)) {
@@ -3771,6 +3835,20 @@ function getLocalIP() {
   }
   return "127.0.0.1";
 }
+async function resolveSessionIP(mode, isLocalhost) {
+  if (isLocalhost) return "127.0.0.1";
+  if (mode === "tailscale") {
+    const status = await getTailscaleStatus();
+    if (!status.running || !status.ip) {
+      console.warn(
+        "\n  \u26A0 Tailscale is not running. Falling back to local WiFi.\n"
+      );
+      return getLocalIP();
+    }
+    return status.ip;
+  }
+  return getLocalIP();
+}
 function findAvailablePort(startPort) {
   return new Promise((resolve, reject) => {
     const server = createServer();
@@ -3959,41 +4037,126 @@ function displayQR(url) {
   });
 }
 
-// src/index.ts
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { join as join3, dirname as dirname2 } from "path";
-import { spawn as spawn2 } from "child_process";
-function preventSleep() {
+// src/config.ts
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join as join3 } from "path";
+var DEFAULT_CONFIG = {
+  networkingMode: "local"
+};
+function getConfigDir() {
+  return process.env.ITWILLSYNC_CONFIG_DIR || join3(homedir(), ".itwillsync");
+}
+function getConfigPath() {
+  return join3(getConfigDir(), "config.json");
+}
+function configExists() {
+  return existsSync(getConfigPath());
+}
+function loadConfig() {
   try {
-    if (process.platform === "darwin") {
-      const child = spawn2("caffeinate", ["-i", "-w", String(process.pid)], {
-        stdio: "ignore",
-        detached: true
+    const raw = readFileSync(getConfigPath(), "utf-8");
+    const parsed = JSON.parse(raw);
+    return { ...DEFAULT_CONFIG, ...parsed };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+function saveConfig(config) {
+  const dir = getConfigDir();
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join3(dir, "config.json"),
+    JSON.stringify(config, null, 2) + "\n",
+    "utf-8"
+  );
+}
+
+// src/wizard.ts
+import * as p from "@clack/prompts";
+async function runSetupWizard() {
+  p.intro("itwillsync setup");
+  const networkingMode = await p.select({
+    message: "How do you want to connect your phone?",
+    options: [
+      {
+        value: "local",
+        label: "Local Network",
+        hint: "Phone and computer on the same WiFi"
+      },
+      {
+        value: "tailscale",
+        label: "Tailscale",
+        hint: "Connect from anywhere via Tailscale VPN"
+      }
+    ]
+  });
+  if (p.isCancel(networkingMode)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+  if (networkingMode === "tailscale") {
+    const s = p.spinner();
+    s.start("Checking Tailscale status...");
+    const status = await getTailscaleStatus();
+    s.stop("Tailscale check complete");
+    if (!status.installed) {
+      p.log.error("Tailscale is not installed.");
+      const installHint = process.platform === "darwin" ? "brew install tailscale  or  https://tailscale.com/download" : process.platform === "win32" ? "https://tailscale.com/download/windows" : "curl -fsSL https://tailscale.com/install.sh | sh";
+      p.log.info(`Install: ${installHint}`);
+      const saveAnyway = await p.confirm({
+        message: "Save Tailscale as your default anyway? (You can install it later)",
+        initialValue: false
       });
-      child.unref();
-      return child;
-    } else if (process.platform === "linux") {
-      return spawn2("systemd-inhibit", [
-        "--what=idle",
-        "--who=itwillsync",
-        "--why=Terminal sync session active",
-        "sleep",
-        "infinity"
-      ], { stdio: "ignore" });
+      if (p.isCancel(saveAnyway) || !saveAnyway) {
+        const config2 = { networkingMode: "local" };
+        saveConfig(config2);
+        p.outro("Saved as Local Network. Run 'itwillsync setup' to change later.");
+        return config2;
+      }
+    } else if (!status.running) {
+      p.log.warn("Tailscale is installed but not connected.");
+      p.log.info("Run 'tailscale up' or start the Tailscale app to connect.");
+      const saveAnyway = await p.confirm({
+        message: "Save Tailscale as your default anyway?",
+        initialValue: true
+      });
+      if (p.isCancel(saveAnyway) || !saveAnyway) {
+        const config2 = { networkingMode: "local" };
+        saveConfig(config2);
+        p.outro("Saved as Local Network. Run 'itwillsync setup' to change later.");
+        return config2;
+      }
+    } else {
+      p.log.success(
+        `Tailscale detected! IP: ${status.ip}${status.hostname ? ` (${status.hostname})` : ""}`
+      );
     }
-  } catch {
   }
-  return null;
+  const config = { networkingMode };
+  saveConfig(config);
+  const modeLabel = networkingMode === "tailscale" ? "Tailscale" : "Local Network";
+  p.outro(`Saved! Your phone will connect via ${modeLabel}.`);
+  return config;
 }
+
+// src/cli-options.ts
 var DEFAULT_PORT = 3456;
 function parseArgs(argv) {
   const options = {
     port: DEFAULT_PORT,
     localhost: false,
     noQr: false,
-    command: []
+    command: [],
+    subcommand: null,
+    tailscale: false,
+    local: false
   };
   const args = argv.slice(2);
+  if (args.length > 0 && args[0] === "setup") {
+    options.subcommand = "setup";
+    return options;
+  }
   let i = 0;
   while (i < args.length) {
     const arg = args[i];
@@ -4006,6 +4169,12 @@ function parseArgs(argv) {
     } else if (arg === "--localhost") {
       options.localhost = true;
       i++;
+    } else if (arg === "--tailscale") {
+      options.tailscale = true;
+      i++;
+    } else if (arg === "--local") {
+      options.local = true;
+      i++;
     } else if (arg === "--no-qr") {
       options.noQr = true;
       i++;
@@ -4029,36 +4198,91 @@ itwillsync \u2014 Sync any terminal agent to your phone
 Usage:
   itwillsync [options] -- <command> [args...]
   itwillsync [options] <command> [args...]
+  itwillsync setup
 
 Examples:
   itwillsync -- claude
   itwillsync -- aider --model gpt-4
   itwillsync bash
   itwillsync --port 8080 -- claude
+  itwillsync --tailscale -- claude
+  itwillsync setup
+
+Commands:
+  setup              Run the setup wizard (configure networking mode)
 
 Options:
-  --port <number>   Port to listen on (default: ${DEFAULT_PORT})
-  --localhost        Bind to 127.0.0.1 only (no LAN access)
-  --no-qr           Don't display QR code
-  -h, --help        Show this help
-  -v, --version     Show version
+  --port <number>    Port to listen on (default: ${DEFAULT_PORT})
+  --localhost         Bind to 127.0.0.1 only (no LAN access)
+  --tailscale         Use Tailscale IP for this session
+  --local             Use local network IP for this session
+  --no-qr            Don't display QR code
+  -h, --help         Show this help
+  -v, --version      Show version
 `);
 }
+
+// src/index.ts
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { join as join4, dirname as dirname2 } from "path";
+import { spawn as spawn2 } from "child_process";
+function preventSleep() {
+  try {
+    if (process.platform === "darwin") {
+      const child = spawn2("caffeinate", ["-i", "-w", String(process.pid)], {
+        stdio: "ignore",
+        detached: true
+      });
+      child.unref();
+      return child;
+    } else if (process.platform === "linux") {
+      return spawn2("systemd-inhibit", [
+        "--what=idle",
+        "--who=itwillsync",
+        "--why=Terminal sync session active",
+        "sleep",
+        "infinity"
+      ], { stdio: "ignore" });
+    }
+  } catch {
+  }
+  return null;
+}
 async function main() {
   const options = parseArgs(process.argv);
+  if (options.subcommand === "setup") {
+    await runSetupWizard();
+    return;
+  }
+  if (options.tailscale && options.local) {
+    console.error("Error: Cannot use both --tailscale and --local.\n");
+    process.exit(1);
+  }
+  if (!configExists() && !options.tailscale && !options.local && process.stdin.isTTY) {
+    await runSetupWizard();
+  }
   if (options.command.length === 0) {
     console.error("Error: No command specified.\n");
     printHelp();
     process.exit(1);
   }
+  let networkingMode = "local";
+  if (options.tailscale) {
+    networkingMode = "tailscale";
+  } else if (options.local) {
+    networkingMode = "local";
+  } else {
+    const config = loadConfig();
+    networkingMode = config.networkingMode;
+  }
   const [cmd, ...cmdArgs] = options.command;
   const token = generateToken();
   const port = await findAvailablePort(options.port);
   const host = options.localhost ? "127.0.0.1" : "0.0.0.0";
-  const ip = options.localhost ? "127.0.0.1" : getLocalIP();
+  const ip = await resolveSessionIP(networkingMode, options.localhost);
   const url = `http://${ip}:${port}?token=${token}`;
   const __dirname = dirname2(fileURLToPath2(import.meta.url));
-  const webClientPath = join3(__dirname, "web-client");
+  const webClientPath = join4(__dirname, "web-client");
   const ptyManager = new PtyManager(cmd, cmdArgs);
   const server = createSyncServer({
     ptyManager,