reference chrome bridge

What problem this solves

The Claude-in-Chrome MCP shows a per-domain "Allow?" dialog the FIRST time each Claude session touches each site. Scheduled tasks fire when Joseph is asleep — nobody clicks Allow → task fails silently → 0 productive output despite firing on schedule.

This was the root cause of:

10 days of zero BV enrichment (Apr 16–26) — even after upgrading to Premium 400/mo
"Chrome MCP unavailable" partials in grand-county-property-scout heartbeats
Recurring "session_lost" warnings in daily-data-quality-check

The fix

chrome_bridge.py at ~/Library/Application Support/SkyRun/chrome_bridge.py controls Chrome via osascript's execute javascript API. That uses macOS Apple Events (granted ONCE in System Settings → Privacy & Security → Automation), not Chrome's per-domain ACL. Headless forever after the one-time grant.

Quick start

bash
BRIDGE="/Users/josephbowens/Library/Application Support/SkyRun/chrome_bridge.py"
TAB=$(/usr/bin/python3 "$BRIDGE" find "beenverified.com")
/usr/bin/python3 "$BRIDGE" js "$TAB" "document.title"

python
sys.path.insert(0, '/Users/josephbowens/Library/Application Support/SkyRun')
from chrome_bridge import ChromeBridge
cb = ChromeBridge()
tab = cb.find_tab(url_contains="beenverified.com") or cb.open_tab("https://www.beenverified.com/")
cb.wait_for_load(tab)
cb.fill(tab, 'input[name="name"]', 'Joe Smith')
cb.click(tab, 'button[type="submit"]')
cb.wait_for(tab, "document.querySelectorAll('[data-test-id=\"result-card\"]').length > 0", timeout=20)

Capabilities

find_tab(url_contains=) — locate an open tab by URL substring
open_tab(url) — open a new tab in window 1
navigate(tab, url) — change a tab's URL
js(tab, code) — execute JS, return last expression
get_text(tab) — document.body.innerText (bypasses Chrome MCP content filter)
wait_for(tab, condition_js, timeout) — poll until truthy
fill(tab, selector, value) — set input value with React/Vue native setter
click(tab, selector) — click element by CSS selector
close_tab(tab) — close

CLI surface for shell scripts: find / open / nav / js / text / title / wait / list.

Required heartbeat metrics for any skill using the bridge

json
"metrics": {
  ...,
  "chrome_bridge_status": "ok" | "session_lost" | "auth_expired" | "tab_not_found" | "timeout"
}

The system-hygiene watchdog has a rule that escalates if a task ran but reported 0 productive output AND chrome_bridge_status: ok — that's the "silent failure" pattern. Without the bridge-status field, the watchdog can't tell skipped-by-design from broken-and-pretending-to-work.

Important: tab indices change

Chrome tab indices shift when:

A new tab opens
Chrome reorders for any reason
Joseph manually moves a tab

Always re-find your tab after navigate(), open_tab(), or any operation that triggers tab churn. The bridge's find_tab(url_contains=...) is fast and reliable. The TabRef object's .window/.tab indices go stale.

Authentication

The bridge does NOT handle authentication. Sites are assumed to be already logged in. Skills using the bridge must:
1. Detect login redirect via location.href.includes('login') or similar
2. Heartbeat with chrome_bridge_status: "auth_expired" and status: error
3. Push ntfy at high priority

Migration status

Skill	Migrated?
`daily-beenverified-enrichment`	✅ 2026-04-26
`daily-data-quality-check`	🟡 next batch
`grand-county-property-scout`	🟡 next batch
`gmail-deep-scan`	🟡 next batch
`transcript-scan`	🟡 next batch
`nightly-consolidation`	🟡 next batch
`historical-gmail-backfill`	✅ COMPLETE + disabled
`live-ea`	⚪ Runs interactively during business hours; Chrome MCP fine here

Files

Path	Purpose
`~/Library/Application Support/SkyRun/chrome_bridge.py`	Implementation
`~/Library/Application Support/SkyRun/chrome_bridge.md`	Canonical docs (skill-readable)
`~/Library/Logs/skyrun-chrome-bridge.log`	Per-call log

reference_system_hygiene.md — the watchdog with BV silent-failure escalation
reference_beenverified_rotation.md — the BV skill that was blocked 10 days