claude-chrome-parallel 2.1.0 → 2.1.1

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"
 
-## Problem 2: Browser "Detached" Errors
+# Terminal 3: Monitor admin dashboard
+claude -p "Take screenshots of https://myapp.com/admin every 30 seconds"
+```
 
-When using browser automation with multiple sessions:
+### Parallel Debugging
 
-```
-Error: Detached while handling command
+Debug multiple pages or user journeys at the same time:
+
+```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,185 @@ 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)
-
-```bash
-# Start Claude Code with isolated config
-claude-chrome-parallel launch
+### Basic Usage
 
-# 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"
+Once configured, browser automation works in any Claude Code session:
 
-# 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
 
-### Recovery Commands
+# Terminal 2 (at the same time!)
+claude
+> Fill out the form on myapp.com/contact and submit
 
-```bash
-# Check config health
-claude-chrome-parallel doctor
+# Terminal 3 (also at the same time!)
+claude
+> Monitor network requests on myapp.com/api
+```
 
-# Auto-recover corrupted .claude.json
-claude-chrome-parallel recover
+All sessions work without conflicts!
 
-# List available backups
-claude-chrome-parallel recover --list-backups
+### Available Browser Tools
 
-# Restore from specific backup
-claude-chrome-parallel recover --backup ".claude.json.2024-01-15T10-30-00-000Z.bak"
+| 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 |
 
-# Force create new empty config
-claude-chrome-parallel recover --force-new
+---
 
-# 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
-```
+## How It Works
 
-### Browser Automation (MCP Server)
+### The Problem: Shared Extension State
 
-Add to `~/.claude.json`:
+The official Chrome extension maintains a single shared state:
 
-```json
-{
-  "mcpServers": {
-    "chrome-parallel": {
-      "command": "claude-chrome-parallel",
-      "args": ["serve"]
-    }
-  }
-}
+```
+Claude Code 1 ─┐
+               ├─► Chrome Extension (shared state) ─► Chrome
+Claude Code 2 ─┘
+                    ↑
+              State conflicts here!
 ```
 
-Then use in Claude Code:
+### The Solution: Independent CDP Connections
+
+Chrome's DevTools Protocol natively supports multiple simultaneous connections:
 
 ```
-You: Take a screenshot of https://github.com
+Claude Code 1 ─► Process 1 ─► CDP Connection 1 ─┐
+                                                 ├─► Chrome (port 9222)
+Claude Code 2 ─► Process 2 ─► CDP Connection 2 ─┘
 
-Claude: [Uses chrome-parallel tools automatically]
+Independent connections, no shared state!
 ```
 
-**Run multiple sessions with browser automation:**
+Each Claude Code session spawns its own MCP server process with a dedicated CDP connection.
+
+---
+
+## CLI Commands
 
 ```bash
-# Terminal 1
-claude-chrome-parallel launch
-> Take a screenshot of github.com
+# Start MCP server (used by Claude Code automatically)
+claude-chrome-parallel serve
 
-# Terminal 2 (simultaneously!)
-claude-chrome-parallel launch
-> Take a screenshot of google.com
-```
+# Check Chrome connection status
+claude-chrome-parallel check
 
-Both work without conflicts!
+# Use custom Chrome debugging port
+claude-chrome-parallel serve --port 9223
 
----
+# Check installation health
+claude-chrome-parallel doctor
+```
 
-## CLI Reference
+---
 
-| 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 |
+## Chrome Configuration
 
-### Launch Options
+By default, connects to Chrome on port 9222.
 
-| Option | Description |
-|--------|-------------|
-| `--sync-back` | Sync config changes back to original on exit |
-| `--keep-session` | Keep session directory after exit (debugging) |
+**Auto-launch**: If Chrome isn't running with debugging enabled, the package will start it automatically.
 
-### Recover Options
+**Manual start** (if needed):
 
-| Option | Description |
-|--------|-------------|
-| `--list-backups` | List available backup files |
-| `--backup <name>` | Restore from specific backup |
-| `--force-new` | Create new empty config (loses all data) |
+```bash
+# Windows
+chrome.exe --remote-debugging-port=9222
 
-### Cleanup Options
+# macOS
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
 
-| Option | Description |
-|--------|-------------|
-| `--max-age <hours>` | Max session age in hours (default: 24) |
-| `--keep-backups <n>` | Number of backups to keep (default: 10) |
+# Linux
+google-chrome --remote-debugging-port=9222
+```
 
 ---
 
-## Browser Automation Tools
+## Additional Features
 
-| 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 |
-
----
+### Session Isolation (Bonus)
 
-## How It Works
+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:
 
-### Session Isolation
+```bash
+# Run Claude Code with isolated config directory
+claude-chrome-parallel launch
 
-```
-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 │
-└─────────────────────────────────────────────┘
+# Pass any claude flags
+claude-chrome-parallel launch --dangerously-skip-permissions
+claude-chrome-parallel launch -p "Your prompt"
 ```
 
-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
+### Config Recovery
 
-### Browser Automation
+If your `.claude.json` gets corrupted:
 
-Chrome's DevTools Protocol natively supports multiple connections:
+```bash
+# Auto-recover corrupted config
+claude-chrome-parallel recover
 
-```
-Process 1 ─► CDP Connection 1 ─┐
-                               ├─► Chrome (port 9222)
-Process 2 ─► CDP Connection 2 ─┘
+# 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 | ❌ | ✅ |
 
-```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 +274,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 +297,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-chrome-parallel",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "MCP server for parallel Claude Code browser sessions - no more 'Detached' errors",
   "main": "dist/index.js",
   "bin": {