itwillsync 1.7.1 → 1.8.1

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)