minivibe 0.1.0 → 0.1.2

package/GETTING_STARTED.md

@@ -0,0 +1,241 @@
+# Getting Started with MiniVibe CLI
+
+This guide walks you through setting up MiniVibe CLI to control Claude Code from your iOS device.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+1. **Node.js 18+** installed
+2. **Claude Code CLI** installed and working (`claude --version`)
+3. **MiniVibe iOS app** installed on your iPhone/iPad
+4. **Python 3** (macOS/Linux) or **node-pty** (Windows)
+
+## Step 1: Install MiniVibe CLI
+
+```bash
+npm install -g minivibe
+```
+
+Verify installation:
+
+```bash
+vibe --help
+vibe-agent --help
+```
+
+## Step 2: Authenticate
+
+### On Desktop/Laptop (with browser)
+
+```bash
+vibe --login
+```
+
+This opens your browser for Google sign-in. After signing in, authentication is saved automatically.
+
+### On Server/EC2 (headless)
+
+```bash
+vibe --login --headless
+```
+
+You'll see output like:
+
+```
+Requesting device code...
+   Visit:  https://ws.neng.ai/device
+   Code:   ABC123
+
+   Code expires in 5 minutes.
+   Waiting for authentication...
+```
+
+1. On your phone or another computer, visit the URL shown
+2. Enter the code
+3. Sign in with Google
+4. The CLI will automatically detect the login and save your token
+
+## Step 3: Choose Your Setup
+
+### Option A: Direct Mode (Simple)
+
+Best for: Single session, desktop use
+
+```bash
+vibe --bridge wss://ws.neng.ai
+```
+
+### Option B: Agent Mode (Recommended for Servers)
+
+Best for: EC2, multiple sessions, persistent connection
+
+**Terminal 1 - Start the agent:**
+
+```bash
+vibe-agent --bridge wss://ws.neng.ai
+```
+
+Keep this running. The agent maintains the bridge connection and manages all sessions.
+
+**Terminal 2+ - Create sessions:**
+
+```bash
+vibe --agent
+```
+
+## Step 4: Connect from iOS
+
+1. Open the **MiniVibe** app on your iOS device
+2. Sign in with the same Google account
+3. Your sessions will appear automatically
+4. Tap a session to view, send messages, and approve permissions
+
+## Common Workflows
+
+### Basic Development Session
+
+```bash
+# Start a named session
+vibe --agent --name "Feature: User Auth"
+
+# Claude will start, you can work locally
+# Monitor and control from iOS app
+```
+
+### Automated Tasks
+
+```bash
+# Skip all permission prompts (use with caution!)
+vibe --agent --dangerously-skip-permissions "Run all tests and fix failures"
+```
+
+### Resume Previous Session
+
+```bash
+# Find session ID from iOS app or previous output
+vibe --agent --resume abc12345-6789-...
+```
+
+## Running Agent as a Service
+
+### Using systemd (Linux)
+
+Create `/etc/systemd/system/vibe-agent.service`:
+
+```ini
+[Unit]
+Description=MiniVibe Agent
+After=network.target
+
+[Service]
+Type=simple
+User=ubuntu
+WorkingDirectory=/home/ubuntu
+ExecStart=/usr/bin/vibe-agent --bridge wss://ws.neng.ai
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start:
+
+```bash
+sudo systemctl enable vibe-agent
+sudo systemctl start vibe-agent
+```
+
+### Using tmux/screen
+
+```bash
+# Start in detached tmux session
+tmux new-session -d -s vibe-agent "vibe-agent --bridge wss://ws.neng.ai"
+
+# Attach to view logs
+tmux attach -t vibe-agent
+```
+
+### Using pm2
+
+```bash
+npm install -g pm2
+pm2 start vibe-agent -- --bridge wss://ws.neng.ai
+pm2 save
+pm2 startup
+```
+
+## Troubleshooting
+
+### "Session file not found"
+
+This is normal during startup. The session file is created when Claude starts processing. If it persists:
+
+1. Check Claude Code is installed: `claude --version`
+2. Check the projects directory exists: `ls ~/.claude/projects/`
+
+### "Authentication failed"
+
+Token may have expired. Re-authenticate:
+
+```bash
+vibe --logout
+vibe --login --headless
+```
+
+### Agent not discovered
+
+If `vibe --agent` can't find the agent:
+
+```bash
+# Specify agent URL explicitly
+vibe --agent ws://localhost:9999
+
+# Check agent is running
+ps aux | grep vibe-agent
+```
+
+### Permission prompts not appearing on iOS
+
+1. Ensure you're signed into the same Google account on both CLI and iOS
+2. Check the session is "active" in the iOS app
+3. Verify bridge connection: look for "Connected to bridge" in CLI output
+
+## Architecture Overview
+
+```
+Your Mac/PC                          Cloud                    Your iPhone
+┌─────────────────┐                                          ┌─────────────┐
+│                 │                                          │             │
+│  Terminal 1     │                                          │  MiniVibe   │
+│  ┌───────────┐  │     ┌─────────────────┐                  │    App      │
+│  │vibe-agent │──┼────▶│  Bridge Server  │◀─────────────────│             │
+│  └───────────┘  │     │ ws.neng.ai      │                  │  - View     │
+│       ▲         │     └─────────────────┘                  │  - Chat     │
+│       │         │                                          │  - Approve  │
+│  Terminal 2     │                                          │             │
+│  ┌───────────┐  │                                          └─────────────┘
+│  │   vibe    │──┘
+│  │ + Claude  │
+│  └───────────┘
+│                 │
+└─────────────────┘
+```
+
+1. **vibe-agent** connects to the bridge server and stays connected
+2. **vibe --agent** connects to the local agent, which spawns Claude Code
+3. Messages flow: iOS ↔ Bridge ↔ Agent ↔ vibe ↔ Claude
+4. Permissions appear on iOS for approval
+
+## Next Steps
+
+- Explore session management in the iOS app
+- Set up multiple named sessions for different projects
+- Configure auto-start on your development servers
+- Check token usage in iOS Settings
+
+## Getting Help
+
+- GitHub Issues: https://github.com/python3isfun/neng/issues
+- Check `vibe --help` and `vibe-agent --help` for all options

package/README.md

@@ -0,0 +1,213 @@
+# MiniVibe CLI
+
+CLI wrapper for Claude Code with mobile remote control via MiniVibe iOS app.
+
+## Features
+
+- Remote control Claude Code from your iOS device
+- Agent mode for managing multiple sessions
+- Session management with resume capability
+- Permission handling from mobile
+- Token usage tracking
+- Headless authentication for servers (EC2, etc.)
+- Skip permissions mode for automation
+
+## Quick Start
+
+```bash
+# Install globally from npm
+npm install -g minivibe
+
+# Authenticate (one-time)
+vibe --login              # Desktop (opens browser)
+vibe --login --headless   # Server/EC2 (device code)
+
+# Option 1: Direct bridge connection
+vibe --bridge wss://ws.neng.ai
+
+# Option 2: Agent mode (recommended for servers)
+vibe-agent --bridge wss://ws.neng.ai &   # Start agent
+vibe --agent                              # Create sessions
+```
+
+See [GETTING_STARTED.md](GETTING_STARTED.md) for detailed setup instructions.
+
+## Installation
+
+### From npm (Recommended)
+
+```bash
+npm install -g minivibe
+```
+
+This installs two commands:
+- `vibe` - Start Claude Code sessions
+- `vibe-agent` - Background agent for managing sessions
+
+### From Source
+
+```bash
+git clone https://github.com/python3isfun/neng.git
+cd neng/vibe-cli
+npm install
+npm link
+```
+
+## Authentication
+
+### Browser Login (Desktop)
+
+```bash
+vibe --login
+```
+
+Opens browser for Google sign-in. Token is saved to `~/.vibe/auth.json`.
+
+### Headless Login (Servers/EC2)
+
+```bash
+vibe --login --headless
+```
+
+Displays a device code. Visit the URL on any device to authenticate.
+
+### Manual Token
+
+```bash
+vibe --token <firebase-token>
+```
+
+Get token from MiniVibe iOS app: Settings > Copy Token for CLI.
+
+## Usage Modes
+
+### Direct Bridge Mode
+
+Connect directly to the bridge server:
+
+```bash
+vibe --bridge wss://ws.neng.ai
+vibe --bridge wss://ws.neng.ai "Fix the bug in main.js"
+```
+
+### Agent Mode (Recommended for Servers)
+
+Use a local agent to manage sessions:
+
+```bash
+# Terminal 1: Start the agent (runs continuously)
+vibe-agent --bridge wss://ws.neng.ai
+
+# Terminal 2+: Create sessions via agent
+vibe --agent
+vibe --agent "Deploy the application"
+vibe --agent --name "Backend Work"
+```
+
+**Benefits of Agent Mode:**
+- Single bridge connection for multiple sessions
+- Start/stop sessions remotely from iOS app
+- Sessions survive network hiccups
+- Cleaner process management
+
+### Local Mode (No Bridge)
+
+Run without remote control:
+
+```bash
+vibe                          # Interactive
+vibe "Explain this code"      # With prompt
+```
+
+## Options
+
+### vibe
+
+| Option | Description |
+|--------|-------------|
+| `--bridge <url>` | Connect to bridge server |
+| `--agent [url]` | Connect via local vibe-agent (default: auto-discover) |
+| `--name <name>` | Name this session (shown in mobile app) |
+| `--resume <id>` | Resume a previous session |
+| `--login` | Sign in with Google |
+| `--headless` | Use device code flow for headless environments |
+| `--token <token>` | Set Firebase auth token manually |
+| `--logout` | Remove stored auth token |
+| `--dangerously-skip-permissions` | Auto-approve all tool executions |
+| `--node-pty` | Use Node.js PTY wrapper (required for Windows) |
+| `--help, -h` | Show help message |
+
+### vibe-agent
+
+| Option | Description |
+|--------|-------------|
+| `--bridge <url>` | Bridge server URL (required) |
+| `--port <port>` | Local WebSocket port (default: 9999) |
+| `--help, -h` | Show help message |
+
+## In-Session Commands
+
+| Command | Description |
+|---------|-------------|
+| `/name <name>` | Rename the current session |
+| `//` | Type literal `/` (escape sequence) |
+| `Escape` | Cancel command mode, forward to Claude |
+| `Ctrl+C` | Cancel command mode, forward to Claude |
+
+## Skip Permissions Mode
+
+For automated/headless environments where you trust the execution context:
+
+```bash
+vibe --dangerously-skip-permissions --bridge wss://ws.neng.ai
+vibe --dangerously-skip-permissions --agent
+```
+
+**Warning:** This mode auto-approves ALL tool executions (commands, file writes, etc.) without prompting. Only use in trusted/sandboxed environments.
+
+## Architecture
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  MiniVibe   │────▶│   Bridge    │◀────│ vibe-agent  │◀────│    vibe     │
+│  iOS App    │     │   Server    │     │  (daemon)   │     │  (session)  │
+└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
+```
+
+**Direct mode:** `vibe --bridge` connects directly to bridge server
+
+**Agent mode:** `vibe --agent` connects to local `vibe-agent`, which manages bridge connection
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Claude Code CLI installed and in PATH
+- Python 3 (for Unix PTY wrapper) or node-pty (for Windows)
+
+## Platform Notes
+
+### macOS/Linux
+
+Uses Python PTY wrapper by default. Requires `python3`.
+
+### Windows
+
+Requires `node-pty`:
+
+```bash
+npm install node-pty
+```
+
+May also need Visual Studio Build Tools and Python for native compilation.
+
+## Files
+
+| Path | Description |
+|------|-------------|
+| `~/.vibe/auth.json` | Stored authentication (token + refresh token) |
+| `~/.vibe/token` | Legacy token file |
+| `~/.vibe-agent/port` | Agent port file for auto-discovery |
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minivibe",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI wrapper for Claude Code with mobile remote control",
   "author": "neng.ai",
   "homepage": "https://github.com/python3isfun/neng",
@@ -21,7 +21,9 @@
     "login.html",
     "pty-wrapper.py",
     "pty-wrapper-node.js",
-    "agent/"
+    "agent/",
+    "README.md",
+    "GETTING_STARTED.md"
   ],
   "engines": {
     "node": ">=18.0.0"

package/vibe.js

@@ -382,6 +382,7 @@ let authToken = null;
 let headlessMode = false;
 let sessionName = null;
 let useNodePty = os.platform() === 'win32';  // Auto-detect Windows, can be overridden
+let skipPermissions = false;  // --dangerously-skip-permissions mode
 
 for (let i = 0; i < args.length; i++) {
   if (args[i] === '--help' || args[i] === '-h') {
@@ -407,10 +408,12 @@ Options:
   --token <token>  Set Firebase auth token manually
   --logout         Remove stored auth token
   --node-pty       Use Node.js PTY wrapper (required for Windows, optional for Unix)
+  --dangerously-skip-permissions   Run Claude without permission prompts (use with caution!)
   --help, -h       Show this help message
 
 In-Session Commands:
   /name <name>     Rename the current session
+  //               Type literal '/' (escape sequence)
 
 Authentication:
   Use --login to sign in via browser, or get token from MiniVibe iOS app.
@@ -466,6 +469,8 @@ Examples:
     process.exit(0);
   } else if (args[i] === '--node-pty') {
     useNodePty = true;
+  } else if (args[i] === '--dangerously-skip-permissions') {
+    skipPermissions = true;
   } else if (!args[i].startsWith('--')) {
     initialPrompt = args[i];
   }
@@ -534,12 +539,50 @@ function logStatus(msg) {
 
 // Get Claude session file path
 // Claude uses path with '/' replaced by '-' (not base64)
+// But the exact format may vary - we try multiple strategies
 function getSessionFilePath() {
-  const projectPathHash = process.cwd().replace(/\//g, '-');
-  const claudeDir = path.join(os.homedir(), '.claude', 'projects', projectPathHash);
-  return path.join(claudeDir, `${sessionId}.jsonl`);
+  const cwd = process.cwd();
+  const projectsDir = path.join(os.homedir(), '.claude', 'projects');
+
+  // Strategy 1: Direct replacement (e.g., /home/ubuntu -> -home-ubuntu)
+  const directHash = cwd.replace(/\//g, '-');
+
+  // Strategy 2: Without leading dash (e.g., home-ubuntu)
+  const noLeadingDash = directHash.replace(/^-/, '');
+
+  // Strategy 3: URL-safe encoding variations
+  const candidates = [directHash, noLeadingDash];
+
+  // Try to find existing directory that matches
+  if (fs.existsSync(projectsDir)) {
+    for (const candidate of candidates) {
+      const candidateDir = path.join(projectsDir, candidate);
+      if (fs.existsSync(candidateDir)) {
+        return path.join(candidateDir, `${sessionId}.jsonl`);
+      }
+    }
+
+    // Scan for session file in any project directory
+    try {
+      const dirs = fs.readdirSync(projectsDir);
+      for (const dir of dirs) {
+        const sessionFile = path.join(projectsDir, dir, `${sessionId}.jsonl`);
+        if (fs.existsSync(sessionFile)) {
+          return sessionFile;
+        }
+      }
+    } catch (err) {
+      // Ignore scan errors
+    }
+  }
+
+  // Fall back to direct hash (will be created by Claude)
+  return path.join(projectsDir, directHash, `${sessionId}.jsonl`);
 }
 
+// Cache for discovered session file path
+let discoveredSessionFile = null;
+
 // Get local IP
 function getLocalIP() {
   const interfaces = os.networkInterfaces();
@@ -910,28 +953,41 @@ function sendToBridge(data) {
 // ====================
 
 function startSessionFileWatcher() {
-  const sessionFile = getSessionFilePath();
-  logStatus(`Watching session file: ${sessionFile}`);
+  let sessionFile = getSessionFilePath();
+  logStatus(`Watching for session file: ${sessionFile}`);
 
-  // Also check what files actually exist in the projects directory
   const projectsDir = path.join(os.homedir(), '.claude', 'projects');
-  if (fs.existsSync(projectsDir)) {
-    const dirs = fs.readdirSync(projectsDir);
-    logStatus(`Found ${dirs.length} project directories in ${projectsDir}`);
-    // Look for our session in any directory
-    for (const dir of dirs.slice(0, 5)) { // Check first 5
-      const fullDir = path.join(projectsDir, dir);
-      if (fs.statSync(fullDir).isDirectory()) {
-        const files = fs.readdirSync(fullDir);
-        const sessionFiles = files.filter(f => f.includes(sessionId.slice(0, 8)));
-        if (sessionFiles.length > 0) {
-          logStatus(`Found session files in ${dir}: ${sessionFiles.join(', ')}`);
+  let fileCheckCount = 0;
+  let lastNotFoundLog = 0;
+  let fileFound = false;
+
+  // Function to scan for session file in all project directories
+  function scanForSessionFile() {
+    if (!fs.existsSync(projectsDir)) return null;
+
+    try {
+      const dirs = fs.readdirSync(projectsDir);
+      // Limit scan to 50 directories to avoid slowdown
+      const dirsToScan = dirs.slice(0, 50);
+      for (const dir of dirsToScan) {
+        const fullDir = path.join(projectsDir, dir);
+        try {
+          if (fs.statSync(fullDir).isDirectory()) {
+            const candidateFile = path.join(fullDir, `${sessionId}.jsonl`);
+            if (fs.existsSync(candidateFile)) {
+              return candidateFile;
+            }
+          }
+        } catch (e) {
+          // Skip inaccessible directories
         }
       }
+    } catch (err) {
+      // Ignore scan errors
     }
+    return null;
   }
 
-  let fileCheckCount = 0;
   const pollInterval = setInterval(() => {
     if (!isRunning || isShuttingDown) {
       clearInterval(pollInterval);
@@ -939,15 +995,46 @@ function startSessionFileWatcher() {
     }
 
     try {
-      if (!fs.existsSync(sessionFile)) {
-        // Log occasionally that file doesn't exist yet
-        if (fileCheckCount++ % 20 === 0) {
-          logStatus(`Session file not found yet: ${sessionFile}`);
+      // If file not found yet, try to discover it
+      if (!fileFound) {
+        if (!fs.existsSync(sessionFile)) {
+          // Try scanning for it every 5 seconds
+          fileCheckCount++;
+          if (fileCheckCount % 10 === 0) {
+            const discovered = scanForSessionFile();
+            if (discovered) {
+              sessionFile = discovered;
+              fileFound = true;
+              lastFileSize = 0;  // Reset to read from beginning
+              log(`📁 Found session file: ${sessionFile}`, colors.dim);
+            } else {
+              // Only log "not found" every 30 seconds to reduce spam
+              const now = Date.now();
+              if (now - lastNotFoundLog > 30000) {
+                logStatus(`Waiting for session file... (${Math.floor(fileCheckCount / 2)}s)`);
+                lastNotFoundLog = now;
+              }
+            }
+          }
+          return;
         }
+        fileFound = true;
+        lastFileSize = 0;  // Reset to read from beginning
+        log(`📁 Session file ready: ${sessionFile}`, colors.dim);
+      }
+
+      if (!fs.existsSync(sessionFile)) {
         return;
       }
 
       const stats = fs.statSync(sessionFile);
+
+      // Handle file being recreated (size shrunk)
+      if (stats.size < lastFileSize) {
+        logStatus(`Session file was recreated, re-reading from start`);
+        lastFileSize = 0;
+      }
+
       if (stats.size > lastFileSize) {
         logStatus(`Session file changed: ${lastFileSize} -> ${stats.size} bytes`);
         const fd = fs.openSync(sessionFile, 'r');
@@ -1277,6 +1364,12 @@ function startClaude() {
     logStatus(`Starting new Claude session: ${sessionId.slice(0, 8)}...`);
   }
 
+  // Add --dangerously-skip-permissions if requested
+  if (skipPermissions) {
+    claudeArgs.push('--dangerously-skip-permissions');
+    log('⚠️  Running in skip-permissions mode (no prompts)', colors.yellow);
+  }
+
   // Choose PTY wrapper based on platform/flag
   // - Windows: always use node-pty (Python PTY doesn't work)
   // - Unix: use Python by default, node-pty with --node-pty flag
@@ -1443,11 +1536,6 @@ function setupTerminalInput() {
   }
   process.stdin.resume();
   process.stdin.on('data', (data) => {
-    // Debug: log what bytes the keyboard sends (only when not in command mode)
-    if (data.length <= 4 && !inCommandMode) {
-      logStatus(`Keyboard input: ${data.length} bytes, hex: ${data.toString('hex')}`);
-    }
-
     const str = data.toString();
 
     // Check for command mode
@@ -1476,17 +1564,36 @@ function setupTerminalInput() {
         }
       }
 
-      // Ctrl+C or Escape in command mode - cancel command
-      if ((code === 0x03 || code === 0x1b) && inCommandMode) {
-        // Clear the echoed text
-        for (let i = 0; i < commandBuffer.length; i++) {
-          process.stdout.write('\b \b');
+      // Ctrl+C - always forward to Claude (cancel any prompt)
+      if (code === 0x03) {
+        if (inCommandMode) {
+          // Clear the echoed command text
+          for (let i = 0; i < commandBuffer.length; i++) {
+            process.stdout.write('\b \b');
+          }
+          commandBuffer = '';
+          inCommandMode = false;
+        }
+        // Always forward Ctrl+C to Claude
+        if (claudeProcess && isRunning && claudeProcess.stdin && claudeProcess.stdin.writable) {
+          claudeProcess.stdin.write('\x03');
         }
-        commandBuffer = '';
-        inCommandMode = false;
-        if (code === 0x03) {
-          // Forward Ctrl+C to Claude if not in command mode
-          // (but we just exited, so do nothing)
+        continue;
+      }
+
+      // Escape - exit command mode and forward to Claude
+      if (code === 0x1b) {
+        if (inCommandMode) {
+          // Clear the echoed command text
+          for (let i = 0; i < commandBuffer.length; i++) {
+            process.stdout.write('\b \b');
+          }
+          commandBuffer = '';
+          inCommandMode = false;
+        }
+        // Always forward Escape to Claude (for canceling prompts)
+        if (claudeProcess && isRunning && claudeProcess.stdin && claudeProcess.stdin.writable) {
+          claudeProcess.stdin.write('\x1b');
         }
         continue;
       }
@@ -1515,6 +1622,17 @@ function setupTerminalInput() {
 
       // In command mode - buffer the character
       if (inCommandMode) {
+        // Check for '//' escape - send literal '/' to Claude
+        if (char === '/' && commandBuffer === '/') {
+          // User typed '//' - exit command mode and send '/' to Claude
+          process.stdout.write('\b \b');  // Erase the first '/'
+          inCommandMode = false;
+          commandBuffer = '';
+          if (claudeProcess && isRunning && claudeProcess.stdin && claudeProcess.stdin.writable) {
+            claudeProcess.stdin.write('/');
+          }
+          continue;
+        }
         commandBuffer += char;
         // Echo to terminal
         process.stdout.write(char);
@@ -1593,6 +1711,10 @@ function main() {
     log(`   Mode:     Local (no bridge - terminal only)`, colors.dim);
   }
 
+  if (skipPermissions) {
+    log(`   Perms:    SKIPPED (dangerously-skip-permissions)`, colors.yellow);
+  }
+
   log(`   Terminal: ${process.cwd()}`, colors.dim);
   log('══════════════════════════════════════', colors.dim);
   console.log('');