browser-setup · diff
git:20260523.aadc7ee to git:20260526.a372b8d
90 added, 0 removed. Audit A to A.
---
name: browser-setup
description: |
Configure the browser tool for Clacky. Guides the user through Chrome or Edge setup,
verifies the connection, and writes ~/.clacky/browser.yml.
Supports macOS, Linux, and WSL (Windows Chrome/Edge via remote debugging).
Trigger on: "browser setup", "setup browser", "配置浏览器", "browser config",
"browser doctor".
Subcommands: setup, doctor.
argument-hint: "setup | doctor"
allowed-tools:
- Bash
- Read
- Write
- browser
---
# Browser Setup Skill
Configure the browser tool for Clacky. Config is stored at `~/.clacky/browser.yml`.
## Region-Aware Download Links
Whenever you show the user a link to download or upgrade Chrome/Edge, pick the right one for their region instead of always using google.com.
Treat the user as **in China** when any of these is true:
- The user is talking to you in Chinese
- The system locale is Chinese (`echo $LANG` contains `zh_CN` / `zh_`)
- A previous run of `install_browser.sh` reported `Region: china` (visible in its output)
- `curl -s --max-time 3 https://www.google.com -o /dev/null -w "%{http_code}"` returns `000` while baidu.com works
Use these links accordingly:
| Region | Chrome | Edge |
|---|---|---|
| China | https://www.google.cn/chrome/ | https://www.microsoft.com/zh-cn/edge |
| Global | https://www.google.com/chrome/ | https://www.microsoft.com/edge |
When unsure, show **both** lines (label them "China:" and "Global:") so the user can pick.
## Command Parsing
| User says | Subcommand |
|---|---|
| `browser setup`, `配置浏览器`, `setup browser` | setup |
| `browser doctor` | doctor |
If no subcommand is clear, default to `setup`.
---
## `setup`
**Core Strategy**: Progressive validation with clear next steps at each failure point.
### Step 1 — Ensure Node.js is installed
Check Node.js version:
```bash
node --version 2>/dev/null
```
Parse the version. If Node.js is missing or version < 20:
Run the bundled installer to automatically install Node.js:
```bash
bash ~/.clacky/scripts/install_browser.sh
```
If the script exits 0 → Node.js is now installed. Proceed to Step 2.
If the script exits non-zero or doesn't exist:
> ❌ Node.js 20+ is required for browser automation.
>
> Please install Node.js from: https://nodejs.org
>
> Let me know when done and I'll continue.
Wait for user confirmation, then retry this step once. If still failing, stop.
### Step 2 — Ensure chrome-devtools-mcp is installed
Check if installed:
```bash
chrome-devtools-mcp --version 2>/dev/null
```
If found and exits 0 → skip to Step 3.
If missing, run the bundled installer:
```bash
bash ~/.clacky/scripts/install_browser.sh
```
If the script exits non-zero or doesn't exist:
> ❌ Failed to install chrome-devtools-mcp automatically.
>
> Please run manually:
> ```
> npm install -g chrome-devtools-mcp@latest
> ```
>
> Let me know when done.
Wait for user confirmation, then verify installation:
```bash
chrome-devtools-mcp --version 2>/dev/null
```
If still missing after user confirms, stop with error message.
+ ### Step 2.5 — WSL networking setup (only when session context shows `OS: WSL/Windows`)
+
+ **Skip this entire step on macOS / Linux.** Look at the session context line that begins with `[Session context: ...]` — only run this step if it includes `OS: WSL/Windows`.
+
+ #### Background (read this so you know what to do)
+
+ The browser tool runs inside WSL but Chrome/Edge runs on Windows. By default WSL2 uses NAT networking, which means `127.0.0.1` inside WSL **cannot** reach Windows' Chrome debug port. The fix is to enable WSL2 **mirrored networking** (`networkingMode=mirrored` in `%USERPROFILE%\.wslconfig`), which makes WSL share Windows' network stack so `127.0.0.1` works directly.
+
+ We have a helper script that handles all the Windows-side details:
+
+ ```
+ ~/.clacky/scripts/wsl_network_doctor.ps1
+ ```
+
+ It exposes three subcommands:
+
+ | Subcommand | What it does | Exit code |
+ |---|---|---|
+ | `status` | Check whether mirrored is configured (auto-passes on WSL1) | `0` OK / `10` NEED_ENABLE |
+ | `enable` | Write `networkingMode=mirrored` to `.wslconfig` (does NOT shut down WSL) | `0` success / `1` fail |
+ | `repair` | Restart Windows Host Network Service (HNS) via UAC prompt | `0` launched / `1` fail |
+
+ Invoke it from WSL like this:
+
+ ```bash
+ powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$(wslpath -w ~/.clacky/scripts/wsl_network_doctor.ps1)" <subcommand>
+ ```
+
+ #### Step 2.5.1 — Check status
+
+ ```bash
+ powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$(wslpath -w ~/.clacky/scripts/wsl_network_doctor.ps1)" status
+ ```
+
+ - Exit `0` (output starts with `OK:`) → either mirrored is configured (WSL2) or
+ Ubuntu is running on WSL1 (which shares the Windows network stack and needs no
+ config). Either way, proceed to Step 3.
+ - Exit `10` (output starts with `NEED_ENABLE:`) → continue to Step 2.5.2.
+ - Any other failure → show the output to the user and ask them to retry. Stop here.
+
+ #### Step 2.5.2 — Enable mirrored (only when NEED_ENABLE)
+
+ Tell the user what's about to happen (in their language):
+
+ > WSL doesn't have mirrored networking enabled yet — the browser tool needs it to reach Chrome on Windows.
+ > I'll add one line to `%USERPROFILE%\.wslconfig`. Your current WSL session will NOT be restarted.
+
+ Run:
+
+ ```bash
+ powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$(wslpath -w ~/.clacky/scripts/wsl_network_doctor.ps1)" enable
+ ```
+
+ If the script exits `0`:
+
+ > ✅ `.wslconfig` updated. Tell the user (in their language):
+ >
+ > The config takes effect only after WSL restarts, but we can't restart WSL from inside WSL.
+ > Please:
+ >
+ > 1. Open **PowerShell** on Windows
+ > 2. Run: `wsl --shutdown`
+ > 3. Reopen the Clacky terminal
+ > 4. Run `/browser-setup` again
+ >
+ > Stop here. Wait for the user to come back in a new session.
+
+ If the script exits non-zero, show the output to the user and stop. Do NOT proceed to Step 3 — without mirrored networking the browser tool will not work.
+
+ #### Step 2.5.3 — When to run repair
+
+ Do NOT run `repair` proactively. Only run it later if **all** of the following are true:
+
+ - `status` returned `OK` (mirrored is configured)
+ - The user has restarted WSL since the config was written
+ - Step 3's `browser(action="status")` still fails with a "Chrome/Edge is not running or remote debugging is not enabled" error
+
+ In that situation, tell the user (in their language):
+
+ > The config looks correct but the browser still can't connect. Windows Host Network Service may be stuck — I'll restart it.
+ > **A Windows User Account Control (UAC) prompt will appear shortly. Please click "Yes".**
+
+ Then run:
+
+ ```bash
+ powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$(wslpath -w ~/.clacky/scripts/wsl_network_doctor.ps1)" repair
+ ```
+
+ After it returns, tell the user to run `wsl --shutdown` in PowerShell and reopen Clacky. Stop and wait.
+
### Step 3 — Verify Chrome/Edge is running with remote debugging
**CRITICAL**: Do NOT attempt `browser()` calls yet. First check if the browser is reachable using the API:
```bash
curl -s http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/browser/status
```
This returns JSON with `daemon_running` and `enabled` status. **Ignore the result for now** — we just need to see if the Clacky server is running.
Now attempt a browser connection to detect Chrome:
```bash
browser(action="status")
```
**If this succeeds** → Chrome is running and reachable. Proceed to Step 4.
**If this fails** → The error message will indicate the specific issue. Parse it carefully:
#### Case A: "Chrome/Edge is not running or remote debugging is not enabled"
This is the most common case. The system can't find Chrome's DevToolsActivePort file or the port is not reachable.
**Action**: Guide the user to enable remote debugging.
**On macOS**:
```bash
open "chrome://inspect/#remote-debugging" 2>/dev/null || echo "Please open chrome://inspect/#remote-debugging manually"
```
Then tell the user:
> I've tried to open the remote debugging page in Chrome.
>
> Please follow these steps:
> 1. Make sure **Chrome or Edge is open**
> 2. Visit: `chrome://inspect/#remote-debugging` (or `edge://inspect/#remote-debugging`)
> 3. Click **"Allow remote debugging for this browser instance"**
> 4. You should see a brief connection message appear
>
> Let me know when done ✅
**On Linux (non-WSL)**:
> Please follow these steps:
> 1. Make sure **Chrome or Edge is open**
> 2. Visit: `chrome://inspect/#remote-debugging`
> 3. Click **"Allow remote debugging for this browser instance"**
>
> Let me know when done ✅
**On WSL**:
> Please follow these steps:
> 1. Open **Edge** on Windows
> 2. Visit: `edge://inspect/#remote-debugging`
> 3. Click **"Allow remote debugging for this browser instance"**
>
> Let me know when done ✅
**After user confirms**, retry the connection **once**:
```bash
browser(action="status")
```
If still failing:
> ❌ Still unable to connect to Chrome.
>
> Please make sure:
> - Chrome/Edge is running
> - You clicked "Allow remote debugging" in chrome://inspect/#remote-debugging
> - No firewall is blocking localhost connections
>
> Run `/browser-setup doctor` to diagnose the issue in detail.
Stop here and suggest running doctor.
#### Case B: Other errors (MCP handshake timeout, daemon crash, etc.)
For any other error message, show it to the user and suggest:
> ❌ Browser connection failed: <error message>
>
> This may be a temporary issue. Please try:
> 1. Restart your browser
> 2. Run `/browser-setup` again
>
> If the problem persists, run `/browser-setup doctor` for detailed diagnostics.
### Step 4 — Get and verify browser version
Now that connection is established, get the version:
```bash
browser(action="act", kind="evaluate", js="navigator.userAgentData?.brands?.find(b => b.brand === 'Google Chrome' || b.brand === 'Microsoft Edge')?.version || navigator.userAgent.match(/Chrome\/(\d+)/)?.[1] || 'unknown'")
```
Parse the version number:
- **version >= 146** → Excellent, proceed
- **version 144-145** → Show warning but proceed:
> ⚠️ Your browser version is v${VERSION}. Version 146+ is recommended for best compatibility.
> Continuing anyway...
- **version < 144 or "unknown"** → Stop:
> ❌ Browser version v${VERSION} is too old. Please upgrade Chrome or Edge to v146+.
>
> Use the download link from the **Region-Aware Download Links** section above
> (pick `China` or `Global` based on the user's region).
>
> After upgrading, run `/browser-setup` again.
### Step 5 — Save configuration via API
Call the API to save the configuration:
```bash
curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/browser/configure \
-H "Content-Type: application/json" \
-d "{\"chrome_version\":\"${VERSION}\"}"
```
If this fails (HTTP error or empty response), show a warning:
> ⚠️ Failed to save configuration via API. You may need to run `/browser-setup` again after restarting Clacky.
### Step 6 — Done
> ✅ Browser setup complete!
>
> **Chrome/Edge v${VERSION}** is connected and ready to use.
>
> You can now use browser automation features. Try asking me to:
> - "Open google.com in the browser"
> - "Take a screenshot"
> - "Fill out a form on this page"
---
## `doctor`
**Core Strategy**: Diagnose don't fix. Check each component and report status.
This is a **diagnostic tool**, not a repair tool. It will check each component and tell you what's wrong, but won't automatically fix things.
### Diagnostic Steps
Run all checks **before** showing results. Then show a summary report.
#### 1. Check Config File
```bash
test -f ~/.clacky/browser.yml && cat ~/.clacky/browser.yml
```
Parse the result:
- **File missing** → ❌ Not configured
- **File exists, `enabled: false`** → ⏸️ Disabled
- **File exists, `enabled: true`** → ✅ Enabled
#### 2. Check Node.js
```bash
node --version 2>/dev/null
```
- **Not found** → ❌ Node.js not installed
- **Version < 20** → ❌ Node.js too old (need 20+)
- **Version >= 20** → ✅ Node.js OK
#### 3. Check chrome-devtools-mcp
```bash
chrome-devtools-mcp --version 2>/dev/null
```
- **Not found** → ❌ Not installed
- **Found** → ✅ Installed (version: ...)
#### 4. Check Clacky Server
```bash
curl -s -f http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/browser/status
```
- **Failed** → ❌ Server not responding
- **Success** → Parse JSON and show `daemon_running` status
#### 5. Check Chrome Connection
Only run this if steps 1-4 are OK.
```bash
browser(action="status")
```
- **Success** → ✅ Connected. Also get the tab count from the result.
- **Failed** → ❌ Not connected. Parse the error message to determine cause.
#### 6. Check Chrome Version
Only run this if step 5 succeeded.
```bash
browser(action="act", kind="evaluate", js="navigator.userAgent.match(/Chrome\/(\d+)/)?.[1] || 'unknown'")
```
- **version >= 146** → ✅ Excellent
- **version 144-145** → ⚠️ Acceptable but upgrade recommended
- **version < 144 or unknown** → ❌ Too old
### Report Format
Show results in a clean table:
```
Browser Doctor — Diagnostic Report
═══════════════════════════════════════════════════════════════
Configuration
[✅] Config file found (~/.clacky/browser.yml)
[✅] Browser tool enabled
Dependencies
[✅] Node.js v22.1.0
[✅] chrome-devtools-mcp installed (v1.2.3)
Connection
[✅] Clacky server running
[✅] MCP daemon running
[✅] Chrome connected (3 tabs open)
[✅] Chrome v146
═══════════════════════════════════════════════════════════════
✅ All systems operational!
```
If there are any ❌ or ⚠️ items, show them first in a **Problems Found** section, followed by specific **Recommended Actions**:
```
Browser Doctor — Diagnostic Report
═══════════════════════════════════════════════════════════════
⚠️ Problems Found
[❌] Chrome not connected
Error: Chrome/Edge is not running or remote debugging is not enabled
[❌] Chrome version v142 is too old
───────────────────────────────────────────────────────────────
Configuration
[✅] Config file found
[✅] Browser tool enabled
Dependencies
[✅] Node.js v22.1.0
[✅] chrome-devtools-mcp installed
Connection
[✅] Clacky server running
[❌] Chrome not connected
═══════════════════════════════════════════════════════════════
🔧 Recommended Actions
1. Enable remote debugging:
- Open Chrome and visit: chrome://inspect/#remote-debugging
- Click "Allow remote debugging for this browser instance"
2. Upgrade your browser:
- Chrome v142 is too old (need v146+)
- Pick the download link for the user's region from the
**Region-Aware Download Links** section at the top of this skill
(China users → google.cn; others → google.com).
After fixing these issues, run `/browser-setup` again to verify.
```
### Common Diagnostic Scenarios
**Scenario 1: Config not found**
```
[❌] Config file not found
🔧 Fix: Run `/browser-setup` to configure the browser tool.
```
**Scenario 2: Chrome not running**
```
[❌] Chrome not connected
Error: Chrome/Edge is not running or remote debugging is not enabled
🔧 Fix:
1. Open Chrome or Edge
2. Visit: chrome://inspect/#remote-debugging
3. Click "Allow remote debugging"
```
**Scenario 3: MCP not installed**
```
[❌] chrome-devtools-mcp not installed
🔧 Fix: Run `npm install -g chrome-devtools-mcp@latest`
(or run `/browser-setup` to install automatically)
```
**Scenario 4: Everything OK**
```
✅ All systems operational!
The browser tool is ready to use.
```