# ChromeControlSkill

**Repository Path**: jarain/chrome-control-skill

## Basic Information

- **Project Name**: ChromeControlSkill
- **Description**: hermes(wsl)  control your chrome with profile (windows)
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-27
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Chrome Control Skill

Control your **Windows Chrome** browser from **WSL2** via the Chrome DevTools Protocol (CDP).

## Quick Start

```bash
# Step 1: Windows setup (from WSL)
powershell.exe -ExecutionPolicy Bypass -File "$(wslpath -w ~/.hermes/skills/chrome-control/scripts/setup-windows.ps1)"

# Step 2: WSL setup
bash ~/.hermes/skills/chrome-control/scripts/setup-wsl.sh

# Step 3: Verify
bash ~/.hermes/skills/chrome-control/scripts/check-cdp.sh
```

## Daily Usage

```bash
# Chrome closed? Restart it:
bash ~/.hermes/skills/chrome-control/scripts/restart-chrome.sh

# Health check:
bash ~/.hermes/skills/chrome-control/scripts/check-cdp.sh

# Take a full-resolution screenshot:
python3 ~/.hermes/skills/chrome-control/scripts/save-screenshot.py --auto
```

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/setup-windows.ps1` | One-time Windows setup: clean portproxy, kill Chrome, disable restore, open firewall, create portproxy bridge, launch headless Chrome with CDP |
| `scripts/setup-wsl.sh` | One-time WSL setup: detect gateway IP, verify CDP, configure Hermes |
| `scripts/check-cdp.sh` | Health check: verify CDP connectivity |
| `scripts/restart-chrome.sh` | Clean portproxy + kill + restart Chrome with CDP |
| `scripts/save-screenshot.py` | Save full-resolution screenshots via raw WebSocket (avoids tool output limits and Origin header issues) |

## Known Issues (Chrome 147)

- **Session restore kills CDP**: Chrome auto-restores tabs after `taskkill /F` without inheriting `--remote-debugging-port`. Scripts disable restore automatically.
- **CDP only on 127.0.0.1**: Chrome ignores `--remote-debugging-address=0.0.0.0`. Scripts set up `netsh portproxy` bridge automatically.
- **Port conflict**: Old `netsh portproxy` rules can leave `svchost` binding the CDP port. Scripts clean up stale rules automatically.
- **Wrong IP**: `10.255.255.254` (DNS) ≠ `172.22.x.x` (gateway). Scripts detect gateway IP.
- **WebSocket Origin header**: Chrome 147 rejects WebSocket connections with Origin header. The `save-screenshot.py` script connects without one.

## Architecture

Chrome's CDP binds to `127.0.0.1` only. WSL2 cannot reach Windows localhost. The bridge:

```
WSL2 (172.22.x.x) → netsh portproxy (0.0.0.0:9222 → 127.0.0.1:9222) → Chrome CDP
```

## Requirements

- Windows with Chrome installed
- WSL2 with `powershell.exe` accessible
- Hermes Agent with `browser` toolset

## Full Documentation

See [SKILL.md](SKILL.md) for detailed usage examples, all known pitfalls, and troubleshooting.

## License

MIT