---

Quick Start

npx itwillsync claude        # Claude Code
npx itwillsync aider         # Aider
npx itwillsync bash          # or any terminal command

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 — a terminal opens in your browser
4. Control your agent from your phone, laptop, or both simultaneously

When To Use It

• 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

Multi-Session Dashboard

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  │                    │
│  └─────────────┘                    │
└─────────────────────────────────────┘

• 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

Works With

Claude Code, Aider, Goose, Codex, Cline, Copilot CLI — or any terminal-based tool.

npx itwillsync claude          # Claude Code
npx itwillsync aider           # Aider
npx itwillsync goose            # Goose
npx itwillsync "codex --quiet"  # Codex
npx itwillsync bash             # Plain shell

If it runs in a terminal, itwillsync can sync it.

Connection Modes

Mode	Command	When
Local WiFi (default)	npx itwillsync claude	Phone on same network
Tailscale	npx itwillsync --tailscale claude	Any network, anywhere
Localhost	npx itwillsync --localhost claude	Same machine only

On first run, a setup wizard detects your network and saves your preference.

# 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

Flag	Description
--port <number>	Port to listen on (default: 7964)
--localhost	Bind to 127.0.0.1 only
--tailscale	Use Tailscale for this session
--local	Use local WiFi for this session
--no-qr	Don't display QR code
setup	Run the setup wizard
-h, --help	Show help
-v, --version	Show version

Security

• 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

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 for development setup and PR guidelines.

License

MIT