claude-chrome-parallel 2.1.0 → 2.2.0

package/README.md

@@ -1,85 +1,82 @@
 # Claude Chrome Parallel
 
-> **Run multiple Claude Code sessions safely - no more "Detached" errors or config corruption.**
+> **Run multiple Claude Code browser sessions in parallel - no more "Detached" errors.**
 
 [![npm version](https://badge.fury.io/js/claude-chrome-parallel.svg)](https://www.npmjs.com/package/claude-chrome-parallel)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Features
+## Why This Exists
 
-- **Session Isolation**: Prevents `.claude.json` corruption when running multiple Claude instances
-- **Browser Automation**: Independent CDP connections for parallel browser control
-- **Auto Recovery**: Detects and recovers corrupted config files
+[Claude Chrome](https://claude.ai/chrome) is a powerful tool that lets you debug **production environments while logged in** - no need to replicate auth states or mock sessions. But when you try to run multiple Claude Code sessions with browser automation simultaneously, you get:
 
----
+```
+Error: Detached while handling command
+```
 
-## Problem 1: Config File Corruption
+This happens because the Chrome extension uses **shared internal state**. When Session A takes a screenshot, Session B's connection gets "detached."
 
-When running **multiple Claude Code instances** simultaneously, they compete to write to `~/.claude.json`, causing corruption:
+**Claude Chrome Parallel** solves this by creating **independent CDP connections** for each session:
 
 ```
-Terminal 1: claude  ──┐
-                      ├──► ~/.claude.json ← Race condition!
-Terminal 2: claude  ──┘
-
-Result: {"key":"value"}{"key":"value"}  ← Two JSON objects concatenated = CORRUPT
+Claude Code 1 ──► Process 1 ──► CDP Connection 1 ──┐
+                                                    ├──► Chrome (port 9222)
+Claude Code 2 ──► Process 2 ──► CDP Connection 2 ──┘
 ```
 
-**Symptoms:**
-- Claude Code crashes on startup
-- "Unexpected token" JSON parse errors
-- Lost settings and preferences
+Each session gets isolated browser control. No shared state = No conflicts.
 
-## Solution: Session Isolation
+---
 
-```bash
-# Instead of running claude directly...
-claude-chrome-parallel launch
+## Use Cases
 
-# Each session gets isolated config
-Terminal 1: claude-chrome-parallel launch  ──► ~/.claude-chrome-parallel/sessions/abc123/.claude.json
-Terminal 2: claude-chrome-parallel launch  ──► ~/.claude-chrome-parallel/sessions/def456/.claude.json
-```
+### Multi-Session QA Testing
 
-**All your existing flags work:**
+Run parallel test scenarios against your production or staging environment:
 
 ```bash
-claude-chrome-parallel launch --dangerously-skip-permissions
-claude-chrome-parallel launch --resume abc123
-claude-chrome-parallel launch -p "Fix the bug"
-claude-chrome-parallel launch --model opus --resume
-```
+# Terminal 1: Test user login flow
+claude -p "Test the login flow on https://myapp.com/login"
 
----
+# Terminal 2: Test checkout process (simultaneously!)
+claude -p "Test the checkout flow on https://myapp.com/cart"
+
+# Terminal 3: Monitor admin dashboard
+claude -p "Take screenshots of https://myapp.com/admin every 30 seconds"
+```
 
-## Problem 2: Browser "Detached" Errors
+### Parallel Debugging
 
-When using browser automation with multiple sessions:
+Debug multiple pages or user journeys at the same time:
 
-```
-Error: Detached while handling command
+```bash
+# Debug as different users
+Terminal 1: "Log in as admin and check permissions on /settings"
+Terminal 2: "Log in as regular user and verify they can't access /settings"
 ```
 
-The Chrome extension uses **shared internal state** - when Session A takes a screenshot, Session B's connection breaks.
+### Automated Regression Testing
 
-## Solution: Independent CDP Connections
+Run comprehensive browser tests across multiple sessions:
 
+```bash
+# Run 5 parallel test sessions
+for i in {1..5}; do
+  claude -p "Run test suite $i on https://staging.myapp.com" &
+done
 ```
-Claude Code 1 ──► puppeteer process 1 ──► CDP connection 1 ──┐
-                                                              ├──► Chrome
-Claude Code 2 ──► puppeteer process 2 ──► CDP connection 2 ──┘
-```
-
----
 
-## Installation
+### Tested Concurrency
 
-### Prerequisites
+| Sessions | Success Rate |
+|----------|-------------|
+| 5 | 100% |
+| 10 | 100% |
+| 15 | 100% |
+| 20 | 100% |
 
-- Node.js 18+
-- Google Chrome (for browser automation)
+---
 
-### Install
+## Installation
 
 ```bash
 # From npm
@@ -89,207 +86,210 @@ npm install -g claude-chrome-parallel
 npm install -g github:shaun0927/claude-chrome-parallel
 ```
 
+### Configure Claude Code
+
+Add to your Claude Code MCP settings (`~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "chrome-parallel": {
+      "command": "claude-chrome-parallel",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+Restart Claude Code for changes to take effect.
+
 ---
 
 ## Usage
 
-### Session Isolation (Recommended for Multiple Instances)
+### Basic Usage
 
-```bash
-# Start Claude Code with isolated config
-claude-chrome-parallel launch
+Once configured, browser automation works in any Claude Code session:
 
-# Pass any claude flags
-claude-chrome-parallel launch --dangerously-skip-permissions
-claude-chrome-parallel launch --resume <session-id>
-claude-chrome-parallel launch -p "Your prompt here"
-
-# Sync changes back to original config on exit
-claude-chrome-parallel launch --sync-back
+```
+You: Take a screenshot of https://github.com
 
-# Keep session directory for debugging
-claude-chrome-parallel launch --keep-session
+Claude: [Uses chrome-parallel tools automatically]
 ```
 
-### Standalone Wrapper (Alternative)
+### Multiple Parallel Sessions
+
+Run multiple Claude Code terminals simultaneously:
 
 ```bash
-# Simpler command
-claude-session
-
-# With arguments
-claude-session "Fix the authentication bug"
-claude-session --list      # List active sessions
-claude-session --cleanup   # Clean up stale sessions
-claude-session --recover   # Recover corrupted config
+# Terminal 1
+claude
+> Navigate to myapp.com/dashboard and take a screenshot
+
+# Terminal 2 (at the same time!)
+claude
+> Fill out the form on myapp.com/contact and submit
+
+# Terminal 3 (also at the same time!)
+claude
+> Monitor network requests on myapp.com/api
 ```
 
-### Recovery Commands
+All sessions work without conflicts!
 
-```bash
-# Check config health
-claude-chrome-parallel doctor
+### Available Browser Tools
 
-# Auto-recover corrupted .claude.json
-claude-chrome-parallel recover
+| Tool | Description |
+|------|-------------|
+| `navigate` | Navigate to URL or use history |
+| `computer` | Screenshots, mouse clicks, keyboard input, scrolling |
+| `read_page` | Read page content via accessibility tree |
+| `find` | Find elements by description |
+| `form_input` | Fill form fields |
+| `javascript_tool` | Execute JavaScript |
+| `tabs_context_mcp` | Get available tabs |
+| `tabs_create_mcp` | Create new tab |
+| `network` | Simulate network conditions (3G, 4G, offline, custom) |
 
-# List available backups
-claude-chrome-parallel recover --list-backups
+### Network Simulation
 
-# Restore from specific backup
-claude-chrome-parallel recover --backup ".claude.json.2024-01-15T10-30-00-000Z.bak"
+Test how your app behaves under different network conditions:
 
-# Force create new empty config
-claude-chrome-parallel recover --force-new
+```
+You: Simulate 3G network and navigate to myapp.com
 
-# Clean up old sessions and backups
-claude-chrome-parallel cleanup
-claude-chrome-parallel cleanup --max-age 12      # Sessions older than 12 hours
-claude-chrome-parallel cleanup --keep-backups 5  # Keep only 5 most recent backups
+Claude: [Applies 3G throttling: 1.5Mbps down, 750Kbps up, 100ms latency]
 ```
 
-### Browser Automation (MCP Server)
+Available presets: `offline`, `slow-2g`, `2g`, `3g`, `4g`, `fast-wifi`, `custom`, `clear`
 
-Add to `~/.claude.json`:
+---
 
-```json
-{
-  "mcpServers": {
-    "chrome-parallel": {
-      "command": "claude-chrome-parallel",
-      "args": ["serve"]
-    }
-  }
-}
-```
+## How It Works
 
-Then use in Claude Code:
+### The Problem: Shared Extension State
 
-```
-You: Take a screenshot of https://github.com
+The official Chrome extension maintains a single shared state:
 
-Claude: [Uses chrome-parallel tools automatically]
+```
+Claude Code 1 ─┐
+               ├─► Chrome Extension (shared state) ─► Chrome
+Claude Code 2 ─┘
+                    ↑
+              State conflicts here!
 ```
 
-**Run multiple sessions with browser automation:**
+### The Solution: Independent CDP Connections
 
-```bash
-# Terminal 1
-claude-chrome-parallel launch
-> Take a screenshot of github.com
+Chrome's DevTools Protocol natively supports multiple simultaneous connections:
 
-# Terminal 2 (simultaneously!)
-claude-chrome-parallel launch
-> Take a screenshot of google.com
+```
+Claude Code 1 ─► Process 1 ─► CDP Connection 1 ─┐
+                                                 ├─► Chrome (port 9222)
+Claude Code 2 ─► Process 2 ─► CDP Connection 2 ─┘
+
+Independent connections, no shared state!
 ```
 
-Both work without conflicts!
+Each Claude Code session spawns its own MCP server process with a dedicated CDP connection.
 
 ---
 
-## CLI Reference
+## CLI Commands
 
-| Command | Description |
-|---------|-------------|
-| `launch [args...]` | Start Claude with isolated config |
-| `recover` | Recover corrupted .claude.json |
-| `cleanup` | Clean up stale sessions and backups |
-| `doctor` | Check installation and config health |
-| `serve` | Start MCP server for browser automation |
-| `install` | Install browser extension and native host |
-| `uninstall` | Remove extension and native host |
+```bash
+# Start MCP server (used by Claude Code automatically)
+claude-chrome-parallel serve
 
-### Launch Options
+# Check Chrome connection status
+claude-chrome-parallel check
 
-| Option | Description |
-|--------|-------------|
-| `--sync-back` | Sync config changes back to original on exit |
-| `--keep-session` | Keep session directory after exit (debugging) |
+# Use custom Chrome debugging port
+claude-chrome-parallel serve --port 9223
 
-### Recover Options
+# Check installation health
+claude-chrome-parallel doctor
 
-| Option | Description |
-|--------|-------------|
-| `--list-backups` | List available backup files |
-| `--backup <name>` | Restore from specific backup |
-| `--force-new` | Create new empty config (loses all data) |
+# View session status and statistics
+claude-chrome-parallel status
 
-### Cleanup Options
+# View status as JSON (for automation)
+claude-chrome-parallel status --json
 
-| Option | Description |
-|--------|-------------|
-| `--max-age <hours>` | Max session age in hours (default: 24) |
-| `--keep-backups <n>` | Number of backups to keep (default: 10) |
+# Clean up stale sessions and old backups
+claude-chrome-parallel cleanup --max-age 24 --keep-backups 10
+```
 
 ---
 
-## Browser Automation Tools
+## Chrome Configuration
 
-| Tool | Description |
-|------|-------------|
-| `navigate` | Navigate to URL or use history |
-| `tabs_context_mcp` | Get available tabs |
-| `tabs_create_mcp` | Create new tab |
-| `computer` | Screenshots, mouse/keyboard, scrolling |
-| `read_page` | Read accessibility tree |
-| `find` | Find elements by description |
-| `form_input` | Fill form fields |
-| `javascript_tool` | Execute JavaScript |
+By default, connects to Chrome on port 9222.
 
----
+**Auto-launch**: If Chrome isn't running with debugging enabled, the package will start it automatically.
 
-## How It Works
+**Manual start** (if needed):
+
+```bash
+# Windows
+chrome.exe --remote-debugging-port=9222
 
-### Session Isolation
+# macOS
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
 
-```
-Before (Dangerous):
-┌─────────────────────────────────────────────┐
-│ Terminal 1: claude ──┐                      │
-│                      ├─► ~/.claude.json     │ ← Race condition!
-│ Terminal 2: claude ──┘                      │
-└─────────────────────────────────────────────┘
-
-After (Safe):
-┌─────────────────────────────────────────────┐
-│ Terminal 1: launch ─► sessions/abc/.claude.json │
-│                                                 │ ← No conflict!
-│ Terminal 2: launch ─► sessions/def/.claude.json │
-└─────────────────────────────────────────────┘
+# Linux
+google-chrome --remote-debugging-port=9222
 ```
 
-The `launch` command:
-1. Creates a unique session directory
-2. Copies existing `.claude.json` (if valid)
-3. Sets `HOME` environment variable to session directory
-4. Runs `claude` with all your arguments
-5. Cleans up session on exit
+---
+
+## Additional Features
 
-### Browser Automation
+### Session Isolation (Bonus)
 
-Chrome's DevTools Protocol natively supports multiple connections:
+When running multiple Claude Code instances, they can corrupt `~/.claude.json` due to race conditions. Use the `launch` command to run Claude with isolated config:
+
+```bash
+# Run Claude Code with isolated config directory
+claude-chrome-parallel launch
 
+# Pass any claude flags
+claude-chrome-parallel launch --dangerously-skip-permissions
+claude-chrome-parallel launch -p "Your prompt"
 ```
-Process 1 ─► CDP Connection 1 ─┐
-                               ├─► Chrome (port 9222)
-Process 2 ─► CDP Connection 2 ─┘
+
+### Config Recovery
+
+If your `.claude.json` gets corrupted:
+
+```bash
+# Auto-recover corrupted config
+claude-chrome-parallel recover
+
+# List available backups
+claude-chrome-parallel recover --list-backups
 ```
 
 ---
 
-## Troubleshooting
+## Comparison
 
-### Config Corruption
+| Feature | Claude in Chrome (Extension) | Claude Chrome Parallel |
+|---------|------------------------------|----------------------|
+| Multiple sessions | ❌ Detached errors | ✅ Works perfectly |
+| Parallel QA testing | ❌ | ✅ |
+| Connection type | Shared extension state | Independent CDP |
+| Max concurrent sessions | 1 | 20+ tested |
+| Auto Chrome launch | ❌ | ✅ |
+| Network simulation | ❌ | ✅ 3G/4G/offline presets |
+| Session auto-cleanup | ❌ | ✅ TTL-based |
+| Connection pooling | ❌ | ✅ Pre-warmed pages |
 
-```bash
-# Check health
-claude-chrome-parallel doctor
+---
 
-# If corrupted, recover
-claude-chrome-parallel recover
-```
+## Troubleshooting
 
-### Chrome Not Connecting
+### Chrome not connecting
 
 ```bash
 # Check status
@@ -299,7 +299,7 @@ claude-chrome-parallel check
 chrome --remote-debugging-port=9222
 ```
 
-### Tools Not Appearing
+### Tools not appearing in Claude Code
 
 1. Check MCP config in `~/.claude.json`
 2. Restart Claude Code
@@ -322,17 +322,6 @@ npm install -g .
 
 ---
 
-## Comparison
-
-| Feature | Plain `claude` | `claude-chrome-parallel launch` |
-|---------|----------------|--------------------------------|
-| Multiple instances | Config corruption risk | Safe (isolated) |
-| Browser automation | Detached errors | Works perfectly |
-| Auto backup | | Config backed up |
-| Recovery tools | | Built-in |
-
----
-
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.

package/dist/cdp/connection-pool.d.ts

@@ -0,0 +1,88 @@
+/**
+ * CDP Connection Pool - Pre-allocate and manage page instances for faster session creation
+ */
+import { Page } from 'puppeteer-core';
+import { CDPClient } from './client';
+export interface PoolConfig {
+    /** Minimum number of pre-allocated pages to keep ready (default: 2) */
+    minPoolSize?: number;
+    /** Maximum number of pre-allocated pages (default: 10) */
+    maxPoolSize?: number;
+    /** Page idle timeout in ms before returning to pool (default: 5 minutes) */
+    pageIdleTimeout?: number;
+    /** Whether to pre-warm pages on startup (default: true) */
+    preWarm?: boolean;
+}
+export interface PoolStats {
+    /** Number of pages currently in the pool (ready to use) */
+    availablePages: number;
+    /** Number of pages currently in use */
+    inUsePages: number;
+    /** Total pages created since pool initialization */
+    totalPagesCreated: number;
+    /** Number of pages reused from pool */
+    pagesReused: number;
+    /** Number of pages created on-demand (pool was empty) */
+    pagesCreatedOnDemand: number;
+    /** Average time to acquire a page (ms) */
+    avgAcquireTimeMs: number;
+}
+export declare class CDPConnectionPool {
+    private cdpClient;
+    private config;
+    private availablePages;
+    private inUsePages;
+    private maintenanceTimer;
+    private isInitialized;
+    private totalPagesCreated;
+    private pagesReused;
+    private pagesCreatedOnDemand;
+    private acquireTimes;
+    constructor(cdpClient?: CDPClient, config?: PoolConfig);
+    /**
+     * Initialize the pool with pre-warmed pages
+     */
+    initialize(): Promise<void>;
+    /**
+     * Acquire a page from the pool
+     */
+    acquirePage(): Promise<Page>;
+    /**
+     * Release a page back to the pool
+     */
+    releasePage(page: Page): Promise<void>;
+    /**
+     * Create a new page
+     */
+    private createNewPage;
+    /**
+     * Ensure minimum number of pages in pool
+     */
+    private ensureMinimumPages;
+    /**
+     * Replenish pool asynchronously
+     */
+    private replenishPoolAsync;
+    /**
+     * Perform maintenance on the pool
+     */
+    private performMaintenance;
+    /**
+     * Get pool statistics
+     */
+    getStats(): PoolStats;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Required<PoolConfig>;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<PoolConfig>): void;
+    /**
+     * Shutdown the pool
+     */
+    shutdown(): Promise<void>;
+}
+export declare function getCDPConnectionPool(config?: PoolConfig): CDPConnectionPool;
+//# sourceMappingURL=connection-pool.d.ts.map

package/dist/cdp/connection-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-pool.d.ts","sourceRoot":"","sources":["../../src/cdp/connection-pool.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,SAAS,EAAgB,MAAM,UAAU,CAAC;AAEnD,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,0CAA0C;IAC1C,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAeD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,cAAc,CAAoB;IAC1C,OAAO,CAAC,UAAU,CAAoC;IACtD,OAAO,CAAC,gBAAgB,CAA+B;IACvD,OAAO,CAAC,aAAa,CAAS;IAG9B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,oBAAoB,CAAK;IACjC,OAAO,CAAC,YAAY,CAAgB;gBAExB,SAAS,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,UAAU;IAKtD;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBjC;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IA2ClC;;OAEG;IACG,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAmD5C;;OAEG;YACW,aAAa;IAM3B;;OAEG;YACW,kBAAkB;IAsBhC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;OAEG;YACW,kBAAkB;IAiChC;;OAEG;IACH,QAAQ,IAAI,SAAS;IAgBrB;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,UAAU,CAAC;IAIjC;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;IAI/C;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CA6BhC;AAKD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,iBAAiB,CAK3E"}