eyebrowse-setup

name: eyebrowse-setup description: Install, configure, and troubleshoot Eyebrowse browser bridge

Eyebrowse Setup & Diagnostics

When this skill is invoked, run all diagnostic checks below in order and report a status table. Then offer to fix anything that's broken.

Architecture Quick Reference

Eyebrowse has three parts:

• Daemon — Bun HTTP/WS server on localhost:7890 (manages sessions, bridges MCP ↔ extension)
• MCP Server — stdio wrapper that registers with the daemon and exposes browser tools to Claude Code
• Chrome Extension — WebSocket client that executes commands in Chrome via CDP

Flow: Claude Code → MCP (stdio) → Daemon (HTTP :7890) → Extension (WS) → Chrome

Diagnostic Checks

Run these checks and present results as a status table:

1. Daemon Health

curl -sf http://localhost:7890/health

• OK → daemon is running
• Connection refused → daemon is not running (see "Start the Daemon" below)
• Timeout → port 7890 may be blocked or daemon is hung

2. Extension Connected

Read the daemon token, then query windows:

TOKEN=$(cat ~/.eyebrowse/daemon.token 2>/dev/null)
curl -sf -H "Authorization: Bearer $TOKEN" http://localhost:7890/api/windows

• Returns JSON array with windows → extension is connected and Chrome is open
• Empty array [] → extension is installed but no Chrome windows are open
• 401/no token → daemon token missing (daemon may need restart)
• Connection refused → daemon not running

3. MCP Config

Read ~/.claude.json and check for mcpServers.eyebrowse. It should look like:

{
  "mcpServers": {
    "eyebrowse": {
      "command": "bun",
      "args": ["run", "<EYEBROWSE_HOME>/mcp/index.ts"]
    }
  }
}

Where <EYEBROWSE_HOME> is the path to the eyebrowse repo (e.g. /Users/evan/memory/eyebrowse).

• Present and correct → MCP is configured
• Missing → add the config (see "Configure MCP" below)
• Wrong path → update the path to match the actual repo location

4. End-to-End Test

If checks 1-3 pass, run a live test:

1. Call mcp__eyebrowse__open_browser with url https://example.com
2. Call mcp__eyebrowse__screenshot
3. Verify the screenshot shows the Example Domain page
4. Call mcp__eyebrowse__close_window

If this works, eyebrowse is fully operational.

Setup Guide

Install Dependencies

cd <EYEBROWSE_HOME> && bun install
cd <EYEBROWSE_HOME>/daemon && bun install
cd <EYEBROWSE_HOME>/mcp && bun install

Install the Chrome Extension

1. Open chrome://extensions in Chrome
2. Enable "Developer mode" (top right toggle)
3. Click "Load unpacked"
4. Select <EYEBROWSE_HOME>/extension/
5. The eyebrowse icon should appear in the toolbar

Start the Daemon

Option A — LaunchD (auto-start on boot, recommended):

# Fill in template placeholders
BUN_PATH=$(which bun)
BUN_DIR=$(dirname "$BUN_PATH")
EYEBROWSE_HOME="<EYEBROWSE_HOME>"

sed -e "s|__BUN_PATH__|$BUN_PATH|g" \
    -e "s|__BUN_DIR__|$BUN_DIR|g" \
    -e "s|__EYEBROWSE_HOME__|$EYEBROWSE_HOME|g" \
    "$EYEBROWSE_HOME/com.eyebrowse.daemon.plist" \
    > ~/Library/LaunchAgents/com.eyebrowse.daemon.plist

launchctl load ~/Library/LaunchAgents/com.eyebrowse.daemon.plist

Option B — Manual (foreground, good for debugging):

bun run <EYEBROWSE_HOME>/daemon/index.ts

Configure MCP

Read ~/.claude.json, merge in the eyebrowse MCP server config, and write it back:

{
  "mcpServers": {
    "eyebrowse": {
      "command": "bun",
      "args": ["run", "<EYEBROWSE_HOME>/mcp/index.ts"]
    }
  }
}

After adding, restart Claude Code for the MCP server to load.

Common Issues

Key Paths