aigo 1.0.0

package/AGENTS.md

@@ -0,0 +1 @@
+- Always update README.md if there's changes to the code. Ensure that README.md would always reflect the latest state of this codebase

package/README.md

@@ -0,0 +1,453 @@
+# vigo
+
+Stream AI coding assistants to the web - run Claude Code or Cursor Agent remotely from any device.
+
+**vigo** wraps Claude Code or Cursor Agent in a tmux session and streams it to your browser via WebSocket, letting you access your AI coding sessions from your phone, tablet, or any browser.
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Install globally (optional)
+npm link
+
+# Start Claude Code with web access (ngrok tunnel enabled by default)
+vigo claude
+
+# Or start Cursor Agent
+vigo cursor
+
+# Local only (no tunnel)
+vigo --tunnel none claude
+```
+
+## Requirements
+
+- **Node.js** 18+
+- **tmux** installed and in PATH
+- **Claude Code CLI** installed (`claude` command) - for Claude Code support
+- **Cursor Agent CLI** installed (`agent` command) - for Cursor support
+- **ngrok** (required for default remote access) - sign up at [ngrok.com](https://ngrok.com)
+
+### Installing tmux
+
+```bash
+# macOS
+brew install tmux
+
+# Ubuntu/Debian
+sudo apt install tmux
+
+# Arch Linux
+sudo pacman -S tmux
+```
+
+### Installing ngrok
+
+```bash
+# macOS
+brew install ngrok
+
+# Or download from https://ngrok.com/download
+
+# Then authenticate (required)
+ngrok config add-authtoken YOUR_TOKEN
+```
+
+### Installing Cursor Agent CLI
+
+```bash
+# Install Cursor CLI
+curl https://cursor.com/install -fsS | bash
+
+# Authenticate (required before first use)
+agent login
+
+# Or use API key for headless/automation
+export CURSOR_API_KEY=your_api_key_here
+```
+
+## Usage
+
+```
+vigo [options] claude [claude-args]
+vigo [options] cursor [cursor-args]
+vigo [options] agent [agent-args]
+vigo [options] --attach <session>
+
+Tools:
+  claude                    Use Claude Code CLI
+  cursor, agent             Use Cursor Agent CLI
+
+Options:
+  --port, -p <port>         Web server port (default: 3000, auto-selects if busy)
+  --session, -s <name>      tmux session name (default: claude-code or cursor-agent)
+  --tunnel, -t <type>       Tunnel: ngrok, cloudflared, none (default: ngrok)
+  --attach, -a <session>    Attach to existing tmux session
+  --password, -P <pass>     Custom password (default: auto-generated 6-char)
+  --timeout, -T <mins>      Lock screen after inactivity (default: 0=disabled)
+  --exit-timeout, -E <mins> Exit session after inactivity (default: 0=disabled)
+  --help, -h                Show help
+  --version, -v             Show version
+```
+
+### Examples
+
+```bash
+# Claude Code Examples (ngrok tunnel by default)
+vigo claude                           # Start Claude with ngrok tunnel
+vigo --tunnel none claude             # Local only (no tunnel)
+vigo -p 8080 -s myproject claude      # Custom port and session
+vigo claude --model sonnet            # Pass args to Claude
+
+# Cursor Agent Examples
+vigo cursor                           # Start Cursor Agent with ngrok tunnel
+vigo --tunnel cloudflared cursor      # Use cloudflared instead of ngrok
+vigo -p 8080 -s myproject cursor      # Custom port and session
+vigo cursor --model gpt-5             # Pass args to Cursor Agent
+
+# General Examples
+vigo --attach myproject               # Attach to existing tmux session
+vigo -P mypass123 claude              # Custom password
+vigo -T 15 -E 30 cursor               # 15min lock, 30min exit timeout
+vigo -T 0 -E 0 claude                 # Disable timeouts (default behavior)
+
+# Run multiple sessions (ports auto-selected)
+vigo -s project-a claude              # Gets port 3000
+vigo -s project-b cursor              # Gets port 3001 (auto)
+```
+
+## Configuration
+
+All defaults can be customized by editing `lib/config.js`:
+
+```javascript
+export const config = {
+  // Server Settings
+  defaultPort: 3000,
+  defaultTunnel: 'ngrok',        // 'ngrok', 'cloudflared', or 'none'
+  
+  // Session Timeouts (minutes, 0 = disabled)
+  lockTimeout: 0,                // Lock screen after inactivity (default: disabled)
+  exitTimeout: 0,                // Exit session after inactivity (default: disabled)
+  
+  // Tool Settings
+  defaultTool: 'claude',         // 'claude' or 'cursor'
+  
+  // Security Settings
+  passwordLength: 6,
+  tokenBytes: 2,                 // URL token length (hex = 2x chars)
+  
+  // ... more options
+};
+```
+
+## How It Works
+
+1. **vigo** creates a tmux session and runs `claude` or `agent` inside it
+2. A local web server starts, serving an xterm.js terminal
+3. The server attaches to the tmux session via node-pty
+4. Your browser connects via WebSocket for real-time terminal streaming
+5. ngrok creates a public HTTPS tunnel for remote access (default)
+
+```
+┌────────────────────────────────────────┐
+│  vigo - Claude Code Web Terminal       │
+├────────────────────────────────────────┤
+│  Session:  claude-code                 │
+│  Local:    http://localhost:3000       │
+│  Tunnel:   https://abc123.ngrok.io     │
+│  Password: Xk7mNp                      │
+│  Timeout:  lock:off exit:off           │
+└────────────────────────────────────────┘
+
+Access URL:
+  https://abc123.ngrok.io/t/a1b2c3d4...
+```
+
+## Cursor vs Claude Code
+
+| Feature | Claude Code | Cursor Agent |
+|---------|-------------|--------------|
+| Command | `vigo claude` | `vigo cursor` |
+| CLI Binary | `claude` | `agent` |
+| Authentication | Claude API key / OAuth | Browser login or `CURSOR_API_KEY` |
+| Models | Claude models | Multiple (GPT-5, Claude, etc.) via subscription |
+| Session Default | `claude-code` | `cursor-agent` |
+
+**When to use Cursor:** If you have a Cursor subscription but don't have direct Claude API access, Cursor Agent provides an alternative way to access AI coding assistance remotely.
+
+## Security
+
+vigo uses multiple layers of security:
+
+1. **URL Token** - A random 4-character token in the URL path (`/t/<token>`)
+2. **Password** - A 6-character alphanumeric password (or custom password via `-P`)
+3. **Session Lock** - Screen locks after inactivity (disabled by default, enable with `-T <mins>`)
+4. **Auto Exit** - Session terminates after inactivity (disabled by default, enable with `-E <mins>`)
+
+**Security features:**
+- Token required in URL (403 Forbidden without it)
+- Password required before terminal access
+- Password uses unambiguous characters (no 0/O, 1/l/I)
+- Lock screen requires re-entering password after inactivity (when enabled)
+- Session auto-terminates and kills tmux after extended inactivity (when enabled)
+- HTTPS via ngrok (encrypted in transit)
+
+**Recommendations:**
+- Use HTTPS (ngrok provides this automatically)
+- Don't share your access URL or password publicly
+- Use strong custom passwords for sensitive sessions
+- Enable timeouts (`-T 15 -E 30`) for shared or sensitive environments
+
+## Session Timeouts
+
+vigo has two optional timeout mechanisms (both disabled by default for persistent sessions):
+
+### Lock Timeout (default: disabled)
+When enabled with `-T <minutes>`, the session locks after the specified period of no interaction (mouse movement, typing, etc.) and requires password re-entry. The WebSocket connection stays open, so you don't lose any terminal state.
+
+### Exit Timeout (default: disabled)
+When enabled with `-E <minutes>`, the session completely terminates after the specified period of total inactivity (no user login or interaction):
+- The tmux session is killed
+- Claude Code / Cursor Agent is stopped
+- The server exits
+
+Enable timeouts for security in shared environments: `vigo -T 15 -E 30 claude`
+
+## Browser Notifications
+
+vigo can send browser notifications when:
+- The AI assistant is waiting for input
+- The WebSocket connection is lost
+
+Notifications are only sent when the browser tab is not active. Allow notifications when prompted for the best experience.
+
+## Mobile Controls
+
+When accessing vigo from a mobile device (phone or tablet), control buttons appear at the bottom of the screen:
+
+| Button | Action | Description |
+|--------|--------|-------------|
+| **Mode** | `Shift+Tab` | Toggle between chat/edit modes in Claude Code or switch modes in Cursor Agent |
+| **Enter** | `Enter` | Send Enter key to confirm prompts or submit input |
+| **Stop** | `Ctrl+C` | Interrupt the current operation (stop running commands or cancel AI responses) |
+| **Exit** | Cleanup | Shows confirmation dialog, then kills tmux session and stops the server |
+
+These buttons are useful because mobile keyboards don't easily support modifier key combinations like Ctrl+C or Shift+Tab.
+
+The buttons are automatically shown based on:
+- Touch screen capability
+- Mobile user agent detection
+- Screen width (768px or less)
+- Coarse pointer media query (touch screens)
+
+## Running Persistently
+
+To keep vigo running indefinitely (even after closing your terminal), run it inside tmux or use a process manager:
+
+```bash
+# Run vigo inside its own tmux session
+tmux new-session -d -s vigo-server 'vigo claude'
+
+# Attach to check status
+tmux attach -t vigo-server
+
+# Or use pm2 for auto-restart on crash
+pm2 start "vigo claude" --name vigo-session
+```
+
+When the vigo server stays running, your ngrok URL remains stable and you can return to the same URL anytime.
+
+## Auto Port Selection
+
+If the default port (3000) or your specified port is already in use, vigo automatically finds the next available port:
+
+```
+⚠ Port 3000 in use, using port 3001 instead
+```
+
+This allows running multiple vigo sessions simultaneously without manual port management.
+
+## Exiting and Cleanup
+
+vigo provides different exit behaviors depending on how you terminate the session:
+
+### Exit Behavior Summary
+
+| Action | tmux Session | Server | Web Clients |
+|--------|-------------|--------|-------------|
+| **Web Exit button** | Killed | Stopped | Shows "Session Ended" |
+| **Console Ctrl+C** | **Persists** | Stopped | Disconnected |
+| **Inactivity timeout** | Killed | Stopped | Shows "Session Expired" |
+
+### Full Cleanup (from web interface)
+
+Click the **Exit** button in the top-right corner of the web interface to:
+1. Show a confirmation dialog
+2. Kill the PTY process
+3. Kill the tmux session
+4. Close all WebSocket connections
+5. Shut down the vigo server
+6. Exit the process
+
+**Result:** Everything is cleaned up - tmux session, server, and process all terminate. The web client shows a "Session Ended" message.
+
+This is useful when you're completely done with a session and want to free all resources.
+
+### Session Persistence (Ctrl+C on console)
+
+When you press `Ctrl+C` on the terminal running vigo:
+1. The web server stops
+2. The tunnel closes (if running)
+3. **The tmux session keeps running!**
+4. Connected web clients are disconnected
+
+**Result:** Server stops but the tmux session persists. This is useful when you want to temporarily stop web access but keep the AI session alive.
+
+Re-attach later:
+
+```bash
+# Via vigo (starts new web server for existing session)
+vigo --attach claude-code
+vigo --attach cursor-agent
+
+# Or directly with tmux (local terminal only)
+tmux attach -t claude-code
+tmux attach -t cursor-agent
+```
+
+### Inactivity Timeout Exit
+
+When the exit timeout is enabled and reached:
+1. Server detects no user activity for the configured duration
+2. Kills the tmux session
+3. Notifies all connected clients with "Session Expired" message
+4. Closes all WebSocket connections
+5. Shuts down the server
+6. Exits the process
+
+**Result:** Full cleanup, similar to web exit. Web clients see a "Session Expired" overlay.
+
+**Note:** Exit timeout is disabled by default. Enable with `--exit-timeout <mins>` or `-E <mins>` for security in shared environments.
+
+## Troubleshooting
+
+### "tmux: command not found"
+
+Install tmux (see Requirements section above).
+
+### "claude: command not found"
+
+Make sure Claude Code CLI is installed and in your PATH:
+
+```bash
+# Check if claude is available
+which claude
+```
+
+### "agent: command not found" (Cursor)
+
+Install the Cursor Agent CLI:
+
+```bash
+# Install
+curl https://cursor.com/install -fsS | bash
+
+# Verify installation
+which agent
+```
+
+### Cursor authentication issues
+
+Make sure you're authenticated:
+
+```bash
+# Interactive login (opens browser)
+agent login
+
+# Check status
+agent status
+
+# Or use API key
+export CURSOR_API_KEY=your_api_key_here
+```
+
+### "posix_spawnp failed" error
+
+This can happen if node-pty's spawn-helper isn't executable. Fix with:
+
+```bash
+chmod +x node_modules/node-pty/prebuilds/darwin-*/spawn-helper
+```
+
+Or reinstall dependencies:
+
+```bash
+rm -rf node_modules && npm install
+```
+
+### ngrok authentication error
+
+Sign up at [ngrok.com](https://ngrok.com) and authenticate:
+
+```bash
+ngrok config add-authtoken YOUR_TOKEN
+```
+
+### "ngrok already running" / simultaneous session error
+
+Free ngrok accounts are limited to 1 simultaneous tunnel. If you see this error, it means an ngrok process from a previous session is still running.
+
+vigo will detect this and show you the command to kill it:
+
+```
+Error: An ngrok process is already running.
+Free ngrok accounts only allow 1 simultaneous tunnel.
+
+To kill the existing ngrok process, run:
+  kill 12345
+
+Or to run without a tunnel:
+  vigo --tunnel none cursor
+```
+
+You can also find and kill ngrok manually:
+
+```bash
+# Find ngrok processes
+pgrep -f "ngrok http"
+
+# Kill by PID
+kill <pid>
+
+# Or kill all ngrok processes
+pkill -f "ngrok http"
+```
+
+### WebSocket connection fails
+
+- Check that the server is running
+- Ensure the URL includes the correct token
+- If using a tunnel, make sure it's still active
+
+### Terminal looks broken / garbled
+
+Try resizing your browser window to trigger a terminal resize.
+
+## Development
+
+```bash
+# Run without installing globally
+node bin/vigo.js claude
+node bin/vigo.js cursor
+
+# Watch for changes (requires nodemon)
+npx nodemon bin/vigo.js claude
+```
+
+## License
+
+MIT