minivibe 0.1.1 → 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

@@ -1,40 +1,56 @@
-# vibe-cli
+# MiniVibe CLI
 
-CLI wrapper for Claude Code with mobile remote control via MiniVibe.
+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
 
-## Installation
+## Quick Start
 
 ```bash
-# Clone the repository
-git clone <repo-url>
-cd vibe-cli
+# Install globally from npm
+npm install -g minivibe
 
-# Install dependencies
-npm install
+# Authenticate (one-time)
+vibe --login              # Desktop (opens browser)
+vibe --login --headless   # Server/EC2 (device code)
 
-# Link globally (optional)
-npm link
+# 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
 ```
 
-### Global Installation (EC2/Servers)
+See [GETTING_STARTED.md](GETTING_STARTED.md) for detailed setup instructions.
+
+## Installation
+
+### From npm (Recommended)
 
 ```bash
-# Install to /opt for all users
-sudo git clone <repo-url> /opt/neng
-cd /opt/neng/vibe-cli
-sudo npm install
-sudo npm link
-
-# Or add to PATH
-echo 'export PATH="/opt/neng/vibe-cli:$PATH"' | sudo tee /etc/profile.d/vibe.sh
+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
@@ -61,67 +77,59 @@ Displays a device code. Visit the URL on any device to authenticate.
 vibe --token <firebase-token>
 ```
 
-Get token from MiniVibe iOS app Settings > Copy Token for CLI.
+Get token from MiniVibe iOS app: Settings > Copy Token for CLI.
 
-## Usage
+## Usage Modes
 
-### Basic Usage
+### Direct Bridge Mode
 
-```bash
-# Interactive session
-vibe
-
-# With initial prompt
-vibe "Fix the bug in main.js"
-
-# Connect to bridge server
-vibe --bridge wss://ws.neng.ai
-
-# With prompt and bridge
-vibe --bridge wss://ws.neng.ai "Deploy the application"
-```
-
-### Session Management
+Connect directly to the bridge server:
 
 ```bash
-# Name your session (visible in iOS app)
-vibe --name "Backend Refactor" --bridge wss://ws.neng.ai
-
-# Resume a previous session
-vibe --resume <session-id> --bridge wss://ws.neng.ai
+vibe --bridge wss://ws.neng.ai
+vibe --bridge wss://ws.neng.ai "Fix the bug in main.js"
 ```
 
-### Skip Permissions Mode
+### Agent Mode (Recommended for Servers)
 
-For automated/headless environments where you trust the execution context:
+Use a local agent to manage sessions:
 
 ```bash
-vibe --dangerously-skip-permissions --bridge wss://ws.neng.ai
+# 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"
 ```
 
-**Warning:** This mode auto-approves ALL tool executions (commands, file writes, etc.) without prompting. Only use in trusted/sandboxed environments.
+**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 Agent Mode
+### Local Mode (No Bridge)
 
-Connect via a local vibe-agent for managed sessions:
+Run without remote control:
 
 ```bash
-# Auto-discover agent
-vibe --agent
-
-# Specify agent URL
-vibe --agent ws://localhost:9999
+vibe                          # Interactive
+vibe "Explain this code"      # With prompt
 ```
 
 ## Options
 
+### vibe
+
 | Option | Description |
 |--------|-------------|
-| `--bridge <url>` | Connect to bridge server (e.g., `wss://ws.neng.ai`) |
-| `--agent [url]` | Connect via local vibe-agent |
+| `--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 (browser) |
+| `--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 |
@@ -129,11 +137,46 @@ vibe --agent ws://localhost:9999
 | `--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
 
@@ -159,21 +202,11 @@ May also need Visual Studio Build Tools and Python for native compilation.
 
 ## Files
 
-- `~/.vibe/auth.json` - Stored authentication (token + refresh token)
-- `~/.vibe/token` - Legacy token file (backwards compatibility)
-
-## Architecture
-
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  MiniVibe   │────▶│   Bridge    │◀────│  vibe-cli   │
-│  iOS App    │     │   Server    │     │  + Claude   │
-└─────────────┘     └─────────────┘     └─────────────┘
-```
-
-1. **vibe-cli** wraps Claude Code and connects to the bridge server
-2. **Bridge server** relays messages between mobile and CLI
-3. **MiniVibe iOS** provides remote control, permission approval, and session monitoring
+| 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minivibe",
-  "version": "0.1.1",
+  "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

@@ -413,6 +413,7 @@ Options:
 
 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.
@@ -1535,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
@@ -1568,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');
+        }
+        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;
         }
-        commandBuffer = '';
-        inCommandMode = false;
-        if (code === 0x03) {
-          // Forward Ctrl+C to Claude if not in command mode
-          // (but we just exited, so do nothing)
+        // Always forward Escape to Claude (for canceling prompts)
+        if (claudeProcess && isRunning && claudeProcess.stdin && claudeProcess.stdin.writable) {
+          claudeProcess.stdin.write('\x1b');
         }
         continue;
       }
@@ -1607,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);