claude-chrome-parallel 2.3.0 → 3.0.1

package/README.md

@@ -1,289 +1,400 @@
 # Claude Chrome Parallel
 
-> **Run multiple Claude Code browser sessions in parallel - no more "Detached" errors.**
+> **Run 20+ Claude Code browser sessions simultaneously, without conflicts.**
 
 [![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)
 
-## Why This Exists
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                                                                             │
+│   Claude Code 1 ─► Worker A ─► [Tab1] [Tab2] ─┐                            │
+│                    (Google account)            │                            │
+│                                                │                            │
+│   Claude Code 2 ─► Worker B ─► [Tab3] [Tab4] ─┼─► Chrome (single instance) │
+│                    (Naver account)             │     Port 9222              │
+│                                                │                            │
+│   Claude Code 3 ─► Worker C ─► [Tab5] [Tab6] ─┘                            │
+│                    (Amazon account)                                         │
+│                                                                             │
+│   ✓ Each Worker has isolated cookies/session/storage                       │
+│   ✓ No more "Detached" errors with concurrent sessions                     │
+│   ✓ Multiple account logins on same site simultaneously                    │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Core Features
+
+<table>
+<tr>
+<td width="33%" valign="top">
+
+### 🔀 Worker Isolation
 
-[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:
+Each Worker has a **completely isolated browser context**.
+
+- Separate cookies/sessions
+- Separate localStorage
+- Separate login states
+
+**Log into multiple accounts on the same site simultaneously!**
+
+</td>
+<td width="33%" valign="top">
+
+### ⚡ Parallel Execution
+
+Run tasks across multiple tabs/Workers **at the same time**.
 
 ```
-Error: Detached while handling command
+Sequential: 1500ms
+  Tab1 ████░░░░ 500ms
+  Tab2     ████░░░░ 500ms
+  Tab3         ████░░░░ 500ms
+
+Parallel: 500ms
+  Tab1 ████░░░░
+  Tab2 ████░░░░
+  Tab3 ████░░░░
 ```
 
-This happens because the Chrome extension uses **shared internal state**. When Session A takes a screenshot, Session B's connection gets "detached."
+</td>
+<td width="33%" valign="top">
+
+### 🔄 Workflow Orchestration
 
-**Claude Chrome Parallel** solves this by creating **independent CDP connections** for each session:
+**Automatically distribute** complex multi-site tasks.
 
 ```
-Claude Code 1 ──► Process 1 ──► CDP Connection 1 ──┐
-                                                    ├──► Chrome (port 9222)
-Claude Code 2 ──► Process 2 ──► CDP Connection 2 ──┘
+workflow_init({
+  workers: [
+    {name: "amazon", ...},
+    {name: "ebay", ...},
+    {name: "walmart", ...}
+  ]
+})
+→ 3 sites run in parallel
+→ Results auto-collected
 ```
 
-Each session gets isolated browser control. No shared state = No conflicts.
+</td>
+</tr>
+</table>
 
 ---
 
-## Use Cases
+## Comparison
+
+| | Chrome Extension | Claude Chrome Parallel |
+|---|:---:|:---:|
+| **Concurrent Sessions** | ❌ 1 (Detached error) | ✅ **20+** |
+| **Worker Isolation** | ❌ | ✅ Isolated cookies/sessions |
+| **Multi-account Login** | ❌ | ✅ |
+| **Parallel Execution** | ❌ | ✅ |
+| **Network Simulation** | ❌ | ✅ 3G/4G/offline |
+| **Workflow Orchestration** | ❌ | ✅ |
+| **Auto Chrome Launch** | ❌ | ✅ |
 
-### Multi-Session QA Testing
+---
 
-Run parallel test scenarios against your production or staging environment:
+## Why It Matters
 
-```bash
-# Terminal 1: Test user login flow
-claude -p "Test the login flow on https://myapp.com/login"
+### The Problem
 
-# Terminal 2: Test checkout process (simultaneously!)
-claude -p "Test the checkout flow on https://myapp.com/cart"
+The official Chrome extension has a fatal flaw: **shared internal state**.
 
-# Terminal 3: Monitor admin dashboard
-claude -p "Take screenshots of https://myapp.com/admin every 30 seconds"
+```
+Claude Code 1 ─┐
+               ├─► Chrome Extension (shared state) ─► "Detached" error!
+Claude Code 2 ─┘
 ```
 
-### Parallel Debugging
+When Session A takes a screenshot, Session B's connection breaks. You can only run **one session at a time**.
 
-Debug multiple pages or user journeys at the same time:
+### The Solution
+
+Claude Chrome Parallel creates **independent CDP connections** per session:
 
-```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"
 ```
+Claude Code 1 ─► CDP Connection 1 ─┐
+                                    ├─► Chrome (port 9222)
+Claude Code 2 ─► CDP Connection 2 ─┘
 
-### Automated Regression Testing
+No shared state = No conflicts = 20+ concurrent sessions
+```
 
-Run comprehensive browser tests across multiple sessions:
+### The Real Power: Authenticated 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
-```
+Unlike headless automation, this runs in **your actual browser** with all your logins active:
 
-### Tested Concurrency
+- ✅ Access Gmail, Salesforce, LinkedIn while logged in
+- ✅ No credential management or auth flows needed
+- ✅ Bypass bot detection (real browser profile)
+- ✅ Multiple accounts simultaneously (Worker isolation)
 
-| Sessions | Success Rate |
-|----------|-------------|
-| 5 | 100% |
-| 10 | 100% |
-| 15 | 100% |
-| 20 | 100% |
+**This isn't just for developers.** Any web task requiring authentication—previously impossible to automate—is now possible with natural language.
 
 ---
 
-## Installation
+## Quick Start (2 minutes)
+
+### 1. Install
 
 ```bash
-# From npm
 npm install -g claude-chrome-parallel
-
-# Or from GitHub
-npm install -g github:shaun0927/claude-chrome-parallel
 ```
 
-### Configure Claude Code
+### 2. Configure Claude Code
 
-Add to your Claude Code MCP settings (`~/.claude.json`):
+Add to `~/.claude.json`:
 
 ```json
 {
   "mcpServers": {
     "chrome-parallel": {
-      "command": "claude-chrome-parallel",
+      "command": "ccp",
       "args": ["serve"]
     }
   }
 }
 ```
 
-Restart Claude Code for changes to take effect.
+### 3. Restart Claude Code and use
+
+```
+You: Take a screenshot of https://github.com
+
+Claude: [Auto-launches browser, captures screenshot]
+```
+
+> **Tip:** `ccp` is a shorthand for `claude-chrome-parallel`.
 
 ---
 
-## Usage
+## Usage Examples
 
-### Basic Usage
+### Multiple Accounts Simultaneously
 
-Once configured, browser automation works in any Claude Code session:
+```
+You: Create "google-personal" and "google-work" Workers,
+     then check the inbox of each Gmail account
 
+Claude: [Creates 2 Workers → Each accesses Gmail with isolated sessions]
+        google-personal: Personal account - 3 new emails
+        google-work: Work account - 7 new emails
 ```
-You: Take a screenshot of https://github.com
 
-Claude: [Uses chrome-parallel tools automatically]
+### Price Comparison (Parallel)
+
 ```
+You: Search for "iPhone 15" lowest price on Amazon, eBay, and Walmart simultaneously
 
-### Multiple Parallel Sessions
+Claude: [3 sites run in parallel]
+        Amazon: $999 (1.2s)
+        eBay: $945 (1.1s)
+        Walmart: $979 (1.3s)
+        Total time: 1.3s (vs 3.6s sequential)
+```
 
-Run multiple Claude Code terminals simultaneously:
+### Parallel QA Testing
 
 ```bash
 # Terminal 1
-claude
-> Navigate to myapp.com/dashboard and take a screenshot
+claude -p "Test myapp.com/login"
 
 # Terminal 2 (at the same time!)
-claude
-> Fill out the form on myapp.com/contact and submit
+claude -p "Test myapp.com/checkout"
 
-# Terminal 3 (also at the same time!)
-claude
-> Monitor network requests on myapp.com/api
+# Terminal 3 (at the same time!)
+claude -p "Monitor myapp.com/admin"
 ```
 
-All sessions work without conflicts!
+---
 
-### Available Browser Tools
+## Chrome-Sisyphus: Orchestration Skill
 
-| 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) |
+For complex multi-site workflows, use the built-in **Chrome-Sisyphus** skill system.
 
-### Network Simulation
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /chrome-sisyphus "Compare iPhone prices on Amazon, eBay, Walmart"
+│                              ↓
+│  ┌──────────────────────────────────────────────────────────┐
+│  │            ORCHESTRATOR (Main Session)                   │
+│  │  • Decompose task → 3 workers                           │
+│  │  • Allocate sites → Amazon, eBay, Walmart               │
+│  │  • Context usage: ~500 tokens (lightweight!)            │
+│  └──────────────────────────────────────────────────────────┘
+│                              ↓
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
+│  │  Worker 1   │  │  Worker 2   │  │  Worker 3   │
+│  │  (Amazon)   │  │  (eBay)     │  │  (Walmart)  │
+│  │  Background │  │  Background │  │  Background │
+│  │  Task       │  │  Task       │  │  Task       │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘
+│         ↓                ↓                ↓
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
+│  │ Scratchpad  │  │ Scratchpad  │  │ Scratchpad  │
+│  │ worker-1.md │  │ worker-2.md │  │ worker-3.md │
+│  └─────────────┘  └─────────────┘  └─────────────┘
+│                              ↓
+│  Results collected → Unified report to user
+└─────────────────────────────────────────────────────────────────┘
+```
 
-Test how your app behaves under different network conditions:
+### Why This Matters: Context Isolation
 
+**Without isolation** (traditional approach):
 ```
-You: Simulate 3G network and navigate to myapp.com
-
-Claude: [Applies 3G throttling: 1.5Mbps down, 750Kbps up, 100ms latency]
+Main Session Context:
+├── Worker 1 screenshot (500KB)     ─┐
+├── Worker 1 DOM tree (large)        │
+├── Worker 2 screenshot (500KB)      ├─► Context explosion!
+├── Worker 2 DOM tree (large)        │
+└── Worker 3 ... (keeps growing)    ─┘
 ```
 
-Available presets: `offline`, `slow-2g`, `2g`, `3g`, `4g`, `fast-wifi`, `custom`, `clear`
+**With Chrome-Sisyphus**:
+```
+Main Session: ~500 tokens (stays light)
+├── Task plan
+├── Worker IDs
+└── Status summary only
+
+Background Tasks: (isolated, don't pollute main)
+├── Worker 1: own context, own screenshots
+├── Worker 2: own context, own screenshots
+└── Worker 3: own context, own screenshots
+
+Scratchpad Files: (persistent state)
+└── .agent/chrome-sisyphus/*.md
+```
 
----
+### Usage
 
-## How It Works
+Copy the `.claude/` folder to your project:
 
-### The Problem: Shared Extension State
+```bash
+cp -r node_modules/claude-chrome-parallel/.claude ~/.claude/
+# Or copy to your project root
+```
 
-The official Chrome extension maintains a single shared state:
+Then use in Claude Code:
 
 ```
-Claude Code 1 ─┐
-               ├─► Chrome Extension (shared state) ─► Chrome
-Claude Code 2 ─┘
-                    ↑
-              State conflicts here!
+/chrome-sisyphus Compare laptop prices on Amazon, BestBuy, and Newegg
 ```
 
-### The Solution: Independent CDP Connections
-
-Chrome's DevTools Protocol natively supports multiple simultaneous connections:
+### Skill Files
 
 ```
-Claude Code 1 ─► Process 1 ─► CDP Connection 1 ─┐
-                                                 ├─► Chrome (port 9222)
-Claude Code 2 ─► Process 2 ─► CDP Connection 2 ─┘
-
-Independent connections, no shared state!
+.claude/
+├── commands/
+│   └── chrome-sisyphus.md      # /chrome-sisyphus command
+└── skills/
+    └── chrome-sisyphus/
+        ├── SKILL.md            # Skill overview
+        ├── AGENTS.md           # Agent specifications
+        └── agents/
+            ├── decomposer.md   # Task decomposition
+            ├── worker-agent.md # Worker execution (Ralph Loop)
+            └── coordinator.md  # Result integration
 ```
 
-Each Claude Code session spawns its own MCP server process with a dedicated CDP connection.
-
 ---
 
-## CLI Commands
-
-```bash
-# Start MCP server (used by Claude Code automatically)
-claude-chrome-parallel serve
+## MCP Tools
 
-# Check Chrome connection status
-claude-chrome-parallel check
+### Browser Automation
 
-# Use custom Chrome debugging port
-claude-chrome-parallel serve --port 9223
+| Tool | Description |
+|------|-------------|
+| `navigate` | Go to URL, back/forward |
+| `computer` | Screenshot, click, keyboard, scroll |
+| `read_page` | Parse page structure (accessibility tree) |
+| `find` | Find elements by natural language |
+| `form_input` | Set form values directly |
+| `javascript_tool` | Execute JavaScript |
+| `network` | Simulate network conditions |
 
-# Check installation health
-claude-chrome-parallel doctor
+### Worker & Tab Management
 
-# View session status and statistics
-claude-chrome-parallel status
+| Tool | Description |
+|------|-------------|
+| `worker_create` | Create isolated browser context |
+| `worker_list` | List Workers and their tabs |
+| `worker_delete` | Delete Worker |
+| `tabs_create_mcp` | Create new tab |
+| `tabs_context_mcp` | Get tab info |
 
-# View status as JSON (for automation)
-claude-chrome-parallel status --json
+### Workflow Orchestration
 
-# Clean up stale sessions and old backups
-claude-chrome-parallel cleanup --max-age 24 --keep-backups 10
-```
+| Tool | Description |
+|------|-------------|
+| `workflow_init` | Initialize parallel workflow |
+| `workflow_status` | Check progress |
+| `workflow_collect` | Collect results |
+| `workflow_cleanup` | Clean up resources |
 
 ---
 
-## Chrome Configuration
-
-By default, connects to Chrome on port 9222.
-
-**Auto-launch**: If Chrome isn't running with debugging enabled, the package will start it automatically.
-
-**Manual start** (if needed):
+## CLI Commands
 
 ```bash
-# Windows
-chrome.exe --remote-debugging-port=9222
+ccp serve              # Start MCP server (auto-run by Claude Code)
+ccp check              # Check Chrome connection
+ccp status             # View session status
+ccp status --json      # JSON output
+ccp doctor             # Diagnose installation
+ccp cleanup            # Clean up old sessions
+ccp serve --port 9223  # Use custom port
+```
 
-# macOS
-/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
+---
 
-# Linux
-google-chrome --remote-debugging-port=9222
-```
+## Performance
+
+| Concurrent Sessions | Success Rate |
+|:---:|:---:|
+| 5 | 100% |
+| 10 | 100% |
+| 15 | 100% |
+| 20 | 100% |
 
 ---
 
 ## Additional Features
 
-### Session Isolation (Bonus)
-
-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:
+### Network Simulation
 
-```bash
-# Run Claude Code with isolated config directory
-claude-chrome-parallel launch
+```
+You: Test myapp.com loading time on 3G network
 
-# Pass any claude flags
-claude-chrome-parallel launch --dangerously-skip-permissions
-claude-chrome-parallel launch -p "Your prompt"
+Claude: [Applies 3G throttling: 1.5Mbps, 100ms latency]
 ```
 
-### Config Recovery
+Presets: `offline`, `slow-2g`, `2g`, `3g`, `4g`, `fast-wifi`, `custom`
 
-If your `.claude.json` gets corrupted:
+### Config Recovery
 
 ```bash
-# Auto-recover corrupted config
-claude-chrome-parallel recover
+# Auto-recover corrupted .claude.json
+ccp recover
 
-# List available backups
-claude-chrome-parallel recover --list-backups
+# List backups
+ccp recover --list-backups
 ```
 
----
-
-## Comparison
+### Session Isolation
 
-| 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
+# Run Claude with isolated config (prevents race conditions)
+ccp launch
+ccp launch -p "Your prompt"
+```
 
 ---
 
@@ -292,51 +403,56 @@ claude-chrome-parallel recover --list-backups
 ### Chrome not connecting
 
 ```bash
-# Check status
-claude-chrome-parallel check
-
-# Manually start Chrome with debugging
+ccp check
+# Or manually start Chrome
 chrome --remote-debugging-port=9222
 ```
 
 ### Tools not appearing in Claude Code
 
-1. Check MCP config in `~/.claude.json`
+1. Check `~/.claude.json` configuration
 2. Restart Claude Code
 3. Run `/mcp` to verify `chrome-parallel` is listed
 
 ---
 
+## Use Cases
+
+- **Business**: ERP/SaaS data extraction, invoice downloads, repetitive task automation
+- **Research**: Login-required platform data collection, academic DB searches
+- **Social Media**: Multi-account posting, message management, analytics
+- **E-commerce**: Member price monitoring, inventory management, review responses
+- **QA Testing**: Parallel scenario testing, network condition testing
+- **Productivity**: Email organization, calendar management, bookmark management
+
+---
+
 ## Development
 
 ```bash
 git clone https://github.com/shaun0927/claude-chrome-parallel.git
 cd claude-chrome-parallel
-
 npm install
 npm run build
-
-# Test locally
-npm install -g .
+npm test
 ```
 
 ---
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details.
+MIT License - [LICENSE](LICENSE)
+
+---
 
 ## Disclaimer
 
-> **This is an unofficial, community-maintained project.**
-> Not affiliated with or endorsed by Anthropic.
+> **This is an unofficial community project.**
+> Not affiliated with Anthropic.
 >
-> "Claude" is a trademark of Anthropic. This project provides
-> tooling to enhance the Claude Code experience but is not
-> an official Anthropic product.
+> "Claude" is a trademark of Anthropic.
 
 ## Acknowledgments
 
-- [Anthropic](https://anthropic.com) for Claude and the MCP protocol
-- [Claude Code](https://github.com/anthropics/claude-code) for the CLI
-- [Puppeteer](https://pptr.dev/) for browser automation
+- [Anthropic](https://anthropic.com) - Claude and MCP protocol
+- [Puppeteer](https://pptr.dev/) - Browser automation