aigo 1.0.0

package/specs/claude-code-web-terminal.md

@@ -0,0 +1,258 @@
+# Vigo - Claude Code Web Terminal
+
+## Overview
+
+**vigo** is a CLI tool that lets you run Claude Code remotely from any device. It wraps Claude in a tmux session and streams it to your browser via WebSocket.
+
+```bash
+# Start Claude Code accessible from anywhere
+vigo --tunnel ngrok claude --model sonnet
+
+# Output:
+# ✓ tmux session: claude-code
+# ✓ Web server: http://localhost:3000
+# ✓ ngrok tunnel: https://abc123.ngrok.io
+# 
+# Access URL: https://abc123.ngrok.io/t/x7k9m2...
+```
+
+## CLI Interface
+
+```
+vigo [vigo-options] claude [claude-args]
+vigo [vigo-options] --attach <session>
+
+Vigo Options:
+  --port, -p <port>       Web server port (default: 3000)
+  --session, -s <name>    tmux session name (default: claude-code)
+  --tunnel, -t <type>     Auto-start tunnel: ngrok, cloudflared, none (default: none)
+  --attach, -a <session>  Attach to existing tmux session (don't start claude)
+  --help, -h              Show help
+
+Examples:
+  vigo claude                           # Basic: start claude in tmux + web server
+  vigo --tunnel ngrok claude            # With ngrok tunnel
+  vigo -p 8080 -s myproject claude      # Custom port and session
+  vigo claude --model sonnet            # Pass args to claude
+  vigo --attach myproject               # Attach to existing session
+```
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph cli [vigo CLI]
+        CLI[bin/vigo.js]
+        CLI --> TMUX_MGR[tmux manager]
+        CLI --> SERVER[web server]
+        CLI --> TUNNEL[tunnel manager]
+    end
+    
+    subgraph local [Local Processes]
+        TMUX[tmux session]
+        CLAUDE[claude CLI]
+        TMUX_MGR --> TMUX
+        TMUX --> CLAUDE
+    end
+    
+    subgraph web [Web Layer]
+        EXPRESS[Express :3000]
+        WS[WebSocket]
+        PTY[node-pty]
+        SERVER --> EXPRESS
+        SERVER --> WS
+        WS <--> PTY
+        PTY <-->|attach| TMUX
+    end
+    
+    subgraph remote [Remote Access]
+        NGROK[ngrok/cloudflared]
+        BROWSER[Browser + xterm.js]
+        TUNNEL --> NGROK
+        NGROK <--> BROWSER
+        EXPRESS --> BROWSER
+        WS <--> BROWSER
+    end
+```
+
+## Project Structure
+
+```
+vigo/
+├── package.json              # dependencies + bin entry
+├── bin/
+│   └── vigo.js               # CLI entry point (#!/usr/bin/env node)
+├── lib/
+│   ├── cli.js                # Argument parsing
+│   ├── tmux.js               # tmux session management
+│   ├── server.js             # Express + WebSocket server
+│   └── tunnel.js             # ngrok/cloudflared spawning
+├── public/
+│   ├── index.html            # Terminal UI
+│   └── terminal.js           # xterm.js setup
+└── README.md
+```
+
+## Implementation Details
+
+### 1. CLI Entry Point (bin/vigo.js)
+
+- Shebang for direct execution: `#!/usr/bin/env node`
+- Parse arguments, separating vigo args from claude args
+- Orchestrate: tmux → server → tunnel (if requested)
+- Handle graceful shutdown (Ctrl+C kills tunnel, keeps tmux alive)
+
+### 2. Argument Parsing (lib/cli.js)
+
+```javascript
+// vigo --port 8080 --tunnel ngrok claude --model sonnet --allowedTools Bash
+// 
+// Parsed as:
+// vigoArgs = { port: 8080, tunnel: 'ngrok', session: 'claude-code' }
+// claudeArgs = ['--model', 'sonnet', '--allowedTools', 'Bash']
+```
+
+- Split on `claude` keyword
+- Everything before = vigo options
+- Everything after = passed to claude CLI
+
+### 3. tmux Manager (lib/tmux.js)
+
+```javascript
+// Check if session exists
+tmux.hasSession(name)  // returns boolean
+
+// Create new session running claude
+tmux.newSession(name, ['claude', ...claudeArgs])
+
+// For --attach mode: just verify session exists
+```
+
+Uses `child_process.execSync` for tmux commands.
+
+### 4. Web Server (lib/server.js)
+
+- Generate 32-byte secure token
+- Serve static files from `public/`
+- Validate token on all requests
+- WebSocket endpoint spawns `tmux attach-session -t <name>`
+- Bridge node-pty ↔ WebSocket
+- Handle resize messages
+
+### 5. Tunnel Manager (lib/tunnel.js)
+
+```javascript
+// Spawn ngrok and parse the public URL from stdout
+const tunnel = await startTunnel('ngrok', port);
+console.log(`Tunnel URL: ${tunnel.url}`);
+
+// On exit, tunnel.kill() is called
+```
+
+- Spawn `ngrok http <port>` or `cloudflared tunnel --url http://localhost:<port>`
+- Parse public URL from output
+- Return URL for display
+
+### 6. Frontend (public/index.html)
+
+- Full-screen xterm.js terminal
+- Dark aesthetic (deep black background, subtle glow)
+- Load xterm.js + addons from CDN
+- WebSocket connection to `/ws/:token`
+- Auto-reconnect on disconnect
+- Send resize events on window resize
+
+## Token Security
+
+- Generated once per `vigo` invocation
+- 32 bytes from `crypto.randomBytes()` → 64 char hex
+- Embedded in URL path: `/t/<token>`
+- Required for both HTTP and WebSocket
+- Printed to console on startup
+
+## Usage Flow
+
+```bash
+# 1. Install globally (or use npx)
+npm install -g .
+
+# 2. Run vigo with Claude
+vigo --tunnel ngrok claude --model sonnet
+
+# 3. Output shows access URL
+# ┌─────────────────────────────────────────────────┐
+# │  vigo - Claude Code Web Terminal                │
+# ├─────────────────────────────────────────────────┤
+# │  tmux session:  claude-code                     │
+# │  Local server:  http://localhost:3000           │
+# │  Tunnel:        https://a1b2c3.ngrok.io         │
+# │                                                 │
+# │  Access URL:                                    │
+# │  https://a1b2c3.ngrok.io/t/f8e2a1...           │
+# └─────────────────────────────────────────────────┘
+
+# 4. Open URL on phone/tablet - full Claude Code access!
+
+# 5. Ctrl+C stops server + tunnel, tmux session persists
+#    Re-attach later with: vigo --attach claude-code
+```
+
+## Dependencies
+
+```json
+{
+  "name": "vigo",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "vigo": "./bin/vigo.js"
+  },
+  "dependencies": {
+    "express": "^4.21.0",
+    "ws": "^8.18.0",
+    "node-pty": "^1.0.0"
+  }
+}
+```
+
+No build step. Frontend loads xterm.js from CDN.
+
+---
+
+## Future: Phase 2 - WebRTC P2P Mode
+
+> **Status:** Planned for future implementation
+
+### New CLI option
+
+```bash
+vigo --tunnel relay claude    # Use self-hosted WebRTC relay
+```
+
+### Architecture
+
+```mermaid
+sequenceDiagram
+    participant Local as vigo (local)
+    participant Signal as Railway Signaling Server
+    participant Browser as Mobile Browser
+    
+    Local->>Signal: Register session
+    Browser->>Signal: Request connection
+    Signal-->>Local: SDP offer
+    Local-->>Signal: SDP answer
+    Note over Local,Browser: WebRTC DataChannel P2P
+    Browser<-->Local: Direct terminal stream
+```
+
+### Components to add
+
+1. **Signaling server** (new repo, deploy to Railway)
+2. **WebRTC module** in vigo (`lib/webrtc.js`)
+3. **Frontend WebRTC client** 
+
+### Benefits
+
+- No ngrok dependency
+- Lower latency (direct P2P)
+- Free Railway tier for signaling

package/specs/cursor-cli-support.md

@@ -0,0 +1,139 @@
+# Cursor CLI Support for vigo
+
+## Overview
+
+Add support for Cursor Agent CLI alongside Claude Code, allowing vigo to stream either tool to a browser via WebSocket. This enables users with Cursor subscriptions to access Cursor's AI features remotely.
+
+## Architecture Comparison
+
+```mermaid
+flowchart TB
+    subgraph current [Current: Claude Code]
+        vigo1[vigo] --> tmux1[tmux session]
+        tmux1 --> claude[claude CLI]
+        claude --> ws1[WebSocket]
+        ws1 --> browser1[Browser xterm.js]
+    end
+    
+    subgraph new [New: Cursor Agent]
+        vigo2[vigo] --> tmux2[tmux session]
+        tmux2 --> agent[agent CLI]
+        agent --> ws2[WebSocket]
+        ws2 --> browser2[Browser xterm.js]
+    end
+```
+
+The architecture is nearly identical - both are CLI-based terminal applications that can run in tmux.
+
+## Technical Feasibility: HIGH
+
+Cursor Agent CLI is architecturally similar to Claude Code:
+
+- Both are terminal-based interactive CLI applications
+- Both support conversational sessions (`agent` vs `claude`)
+- Both can run headless in any terminal environment
+
+## Key Differences to Handle
+
+| Aspect | Claude Code | Cursor Agent |
+|--------|-------------|--------------|
+| Command | `claude` | `agent` |
+| Install | npm/standalone | `curl https://cursor.com/install -fsS \| bash` |
+| Auth | Claude API key / OAuth | Browser login or `CURSOR_API_KEY` |
+| Models | Claude models | Multiple models (GPT-5, Claude, etc.) via subscription |
+
+## Implementation Changes
+
+### 1. CLI Argument Parsing ([lib/cli.js](lib/cli.js))
+
+Add detection for `cursor` or `agent` command in addition to `claude`:
+
+```javascript
+// Current: looks for 'claude' keyword
+if (arg === 'claude') { ... }
+
+// New: also detect 'cursor' or 'agent'  
+if (arg === 'claude' || arg === 'cursor' || arg === 'agent') { ... }
+```
+
+### 2. Session Management ([lib/tmux.js](lib/tmux.js))
+
+Generalize `createSession` to accept any command:
+
+```javascript
+// Current
+export function createSession(name, claudeArgs = []) {
+  const claudeCmd = ['claude', ...claudeArgs].join(' ');
+  // ...
+}
+
+// New: Parameterize the command
+export function createSession(name, command, args = []) {
+  const cmd = [command, ...args].join(' ');
+  // ...
+}
+```
+
+### 3. Default Session Names
+
+- Claude sessions: `claude-code` (unchanged)
+- Cursor sessions: `cursor-agent` (new default)
+
+### 4. Binary Detection
+
+Add Cursor CLI detection similar to tmux detection:
+
+```javascript
+export function getCursorAgentPath() {
+  try {
+    return execSync('which agent', { encoding: 'utf-8' }).trim();
+  } catch { return null; }
+}
+```
+
+## Authentication Considerations
+
+**For Cursor CLI:**
+
+1. **Browser login (recommended for interactive)**: User runs `agent login` before starting vigo
+2. **API key (for headless/automation)**: Set `CURSOR_API_KEY` environment variable
+
+vigo should:
+
+- Check if authentication is configured before starting
+- Provide clear error messages if not authenticated
+- Document the authentication flow in README
+
+## Usage Examples
+
+```bash
+# Start Claude Code (existing)
+vigo claude
+
+# Start Cursor Agent (new)
+vigo cursor
+# or
+vigo agent
+
+# With tunnel for remote access
+vigo --tunnel ngrok cursor
+
+# Pass arguments to Cursor Agent
+vigo cursor --model gpt-5
+```
+
+## Requirements Update
+
+Add to README:
+
+- **Cursor CLI** installed (`agent` command) - for Cursor support
+- Install via: `curl https://cursor.com/install -fsS | bash`
+- Authenticate via: `agent login`
+
+## Files Modified
+
+1. [lib/cli.js](lib/cli.js) - Add cursor/agent command detection
+2. [lib/tmux.js](lib/tmux.js) - Generalize command execution
+3. [bin/vigo.js](bin/vigo.js) - Update startup logic for both tools
+4. [README.md](README.md) - Document Cursor support
+5. [lib/cursor.js](lib/cursor.js) - Cursor-specific utilities