minivibe 0.2.0 → 0.2.1

package/README.md

@@ -16,21 +16,19 @@ CLI wrapper for Claude Code with mobile remote control via MiniVibe iOS app.
 ## Quick Start
 
 ```bash
-# Install globally from npm
+# Install
 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.minivibeapp.com
+# Login (one-time)
+vibe --login
 
-# Option 2: Agent mode (recommended for servers)
-vibe-agent --bridge wss://ws.minivibeapp.com &   # Start agent
-vibe --agent                              # Create sessions
+# Start coding with remote control!
+vibe
+vibe "Fix the bug in main.js"
 ```
 
+> **Note:** For local-only use without remote control, just run `claude` directly.
+
 ## Installation
 
 ### From npm (Recommended)
@@ -80,22 +78,24 @@ Get token from MiniVibe iOS app: Settings > Copy Token for CLI.
 
 ## Usage Modes
 
-### Direct Bridge Mode
+### Direct Mode (Default)
 
-Connect directly to the bridge server:
+Just run `vibe` after logging in:
 
 ```bash
-vibe --bridge wss://ws.minivibeapp.com
-vibe --bridge wss://ws.minivibeapp.com "Fix the bug in main.js"
+vibe                      # Start session
+vibe "Fix the bug"        # With initial prompt
+vibe --e2e                # With end-to-end encryption
 ```
 
 ### Agent Mode (Recommended for Servers)
 
-Use a local agent to manage sessions:
+Use a local agent to manage multiple sessions:
 
 ```bash
 # Terminal 1: Start the agent (runs continuously)
-vibe-agent --bridge wss://ws.minivibeapp.com
+vibe-agent --login       # First time only
+vibe-agent               # Start daemon
 
 # Terminal 2+: Create sessions via agent
 vibe --agent
@@ -109,34 +109,25 @@ vibe --agent --name "Backend Work"
 - 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 |
+| `--login` | Sign in with Google |
+| `--headless` | Use device code flow for headless environments |
 | `--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 (auto-detects directory) |
 | `--attach <id>` | Attach to running session via local agent |
 | `--remote <id>` | Remote control session via bridge (no local Claude needed) |
 | `--list` | List running sessions on local agent |
-| `--login` | Sign in with Google |
-| `--headless` | Use device code flow for headless environments |
+| `--e2e` | Enable end-to-end encryption (auto key exchange with iOS) |
+| `--dangerously-skip-permissions` | Auto-approve all tool executions |
+| `--bridge <url>` | Override bridge URL (default: wss://ws.minivibeapp.com) |
 | `--token <token>` | Set Firebase auth token manually |
 | `--logout` | Remove stored auth token |
-| `--dangerously-skip-permissions` | Auto-approve all tool executions |
-| `--e2e` | Enable end-to-end encryption (auto key exchange with iOS) |
 | `--node-pty` | Use Node.js PTY wrapper (required for Windows) |
 | `--help, -h` | Show help message |
 
@@ -144,11 +135,11 @@ vibe "Explain this code"      # With prompt
 
 | Option | Description |
 |--------|-------------|
-| `--bridge <url>` | Bridge server URL (required) |
-| `--login` | Start device code login flow |
-| `--token <token>` | Use specific Firebase token |
+| `--login` | Sign in via device code flow |
 | `--name <name>` | Set host display name |
 | `--status` | Show current status and exit |
+| `--bridge <url>` | Override bridge URL (default: wss://ws.minivibeapp.com) |
+| `--token <token>` | Use specific Firebase token |
 | `--help, -h` | Show help message |
 
 ## Skip Permissions Mode
@@ -156,7 +147,7 @@ vibe "Explain this code"      # With prompt
 For automated/headless environments where you trust the execution context:
 
 ```bash
-vibe --dangerously-skip-permissions --bridge wss://ws.minivibeapp.com
+vibe --dangerously-skip-permissions
 vibe --dangerously-skip-permissions --agent
 ```
 
@@ -168,7 +159,7 @@ Enable E2E encryption to ensure the bridge server cannot read your message conte
 
 ```bash
 # Start with E2E encryption enabled
-vibe --e2e --bridge wss://ws.minivibeapp.com
+vibe --e2e
 ```
 
 Key exchange happens automatically when both CLI and iOS connect to the bridge:
@@ -207,7 +198,7 @@ Key exchange happens automatically when both CLI and iOS connect to the bridge:
 └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
 ```
 
-**Direct mode:** `vibe --bridge` connects directly to bridge server
+**Direct mode:** `vibe` connects directly to bridge server
 
 **Agent mode:** `vibe --agent` connects to local `vibe-agent`, which manages bridge connection
 
@@ -238,7 +229,6 @@ May also need Visual Studio Build Tools and Python for native compilation.
 | Path | Description |
 |------|-------------|
 | `~/.vibe/auth.json` | Stored authentication (token + refresh token) |
-| `~/.vibe/token` | Legacy token file |
 | `~/.vibe/e2e-keys.json` | E2E encryption keypair and peer info |
 | `~/.vibe-agent/port` | Agent port file for auto-discovery |
 

package/agent/agent.js

@@ -9,8 +9,8 @@
  * - Stop running sessions
  *
  * Usage:
- *   vibe-agent --bridge wss://ws.minivibeapp.com --token <firebase-token>
- *   vibe-agent --login --bridge wss://ws.minivibeapp.com
+ *   vibe-agent --login    Sign in (one-time)
+ *   vibe-agent            Start agent daemon
  */
 
 const { spawn, execSync } = require('child_process');
@@ -35,6 +35,22 @@ const HEARTBEAT_INTERVAL_MS = 30000;
 const LOCAL_SERVER_PORT = 9999;
 const PORT_FILE = path.join(os.homedir(), '.vibe-agent', 'port');
 const MAX_SESSION_HISTORY_AGE_DAYS = 30;
+const DEFAULT_BRIDGE_URL = 'wss://ws.minivibeapp.com';
+
+// Show welcome message for first-time users (no auth)
+function showWelcomeMessage() {
+  console.log(`
+Welcome to vibe-agent!
+
+vibe-agent lets you manage Claude Code sessions from your iPhone.
+
+To get started:
+  1. Download MiniVibe from the App Store
+  2. Run: vibe-agent --login
+
+For help: vibe-agent --help
+`);
+}
 
 // Colors for terminal output
 const colors = {
@@ -225,9 +241,10 @@ const localClients = new Map();
 // ====================
 
 function connect() {
+  // Bridge URL should always be set (defaults to DEFAULT_BRIDGE_URL)
   if (!bridgeUrl) {
-    log('No bridge URL configured', colors.red);
-    return;
+    log('No bridge URL configured (this should not happen)', colors.red);
+    process.exit(1);
   }
 
   log(`Connecting to ${bridgeUrl}...`, colors.cyan);
@@ -244,11 +261,13 @@ function connect() {
     log('Connected to bridge', colors.green);
     clearTimeout(reconnectTimer);
 
-    // Authenticate
+    // Authenticate (auth is required, so this should always be true)
     if (authToken) {
       send({ type: 'authenticate', token: authToken });
     } else {
-      log('No auth token - run: vibe-agent --login', colors.yellow);
+      // Failsafe - should not reach here due to startup check
+      showWelcomeMessage();
+      process.exit(1);
     }
   });
 
@@ -1319,27 +1338,24 @@ function printHelp() {
 ${colors.cyan}${colors.bold}vibe-agent${colors.reset} - Persistent daemon for remote Claude Code sessions
 
 ${colors.bold}Usage:${colors.reset}
-  vibe-agent --bridge <url>              Start agent connected to bridge
-  vibe-agent --login --bridge <url>      Login via device code flow
-  vibe-agent --status                    Show agent status
+  vibe-agent                Start agent daemon
+  vibe-agent --login        Sign in with Google (one-time)
+  vibe-agent --status       Show agent status
 
 ${colors.bold}Options:${colors.reset}
-  --bridge <url>    Bridge server URL (wss://ws.minivibeapp.com)
-  --login           Start device code login flow
-  --token <token>   Use specific Firebase token
+  --login           Sign in via device code flow
   --name <name>     Set host display name
   --status          Show current status and exit
   --help, -h        Show this help
 
-${colors.bold}Examples:${colors.reset}
-  # Login (first time)
-  vibe-agent --login --bridge wss://ws.minivibeapp.com
-
-  # Start agent daemon
-  vibe-agent --bridge wss://ws.minivibeapp.com
+${colors.bold}Advanced:${colors.reset}
+  --bridge <url>    Override bridge URL (default: wss://ws.minivibeapp.com)
+  --token <token>   Use specific Firebase token
 
-  # Start with custom host name
-  vibe-agent --bridge wss://ws.minivibeapp.com --name "AWS Dev Server"
+${colors.bold}Examples:${colors.reset}
+  vibe-agent --login        Sign in (one-time setup)
+  vibe-agent                Start agent
+  vibe-agent --name "EC2"   Start with custom name
 `);
 }
 
@@ -1397,7 +1413,7 @@ async function main() {
   // Load saved config
   const config = loadConfig();
 
-  bridgeUrl = options.bridge || config.bridgeUrl;
+  bridgeUrl = options.bridge || config.bridgeUrl || DEFAULT_BRIDGE_URL;
   hostName = options.name || config.hostName || os.hostname();
   agentId = config.agentId || null;  // Load persisted agentId
 
@@ -1410,7 +1426,7 @@ async function main() {
   }
 
   // Save config for next time
-  if (bridgeUrl) {
+  if (options.bridge) {
     config.bridgeUrl = bridgeUrl;
   }
   if (options.name) {
@@ -1420,7 +1436,7 @@ async function main() {
 
   // Status check
   if (options.status) {
-    console.log(`Bridge URL: ${bridgeUrl || 'Not configured'}`);
+    console.log(`Bridge URL: ${bridgeUrl}`);
     console.log(`Host Name:  ${hostName}`);
     console.log(`Auth Token: ${authToken ? 'Configured' : 'Not configured'}`);
     console.log(`Agent ID:   ${agentId || 'Will be assigned on first connect'}`);
@@ -1429,23 +1445,15 @@ async function main() {
 
   // Login flow
   if (options.login) {
-    if (!bridgeUrl) {
-      log('--bridge URL required for login', colors.red);
-      process.exit(1);
-    }
     const httpUrl = bridgeUrl.replace('wss://', 'https://').replace('ws://', 'http://');
     await startHeadlessLogin(httpUrl);
     return;
   }
 
-  // Validate requirements
-  if (!bridgeUrl) {
-    log('No bridge URL. Run: vibe-agent --bridge wss://ws.minivibeapp.com', colors.red);
-    process.exit(1);
-  }
-
+  // Require auth (block instead of warn)
   if (!authToken) {
-    log('No auth token. Run: vibe-agent --login --bridge <url>', colors.yellow);
+    showWelcomeMessage();
+    process.exit(1);
   }
 
   // Banner

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minivibe",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "CLI wrapper for Claude Code with mobile remote control via MiniVibe iOS app",
   "author": "MiniVibe <hello@minivibeapp.com>",
   "homepage": "https://github.com/minivibeapp/minivibe",

package/vibe.js

@@ -19,6 +19,49 @@ const os = require('os');
 const crypto = require('crypto');
 const e2e = require('./e2e');
 
+// Check if Claude Code is installed
+function checkClaudeInstalled() {
+  try {
+    execSync('claude --version', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Show welcome message for first-time users (no auth)
+function showWelcomeMessage() {
+  console.log(`
+Welcome to MiniVibe!
+
+MiniVibe lets you control Claude Code from your iPhone.
+
+To get started:
+  1. Download MiniVibe from the App Store
+  2. Run: vibe --login
+
+For help: vibe --help
+`);
+}
+
+// Show error when Claude Code is not installed
+function showClaudeNotFoundMessage() {
+  console.log(`
+Claude Code not found
+
+MiniVibe requires Claude Code CLI to be installed.
+
+Install Claude Code:
+  https://claude.ai/download
+
+After installing, run:
+  vibe --login
+`);
+}
+
+// Default bridge URL
+const DEFAULT_BRIDGE_URL = 'wss://ws.minivibeapp.com';
+
 // Find claude executable
 function findClaudePath() {
   try {
@@ -303,54 +346,41 @@ let e2eEnabled = false;  // --e2e mode: enable end-to-end encryption
 for (let i = 0; i < args.length; i++) {
   if (args[i] === '--help' || args[i] === '-h') {
     console.log(`
-vibe-cli - Claude Code wrapper with mobile remote control
+vibe - Claude Code with mobile remote control
 
 Usage:
-  vibe "your prompt here"          Start new session with prompt
-  vibe --bridge ws://server:8080   Connect to bridge server
-  vibe --agent                     Connect via local vibe-agent (managed mode)
-  vibe --resume <id>               Resume existing session
-  vibe --attach <id>               Attach to session via local agent (full terminal)
-  vibe --remote <id> --bridge <url>   Remote control session (no local Claude needed)
-  vibe --list                      List running sessions on local agent
-  vibe --login                     Sign in via minivibeapp.com (opens browser)
-  vibe --login --headless          Sign in on headless server (no browser)
-  vibe                             Start interactive session
+  vibe                    Start session (connects to bridge)
+  vibe "prompt"           Start with initial prompt
+  vibe --login            Sign in with Google
+  vibe --agent            Connect via local vibe-agent
 
 Options:
-  --bridge <url>   Connect to bridge server (enables internet access)
-  --agent [url]    Connect via local vibe-agent (default: ws://localhost:9999)
+  --login          Sign in via minivibeapp.com (opens browser)
+  --headless       Use device code flow for servers (no browser)
+  --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 (auto-detects correct directory)
-  --attach <id>    Attach via local agent (full terminal passthrough)
-  --remote <id>    Remote control via bridge (no local Claude needed, requires --bridge)
+  --resume <id>    Resume a previous session
+  --e2e            Enable end-to-end encryption
+
+Advanced:
+  --bridge <url>   Override bridge URL (default: wss://ws.minivibeapp.com)
+  --attach <id>    Attach to session via local agent (full terminal)
+  --remote <id>    Remote control session via bridge (no local Claude needed)
   --list           List running sessions on local agent
-  --login          Sign in via minivibeapp.com (opens browser)
-  --headless       Don't open browser (for servers without display)
   --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!)
-  --e2e            Enable end-to-end encryption (auto key exchange with iOS)
+  --node-pty       Use Node.js PTY wrapper (required for Windows)
+  --dangerously-skip-permissions   Auto-approve all tool executions
   --help, -h       Show this help message
 
-Attach vs Remote:
-  --attach <id>                    LOCAL: Full terminal passthrough via local vibe-agent
-  --remote <id> --bridge <url>     REMOTE: Chat-style control via bridge server
-                                   - No local agent or Claude Code needed
-                                   - Control sessions running on any host
-
-Authentication:
-  Use --login to sign in via minivibeapp.com (opens browser automatically).
-  Use --login --headless on servers without a display (EC2, etc.)
-
 Examples:
-  vibe --login                                    Sign in (opens minivibeapp.com)
-  vibe --login --headless                         Sign in (prints code for manual entry)
-  vibe --bridge wss://ws.minivibeapp.com                  Connect to bridge
-  vibe --agent                                    Connect via local agent
-  vibe --bridge wss://ws.minivibeapp.com "Fix bug"        With initial prompt
-  vibe --remote abc123 --bridge wss://ws.minivibeapp.com  Remote control session on another host
+  vibe --login            Sign in (one-time setup)
+  vibe                    Start session
+  vibe "Fix the bug"      Start with prompt
+  vibe --e2e              Enable encryption
+  vibe --agent            Use local agent
+
+For local-only use without remote control, run 'claude' directly.
 `);
     process.exit(0);
   } else if (args[i] === '--headless') {
@@ -442,6 +472,39 @@ if (!authToken) {
   authToken = getStoredToken();
 }
 
+// ====================
+// Startup Checks
+// ====================
+
+// Skip checks if in login mode (already handled above)
+if (!loginMode) {
+  const isAgentMode = !!agentUrl || listSessions;
+
+  // 1. --remote mode doesn't need local Claude (controls remote session)
+  // 2. --list mode doesn't need local Claude (just queries agent)
+  // 3. All other modes need Claude installed
+  if (!remoteAttachMode && !listSessions && !checkClaudeInstalled()) {
+    showClaudeNotFoundMessage();
+    process.exit(1);
+  }
+
+  // 3. Check auth (unless agent mode - agent handles its own auth)
+  if (!isAgentMode && !authToken) {
+    showWelcomeMessage();
+    process.exit(1);
+  }
+
+  // 4. Default to bridge URL when authenticated (and not in agent mode)
+  if (!isAgentMode && !bridgeUrl && authToken) {
+    bridgeUrl = DEFAULT_BRIDGE_URL;
+  }
+
+  // 5. --remote without --bridge: use default bridge
+  if (remoteAttachMode && !bridgeUrl) {
+    bridgeUrl = DEFAULT_BRIDGE_URL;
+  }
+}
+
 // Initialize E2E encryption if enabled
 // Track if E2E is pending (enabled but not yet established)
 let e2ePending = false;
@@ -458,20 +521,7 @@ if (e2eEnabled) {
   }
 }
 
-// Validate remote mode requires bridge
-if (remoteAttachMode && !bridgeUrl) {
-  console.error('Error: --remote requires --bridge <url>');
-  console.error('Example: vibe --remote abc123 --bridge wss://ws.minivibeapp.com');
-  process.exit(1);
-}
-
-// Validate E2E requires bridge (for key exchange)
-if (e2ePending && !bridgeUrl && !agentUrl) {
-  console.error('Error: --e2e with no saved peer requires --bridge <url>');
-  console.error('E2E encryption needs a bridge to exchange keys with iOS app.');
-  console.error('Example: vibe --e2e --bridge wss://ws.minivibeapp.com');
-  process.exit(1);
-}
+// Note: E2E key exchange now works automatically since bridge is defaulted when authenticated
 
 // Session state
 const sessionId = resumeSessionId || uuidv4();
@@ -693,13 +743,10 @@ function connectToBridge() {
 
   const isAgentMode = !!agentUrl;
 
-  // Check for auth token when bridge is enabled (not needed for agent mode)
+  // Auth should already be checked in startup, but double-check here
   if (!isAgentMode && !authToken) {
-    log('⚠️  No authentication token found.', colors.yellow);
-    log('   Use --token <token> to set your Firebase token.', colors.dim);
-    log('   Get your token from the MiniVibe mobile app.', colors.dim);
-    log('', '');
-    log('   Continuing without authentication (bridge may reject connection)', colors.dim);
+    showWelcomeMessage();
+    process.exit(1);
   }
 
   if (isAgentMode) {
@@ -765,6 +812,17 @@ function connectToBridge() {
   });
 
   bridgeSocket.on('error', (err) => {
+    if (isAgentMode && err.code === 'ECONNREFUSED') {
+      // Agent not running - show helpful message
+      console.log(`
+Cannot connect to vibe-agent at ${targetUrl}
+
+Make sure vibe-agent is running:
+  vibe-agent --login   # First time
+  vibe-agent           # Start daemon
+`);
+      process.exit(1);
+    }
     logStatus(`Bridge connection error: ${err.message}`);
   });
 }
@@ -2122,18 +2180,16 @@ function setupShutdown() {
 // ====================
 
 function remoteAttachMain() {
-  // Validate before displaying banner
+  // Validate before displaying banner (redundant with startup checks, but good failsafe)
   if (!authToken) {
-    console.log('');
-    log('❌ Remote attach requires authentication', colors.red);
-    log('   Run: vibe --login --bridge ' + bridgeUrl, colors.dim);
+    showWelcomeMessage();
     process.exit(1);
   }
 
   if (!resumeSessionId) {
     console.log('');
     log('❌ Remote mode requires a session ID', colors.red);
-    log('   Run: vibe --remote <session-id> --bridge ' + bridgeUrl, colors.dim);
+    log('   Run: vibe --remote <session-id>', colors.dim);
     process.exit(1);
   }