claude-chrome-parallel 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,353 @@
+# Claude Chrome Parallel
+
+> **Run multiple Claude Code sessions safely - no more "Detached" errors or config corruption.**
+
+[![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
+
+- **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
+
+---
+
+## Problem 1: Config File Corruption
+
+When running **multiple Claude Code instances** simultaneously, they compete to write to `~/.claude.json`, causing corruption:
+
+```
+Terminal 1: claude  ──┐
+                      ├──► ~/.claude.json ← Race condition!
+Terminal 2: claude  ──┘
+
+Result: {"key":"value"}{"key":"value"}  ← Two JSON objects concatenated = CORRUPT
+```
+
+**Symptoms:**
+- Claude Code crashes on startup
+- "Unexpected token" JSON parse errors
+- Lost settings and preferences
+
+## Solution: Session Isolation
+
+```bash
+# Instead of running claude directly...
+claude-chrome-parallel launch
+
+# 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
+```
+
+**All your existing flags work:**
+
+```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
+```
+
+---
+
+## Problem 2: Browser "Detached" Errors
+
+When using browser automation with multiple sessions:
+
+```
+Error: Detached while handling command
+```
+
+The Chrome extension uses **shared internal state** - when Session A takes a screenshot, Session B's connection breaks.
+
+## Solution: Independent CDP Connections
+
+```
+Claude Code 1 ──► puppeteer process 1 ──► CDP connection 1 ──┐
+                                                              ├──► Chrome
+Claude Code 2 ──► puppeteer process 2 ──► CDP connection 2 ──┘
+```
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+
+- Google Chrome (for browser automation)
+
+### Install
+
+```bash
+# From npm
+npm install -g claude-chrome-parallel
+
+# Or from GitHub
+npm install -g github:shaun0927/claude-chrome-parallel
+```
+
+---
+
+## Usage
+
+### Session Isolation (Recommended for Multiple Instances)
+
+```bash
+# Start Claude Code with isolated config
+claude-chrome-parallel launch
+
+# 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
+
+# Keep session directory for debugging
+claude-chrome-parallel launch --keep-session
+```
+
+### Standalone Wrapper (Alternative)
+
+```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
+```
+
+### Recovery Commands
+
+```bash
+# Check config health
+claude-chrome-parallel doctor
+
+# Auto-recover corrupted .claude.json
+claude-chrome-parallel recover
+
+# List available backups
+claude-chrome-parallel recover --list-backups
+
+# Restore from specific backup
+claude-chrome-parallel recover --backup ".claude.json.2024-01-15T10-30-00-000Z.bak"
+
+# 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
+```
+
+### Browser Automation (MCP Server)
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "chrome-parallel": {
+      "command": "claude-chrome-parallel",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+Then use in Claude Code:
+
+```
+You: Take a screenshot of https://github.com
+
+Claude: [Uses chrome-parallel tools automatically]
+```
+
+**Run multiple sessions with browser automation:**
+
+```bash
+# Terminal 1
+claude-chrome-parallel launch
+> Take a screenshot of github.com
+
+# Terminal 2 (simultaneously!)
+claude-chrome-parallel launch
+> Take a screenshot of google.com
+```
+
+Both work without conflicts!
+
+---
+
+## 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 |
+
+### Launch Options
+
+| Option | Description |
+|--------|-------------|
+| `--sync-back` | Sync config changes back to original on exit |
+| `--keep-session` | Keep session directory after exit (debugging) |
+
+### Recover Options
+
+| Option | Description |
+|--------|-------------|
+| `--list-backups` | List available backup files |
+| `--backup <name>` | Restore from specific backup |
+| `--force-new` | Create new empty config (loses all data) |
+
+### Cleanup Options
+
+| Option | Description |
+|--------|-------------|
+| `--max-age <hours>` | Max session age in hours (default: 24) |
+| `--keep-backups <n>` | Number of backups to keep (default: 10) |
+
+---
+
+## Browser Automation Tools
+
+| 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 |
+
+---
+
+## How It Works
+
+### Session Isolation
+
+```
+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 │
+└─────────────────────────────────────────────┘
+```
+
+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
+
+### Browser Automation
+
+Chrome's DevTools Protocol natively supports multiple connections:
+
+```
+Process 1 ─► CDP Connection 1 ─┐
+                               ├─► Chrome (port 9222)
+Process 2 ─► CDP Connection 2 ─┘
+```
+
+---
+
+## Troubleshooting
+
+### Config Corruption
+
+```bash
+# Check health
+claude-chrome-parallel doctor
+
+# If corrupted, recover
+claude-chrome-parallel recover
+```
+
+### Chrome Not Connecting
+
+```bash
+# Check status
+claude-chrome-parallel check
+
+# Manually start Chrome with debugging
+chrome --remote-debugging-port=9222
+```
+
+### Tools Not Appearing
+
+1. Check MCP config in `~/.claude.json`
+2. Restart Claude Code
+3. Run `/mcp` to verify `chrome-parallel` is listed
+
+---
+
+## 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 .
+```
+
+---
+
+## 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.
+
+## Disclaimer
+
+> **This is an unofficial, community-maintained project.**
+> Not affiliated with or endorsed by Anthropic.
+>
+> "Claude" is a trademark of Anthropic. This project provides
+> tooling to enhance the Claude Code experience but is not
+> an official Anthropic product.
+
+## 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

package/dist/cdp/client.d.ts

@@ -0,0 +1,120 @@
+/**
+ * CDP Client - Wrapper around puppeteer-core for Chrome DevTools Protocol
+ */
+import { Browser, Page, Target, CDPSession } from 'puppeteer-core';
+export interface CDPClientOptions {
+    port?: number;
+    maxReconnectAttempts?: number;
+    reconnectDelayMs?: number;
+    heartbeatIntervalMs?: number;
+}
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+export interface ConnectionEvent {
+    type: 'connected' | 'disconnected' | 'reconnecting' | 'reconnect_failed';
+    timestamp: number;
+    attempt?: number;
+    error?: string;
+}
+export declare class CDPClient {
+    private browser;
+    private sessions;
+    private port;
+    private maxReconnectAttempts;
+    private reconnectDelayMs;
+    private heartbeatIntervalMs;
+    private heartbeatTimer;
+    private connectionState;
+    private eventListeners;
+    private reconnectAttempts;
+    constructor(options?: CDPClientOptions);
+    /**
+     * Get current connection state
+     */
+    getConnectionState(): ConnectionState;
+    /**
+     * Add connection event listener
+     */
+    addConnectionListener(listener: (event: ConnectionEvent) => void): void;
+    /**
+     * Remove connection event listener
+     */
+    removeConnectionListener(listener: (event: ConnectionEvent) => void): void;
+    /**
+     * Emit connection event
+     */
+    private emitConnectionEvent;
+    /**
+     * Start heartbeat monitoring
+     */
+    private startHeartbeat;
+    /**
+     * Stop heartbeat monitoring
+     */
+    private stopHeartbeat;
+    /**
+     * Check connection health
+     */
+    private checkConnection;
+    /**
+     * Handle disconnection with automatic reconnection
+     */
+    private handleDisconnect;
+    /**
+     * Internal connect logic
+     */
+    private connectInternal;
+    /**
+     * Connect to Chrome instance
+     */
+    connect(): Promise<void>;
+    /**
+     * Force reconnect by disconnecting and reconnecting
+     */
+    forceReconnect(): Promise<void>;
+    /**
+     * Disconnect from Chrome
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Get browser instance
+     */
+    getBrowser(): Browser;
+    /**
+     * Create a new page
+     */
+    createPage(url?: string): Promise<Page>;
+    /**
+     * Get all page targets
+     */
+    getPages(): Promise<Page[]>;
+    /**
+     * Get page by target ID
+     */
+    getPageByTargetId(targetId: string): Promise<Page | null>;
+    /**
+     * Get CDP session for a page
+     */
+    getCDPSession(page: Page): Promise<CDPSession>;
+    /**
+     * Execute CDP command on a page
+     */
+    send<T = unknown>(page: Page, method: string, params?: Record<string, unknown>): Promise<T>;
+    /**
+     * Get all targets
+     */
+    getTargets(): Target[];
+    /**
+     * Find target by ID
+     */
+    findTarget(targetId: string): Target | undefined;
+    /**
+     * Close a page by target ID
+     */
+    closePage(targetId: string): Promise<void>;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+}
+export declare function getCDPClient(options?: CDPClientOptions): CDPClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/cdp/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/cdp/client.ts"],"names":[],"mappings":"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"}