itwillsync 1.7.0 → 1.8.0

package/README.md

@@ -1,79 +1,215 @@
+<div align="center">
+
 # itwillsync
 
-**[Website](https://shrijayan.github.io/itwillsync/)** | **[Docs](https://shrijayan.github.io/itwillsync/docs/)** | **[npm](https://www.npmjs.com/package/itwillsync)** | **[Demo Video](https://youtu.be/Zc0Tb98CXh0)**
+**Sync any terminal-based AI coding agent to your phone over local network.**
 
-Sync any terminal-based coding agent to your phone. Local network or Tailscale. Open source, agent-agnostic, zero cloud.
+[![npm version](https://img.shields.io/npm/v/itwillsync)](https://www.npmjs.com/package/itwillsync)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm downloads](https://img.shields.io/npm/dm/itwillsync)](https://www.npmjs.com/package/itwillsync)
+[![CI](https://github.com/shrijayan/itwillsync/actions/workflows/ci.yml/badge.svg)](https://github.com/shrijayan/itwillsync/actions/workflows/ci.yml)
 
+Sync any coding agent to your phone — one dashboard for all your sessions. Agent-agnostic, privacy-first, zero cloud.
+
+[Website](https://shrijayan.github.io/itwillsync/) | [Docs](https://shrijayan.github.io/itwillsync/docs/) | [Demo Video](https://youtu.be/Zc0Tb98CXh0)
+
+<!-- TODO: Replace with demo GIF once recorded -->
+<!-- <img src="docs/assets/demo.gif" alt="itwillsync demo: scanning QR code to connect phone to Claude Code terminal session over local WiFi" width="700"> -->
+
+</div>
+
+---
+
+## Quick Start
+
+```bash
+npx itwillsync claude        # Claude Code
+npx itwillsync aider         # Aider
+npx itwillsync bash          # or any terminal command
 ```
-npx itwillsync claude
-npx itwillsync aider
-npx itwillsync bash
-```
 
-## How it works
+No install needed. Node.js 20+ required.
+
+## Why itwillsync
+
+- **Control your agents from your phone**
+  - Scan a QR code and get full terminal access in your browser — no app install needed
+  - Type commands, approve prompts, and fix errors right from your phone
+  - Stay in the loop while you're away from your desk — kitchen, couch, coffee shop
+
+- **One dashboard for all your sessions**
+  - See every running agent at a glance — status, working directory, uptime
+  - Tap any session to jump into the full terminal
+  - Get alerted when an agent needs your attention
+
+- **Works with any agent**
+  - Claude Code, Aider, Codex, Goose, Cline — if it runs in a terminal, it works
+  - Switch between agents without changing your workflow
+  - Not locked to any single vendor or platform
+
+- **Your data stays yours**
+  - Everything runs on your local network — nothing goes to the cloud
+  - No accounts, no signup, no telemetry
+  - End-to-end encrypted connections with per-session tokens
+
+- **Zero friction to get started**
+  - One command: `npx itwillsync claude` — no install, no config
+  - Works on macOS, Windows, and Linux
+
+## How It Works
+
+```
+┌─────────────────┐                           ┌─────────────────┐
+│   Your Laptop   │  Local WiFi / Tailscale   │   Your Phone    │
+│                 │                           │                 │
+│  Agent (Claude, │    WebSocket + Auth       │  Browser-based  │
+│  Aider, etc.)   │  ◄═════════════════════►  │  Terminal       │
+│       ↕         │    Token in QR code       │  (xterm.js)     │
+│  PTY (node-pty) │                           │  Touch keyboard │
+│       ↕         │                           │  Extra keys bar │
+│  HTTP + WS      │                           │                 │
+│  Server         │                           │                 │
+└─────────────────┘                           └─────────────────┘
+```
 
 1. Run `itwillsync` with your agent command
 2. A QR code appears in your terminal
-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)
+3. Scan it on your phone — a terminal opens in your browser
+4. Control your agent from your phone, laptop, or both simultaneously
 
-## Requirements
+## When To Use It
 
-- Node.js 20+
-- Any terminal-based coding agent (Claude Code, Aider, Goose, Codex, or just `bash`)
+- **Walking to the kitchen** while Claude works on a long refactor — check progress from your phone
+- **Monitoring multiple agents** from the couch via the multi-session dashboard
+- **Getting a notification** when your agent needs attention (auto-detects BEL/OSC signals)
+- **Working from a coffee shop** via Tailscale — no need to be on the same WiFi
+- **Showing a colleague** what your AI agents are doing — just share the QR code
+- **Quick approval** from your phone while you're in a meeting
 
-## Install & Use
+## Multi-Session Dashboard
 
-```bash
-# Run directly (no install needed)
-npx itwillsync claude
+Running multiple agents? The hub daemon manages all your sessions from one place.
+
+```
+┌─────────────────────────────────────┐
+│  itwillsync Dashboard               │
+│                                     │
+│  ┌─────────────┐ ┌─────────────┐    │
+│  │ Claude Code │ │ Aider       │    │
+│  │ ~/myproject │ │ ~/api       │    │ 
+│  │ ● Active    │ │ ⚠ Attention │    │
+│  │ 12m uptime  │ │ 3m uptime   │    │
+│  └─────────────┘ └─────────────┘    │
+│                                     │
+│  ┌─────────────┐                    │
+│  │ Bash        │                    │
+│  │ ~/scripts   │                    │
+│  │ ○ Idle      │                    │
+│  │ 45m uptime  │                    │
+│  └─────────────┘                    │
+└─────────────────────────────────────┘
 ```
 
-On first run, a setup wizard asks how you want to connect — local WiFi or Tailscale. Your choice is saved for future sessions.
+- Session cards show agent name, working directory, status, and uptime
+- Real-time updates via WebSocket
+- Tap a card to open the full terminal
+- Attention detection alerts you when an agent needs input
+- Sleep prevention keeps your machine awake during long tasks
 
-## Connect from Anywhere with Tailscale
+## Works With
 
-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.
+Claude Code, Aider, Goose, Codex, Cline, Copilot CLI — or any terminal-based tool.
 
 ```bash
-# First time: the setup wizard will detect Tailscale automatically
-itwillsync claude
+npx itwillsync claude          # Claude Code
+npx itwillsync aider           # Aider
+npx itwillsync goose            # Goose
+npx itwillsync "codex --quiet"  # Codex
+npx itwillsync bash             # Plain shell
+```
 
-# Or use Tailscale for a single session
-itwillsync --tailscale claude
+If it runs in a terminal, itwillsync can sync it.
 
-# Switch back to local WiFi for a session
-itwillsync --local claude
+## Connection Modes
 
-# Re-run setup anytime
-itwillsync setup
-```
+| Mode | Command | When |
+|------|---------|------|
+| **Local WiFi** (default) | `npx itwillsync claude` | Phone on same network |
+| **Tailscale** | `npx itwillsync --tailscale claude` | Any network, anywhere |
+| **Cloudflare Tunnel** | `npx itwillsync --tunnel cloudflare claude` | Remote, no VPN needed |
+| **Localhost** | `npx itwillsync --localhost claude` | Same machine only |
 
-**Setup:** Install Tailscale on both your computer and phone. That's it — itwillsync detects it automatically.
+On first run, a setup wizard detects your network and saves your preference.
 
-## Options
+```bash
+# First run — wizard auto-detects Tailscale
+npx itwillsync claude
 
+# Override for a single session
+npx itwillsync --tailscale claude
+npx itwillsync --local claude
+
+# Re-run the setup wizard
+npx itwillsync setup
 ```
-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
-```
+
+## Commands
+
+| Flag | Description |
+|------|-------------|
+| `--port <number>` | Port to listen on (default: 3456) |
+| `--localhost` | Bind to 127.0.0.1 only |
+| `--tailscale` | Use Tailscale for this session |
+| `--local` | Use local WiFi for this session |
+| `--tunnel <provider>` | Use a tunnel for remote access (cloudflare) |
+| `--no-qr` | Don't display QR code |
+| `setup` | Run the setup wizard |
+| `-h, --help` | Show help |
+| `-v, --version` | Show version |
 
 ## 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 (local mode) or your Tailscale tailnet
+- **E2E encrypted** — all WebSocket messages encrypted with NaCl secretbox (XSalsa20-Poly1305)
+- **Random tokens** — each session generates a cryptographically random 64-character token
+- **QR code auth** — token is embedded in the QR code URL, no manual entry needed
+- **WebSocket auth** — all connections require the token (constant-time comparison)
+- **Rate limiting** — 5 failed auth attempts locks out the IP for 60 seconds
+- **Zero cloud** — no data leaves your local network (or Tailscale tailnet)
+- **No accounts** — no signup, no telemetry, no tracking
+
+## Mobile-Optimized
+
+The phone terminal isn't just a mirror — it's built for mobile:
+
+- **Touch-friendly extra keys bar** — Ctrl, Alt, Tab, Escape, arrows, and function keys
+- **WebGL-accelerated rendering** on desktop, canvas fallback on mobile
+- **Auto-reconnect** with scrollback buffer sync if connection drops
+- **Audio notifications** when agents need attention
+
+## Development
+
+```bash
+git clone https://github.com/shrijayan/itwillsync.git
+cd itwillsync
+nvm use                          # Node 22
+pnpm install
+pnpm build                       # Build all packages
+pnpm test                        # Run tests
+```
+
+Monorepo structure:
+
+```
+packages/
+├── cli/           → Main npm package (itwillsync)
+├── web-client/    → Browser terminal (xterm.js)
+├── hub/           → Dashboard daemon
+├── landing/       → Landing page
+└── docs/          → VitePress documentation
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and PR guidelines.
 
-## Works with
+## License
 
-Claude Code, Aider, Goose, Codex, Cline, Copilot CLI, or any terminal-based tool.
+[MIT](LICENSE)

package/dist/hub/daemon.js

@@ -4147,7 +4147,7 @@ function createInternalApi(options) {
       }
       res.writeHead(404);
       res.end(JSON.stringify({ error: "Not found" }));
-    } catch (err) {
+    } catch {
       res.writeHead(500);
       res.end(JSON.stringify({ error: "Internal server error" }));
     }
@@ -4189,6 +4189,7 @@ var import_websocket = __toESM(require_websocket(), 1);
 var import_websocket_server = __toESM(require_websocket_server(), 1);
 
 // src/server.ts
+import { deriveEncryptionKey, encrypt, decrypt } from "@itwillsync/shared/crypto";
 var MIME_TYPES = {
   ".html": "text/html; charset=utf-8",
   ".js": "application/javascript; charset=utf-8",
@@ -4202,6 +4203,10 @@ var COMPRESSIBLE = /* @__PURE__ */ new Set([".html", ".js", ".css", ".json", ".s
 var PING_INTERVAL_MS = 3e4;
 function createDashboardServer(options) {
   const { registry, masterToken, dashboardPath, host, port, previewCollector, toolHistory, sleepPrevention, onCreateSession } = options;
+  const encryptionKey = deriveEncryptionKey(masterToken);
+  function sendMsg(ws, msg) {
+    ws.send(encrypt(JSON.stringify(msg), encryptionKey));
+  }
   const homeDir = homedir3();
   const clients = /* @__PURE__ */ new Set();
   const aliveMap = /* @__PURE__ */ new WeakMap();
@@ -4357,26 +4362,33 @@ function createDashboardServer(options) {
     clients.add(ws);
     aliveMap.set(ws, true);
     const sessions = registry.getAll();
-    ws.send(JSON.stringify({ type: "sessions", sessions }));
+    sendMsg(ws, { type: "sessions", sessions });
     if (sleepPrevention) {
-      ws.send(JSON.stringify({ type: "sleep-state", state: sleepPrevention.getState() }));
+      sendMsg(ws, { type: "sleep-state", state: sleepPrevention.getState() });
     }
     if (previewCollector) {
       const previews = previewCollector.getAllPreviews();
       for (const [sessionId, lines] of previews) {
         if (lines.length > 0) {
-          ws.send(JSON.stringify({ type: "preview", sessionId, lines }));
+          sendMsg(ws, { type: "preview", sessionId, lines });
         }
       }
     }
     ws.on("message", async (raw) => {
+      let plaintext;
+      try {
+        const rawStr = typeof raw === "string" ? raw : raw.toString("utf-8");
+        plaintext = decrypt(rawStr, encryptionKey);
+      } catch {
+        return;
+      }
       try {
-        const msg = JSON.parse(typeof raw === "string" ? raw : raw.toString("utf-8"));
+        const msg = JSON.parse(plaintext);
         switch (msg.type) {
           case "stop-session": {
             const session = registry.getById(msg.sessionId);
             if (!session) {
-              ws.send(JSON.stringify({ type: "operation-error", operation: "stop", sessionId: msg.sessionId, error: "Session not found" }));
+              sendMsg(ws, { type: "operation-error", operation: "stop", sessionId: msg.sessionId, error: "Session not found" });
               return;
             }
             try {
@@ -4389,7 +4401,7 @@ function createDashboardServer(options) {
           case "rename-session": {
             const renamed = registry.rename(msg.sessionId, msg.name?.trim());
             if (!renamed) {
-              ws.send(JSON.stringify({ type: "operation-error", operation: "rename", sessionId: msg.sessionId, error: "Session not found" }));
+              sendMsg(ws, { type: "operation-error", operation: "rename", sessionId: msg.sessionId, error: "Session not found" });
             }
             break;
           }
@@ -4402,13 +4414,13 @@ function createDashboardServer(options) {
           }
           case "create-session": {
             if (!onCreateSession) {
-              ws.send(JSON.stringify({ type: "session-create-error", error: "Session creation not available" }));
+              sendMsg(ws, { type: "session-create-error", error: "Session creation not available" });
               break;
             }
             const tool = (msg.tool || "").trim();
             const rawCwd = (msg.cwd || "").trim();
             if (!tool) {
-              ws.send(JSON.stringify({ type: "session-create-error", error: "Tool name is required" }));
+              sendMsg(ws, { type: "session-create-error", error: "Tool name is required" });
               break;
             }
             const cwd = rawCwd ? rawCwd.replace(/^~/, homeDir) : homeDir;
@@ -4416,31 +4428,31 @@ function createDashboardServer(options) {
               const resolved = await realpath(cwd);
               const dirStat = await stat(resolved);
               if (!dirStat.isDirectory()) {
-                ws.send(JSON.stringify({ type: "session-create-error", error: "Not a directory" }));
+                sendMsg(ws, { type: "session-create-error", error: "Not a directory" });
                 break;
               }
-              ws.send(JSON.stringify({ type: "session-creating", tool, cwd: rawCwd || "~" }));
+              sendMsg(ws, { type: "session-creating", tool, cwd: rawCwd || "~" });
               onCreateSession(tool, resolved);
             } catch (err) {
-              ws.send(JSON.stringify({ type: "session-create-error", error: err.message }));
+              sendMsg(ws, { type: "session-create-error", error: err.message });
             }
             break;
           }
           case "enable-sleep-prevention": {
             if (!sleepPrevention) {
-              ws.send(JSON.stringify({ type: "sleep-error", error: "Sleep prevention not available" }));
+              sendMsg(ws, { type: "sleep-error", error: "Sleep prevention not available" });
               break;
             }
             const password = typeof msg.password === "string" ? msg.password : "";
             if (!password) {
-              ws.send(JSON.stringify({ type: "sleep-error", error: "Password is required" }));
+              sendMsg(ws, { type: "sleep-error", error: "Password is required" });
               break;
             }
             const enableResult = await sleepPrevention.enable(password);
             if (enableResult.success) {
               broadcast({ type: "sleep-state", state: sleepPrevention.getState() });
             } else {
-              ws.send(JSON.stringify({ type: "sleep-error", error: enableResult.error }));
+              sendMsg(ws, { type: "sleep-error", error: enableResult.error });
             }
             break;
           }
@@ -4453,7 +4465,7 @@ function createDashboardServer(options) {
           case "get-metadata": {
             const session = registry.getById(msg.sessionId);
             if (!session) {
-              ws.send(JSON.stringify({ type: "operation-error", operation: "metadata", sessionId: msg.sessionId, error: "Session not found" }));
+              sendMsg(ws, { type: "operation-error", operation: "metadata", sessionId: msg.sessionId, error: "Session not found" });
               return;
             }
             let memoryKB = 0;
@@ -4466,7 +4478,7 @@ function createDashboardServer(options) {
               memoryKB = parseInt(output.trim(), 10) || 0;
             } catch {
             }
-            ws.send(JSON.stringify({
+            sendMsg(ws, {
               type: "metadata",
               sessionId: msg.sessionId,
               metadata: {
@@ -4478,7 +4490,7 @@ function createDashboardServer(options) {
                 uptimeMs: Date.now() - session.connectedAt,
                 connectedAt: session.connectedAt
               }
-            }));
+            });
             break;
           }
         }
@@ -4496,7 +4508,7 @@ function createDashboardServer(options) {
     });
   });
   function broadcast(message) {
-    const msg = JSON.stringify(message);
+    const msg = encrypt(JSON.stringify(message), encryptionKey);
     for (const client of clients) {
       if (client.readyState === client.OPEN) {
         client.send(msg);
@@ -4540,6 +4552,7 @@ function createDashboardServer(options) {
 
 // src/preview-collector.ts
 import { EventEmitter as EventEmitter2 } from "events";
+import { deriveEncryptionKey as deriveEncryptionKey2, encrypt as encrypt2, decrypt as decrypt2 } from "@itwillsync/shared/crypto";
 var MAX_PREVIEW_LINES = 5;
 var THROTTLE_MS = 500;
 var MAX_LINE_LENGTH = 80;
@@ -4571,6 +4584,7 @@ var PreviewCollector = class extends EventEmitter2 {
   connectToSession(session) {
     const conn = {
       ws: null,
+      encryptionKey: deriveEncryptionKey2(session.token),
       lines: [],
       rawBuffer: "",
       throttleTimer: null,
@@ -4591,10 +4605,18 @@ var PreviewCollector = class extends EventEmitter2 {
       conn.ws = ws;
       ws.on("open", () => {
         conn.reconnectAttempt = 0;
+        ws.send(encrypt2(JSON.stringify({ type: "sync", lastSeq: -1 }), conn.encryptionKey));
       });
       ws.on("message", (raw) => {
+        let plaintext;
+        try {
+          const rawStr = typeof raw === "string" ? raw : raw.toString("utf-8");
+          plaintext = decrypt2(rawStr, conn.encryptionKey);
+        } catch {
+          return;
+        }
         try {
-          const msg = JSON.parse(typeof raw === "string" ? raw : raw.toString("utf-8"));
+          const msg = JSON.parse(plaintext);
           if (msg.type === "data" && typeof msg.data === "string") {
             this.handleData(sessionId, msg.data);
           }
@@ -4612,7 +4634,7 @@ var PreviewCollector = class extends EventEmitter2 {
       this.scheduleReconnect(sessionId, session);
     }
   }
-  scheduleReconnect(sessionId, session) {
+  scheduleReconnect(sessionId, _session) {
     const conn = this.connections.get(sessionId);
     if (!conn || conn.closed) return;
     conn.ws = null;