hybrid-debugging

# Hybrid Debugging: Browser Use + claude-in-chrome Patterns for combining Browser Use MCP tools with claude-in-chrome to achieve full-spectrum browser debugging. **Core principle**: Browser Use and claude-in-chrome have complementary capabilities. Neither covers everything alone. Hybrid workflows combine their strengths. --- ## 1. Tool Capability Map | Capability | Browser Use | claude-in-chrome | |-----------|-------------|-----------------| | Navigate to URL | `browser_navigate` | `navigate` | | Click elements | `browser_click` (by index) | `computer` (by coordinate) | | Type into inputs | `browser_type` (by index) | `computer` (keyboard) | | Get DOM element map | `browser_get_state` | `read_page` (text extract) | | Read raw HTML | `browser_get_html` | `read_page` | | Take screenshot | `browser_screenshot` (seen by the model); `browser_save_screenshot` (PNG file) | `computer` (screenshot) | | Capture full-page screenshot | `browser_screenshot(full_page=True)` | Not available | | Scroll page | `browser_scroll` | `computer` (scroll) | | Read console errors | An error hook installed with `browser_evaluate` (§4.1) | `read_console_messages` | | Read network requests | URLs and statuses from `performance` entries via `browser_evaluate` (§4.2) | `read_network_requests` | | Execute JavaScript | `browser_evaluate` (in its own page) | `javascript_tool` | | Resize viewport | Not available | `resize_window` | | Record GIF of interaction | Not available | `gif_creator` | | Autonomous agent mode | `retry_with_browser_use_agent` | Not available | | Multi-tab session | `browser_navigate(new_tab=True)` | Tab enumeration only | | Export/import session cookies | `browser_export/import_session` | Not available | | Work on headless browser | Yes (Chromium) | No (requires headed Chrome) | | Work on developer's Chrome | No | Yes (attaches to running Chrome) | --- ## 2. Detecting claude-in-chrome Availability Before using hybrid patterns, verify claude-in-chrome is accessible. It requires Chrome to be running with the Claude Chrome extension installed. ``` # Probe for claude-in-chrome availability mcp__claude-in-chrome__tabs_context_mcp() → If successful: returns list of open Chrome tabs → claude-in-chrome IS available → If error/timeout: claude-in-chrome NOT available → fall back to Browser Use-only mode ``` **Decision**: ``` available = probe claude-in-chrome if available: use hybrid workflow (see Section 3-4) else: use Browser Use-only fallback (see Section 5) ``` --- ## 3. Tool Selection Decision Table Use this table when deciding which tool to reach for: | Task | Primary Tool | Fallback | |------|-------------|----------| | Navigate to a URL | `browser_navigate` | N/A (no CiC nav) | | Click a button by DOM element | `browser_click` (index) | `mcp__claude-in-chrome__computer` (coord) | | Read what errors appeared in console | `read_console_messages` | Not possible with BU alone | | Trace which API calls a button made | `read_network_requests` | Not possible with BU alone | | Get the current DOM element map | `browser_get_state` | `read_page` (text only, less structured) | | Execute arbitrary JavaScript | `browser_evaluate` (BU's page) | `javascript_tool` (the user's Chrome) | | Capture full-page screenshot | `browser_screenshot(full_page=True)` | `computer` (viewport only) | | Record a GIF of a user flow | `gif_creator` | screenshot sequence (not animated) | | Autonomous complex task | `retry_with_browser_use_agent` | Not possible with CiC alone | | Scrape structured data across pages | `browser_extract_content` + pagination | `javascript_tool` (scrape in-page) | | Test on user's real logged-in Chrome | `tabs_context_mcp` + CiC tools | Import session (BU) | --- ## 4. Hybrid Workflow Patterns **Two browsers, not one.** Browser Use drives its own headless Chromium; claude-in-chrome reads the user's Chrome. Console and network reads from claude-in-chrome describe the Chrome tab, never Browser Use's session. For the patterns below to observe the same page, open the URL in the user's Chrome too (`mcp__claude-in-chrome__navigate`) and reproduce the action there; use Browser Use for what only it has (indexed DOM map, full-page screenshots, the autonomous agent). ### 4.1 Pattern: Click + Console Errors **Use case**: "The checkout button throws an error — find out what JavaScript error occurs." In the user's Chrome (claude-in-chrome), where the console is readable: ``` 1. mcp__claude-in-chrome__navigate(url="https://app.example.com/cart") → returns the tab list; note tabId 2. mcp__claude-in-chrome__find(query="Checkout button", tabId=T) → its ref 3. mcp__claude-in-chrome__computer(action="left_click", ref="ref_…", tabId=T) 4. mcp__claude-in-chrome__read_console_messages(tabId=T, pattern="Error|Warning", onlyErrors=true) → the errors this click raised, with file:line ``` In Browser Use alone, install an error hook before the action and read it after: ``` 1. browser_navigate(url="https://app.example.com/cart") 2. browser_evaluate(script="window.__errs=[]; addEventListener('error', e => __errs.push(e.message + ' @ ' + e.filename + ':' + e.lineno)); addEventListener('unhandledrejection', e => __errs.push(String(e.reason))); const ce = console.error; console.error = (...a) => { __errs.push(a.join(' ')); ce(...a) }; return true") 3. browser_get_state() → "Checkout" button → index 7 4. browser_click(index=7) 5. browser_evaluate(script="return window.__errs") 6. browser_save_screenshot(output_path="/abs/path/after-checkout.png") ``` The hook sees only what happens after step 2; an error during page load needs claude-in-chrome. ### 4.2 Pattern: Submit + Network Requests **Use case**: "When I submit this form, what API calls are made and are they returning correctly?" In the user's Chrome (full request list, statuses, bodies): ``` 1. mcp__claude-in-chrome__navigate(url="https://app.example.com/signup") 2. mcp__claude-in-chrome__form_input(…, tabId=T) for each field, then click submit with computer 3. mcp__claude-in-chrome__read_network_requests(tabId=T, urlPattern="/api/") ``` In Browser Use alone, the Resource Timing entries give URL, type and status (no bodies): ``` 1. browser_navigate(url="https://app.example.com/signup") 2. browser_get_state() → field indices; browser_type(…) each; browser_click(index=<submit>) 3. browser_evaluate(script="return performance.getEntriesByType('resource').filter(e => e.initiatorType === 'fetch' || e.initiatorType === 'xmlhttprequest').map(e => ({url: e.name, status: e.responseStatus, ms: Math.round(e.duration)}))") ``` ### 4.3 Pattern: Action + Application State **Use case**: "After adding to cart, verify the cart count in the header updates correctly." This needs no second browser: `browser_evaluate` reads state in the page Browser Use drives. ``` 1. browser_navigate(url="https://shop.example.com/product/widget-a") 2. browser_get_state() → "Add to Cart" → index 5 3. browser_click(index=5) 4. browser_evaluate(script="return {store: window.__STORE__?.cart?.items?.length, badge: document.querySelector('.cart-count')?.textContent}") → {"result": {"store": 3, "badge": "3"}} 5. browser_screenshot() → the badge as the user sees it ``` ### 4.4 Pattern: GIF of a Bug Reproduction `gif_creator` records the user's Chrome, so the whole reproduction runs there: `gif_creator(action="start_recording", tabId=T)`, drive the page with claude-in-chrome (`navigate`, `find`, `computer`), then `stop_recording` and `export` with `download=true`. Browser Use cannot appear in that recording: its Chromium is headless and separate. --- ## 5. Browser Use-Only Fallback (When claude-in-chrome Unavailable) When `tabs_context_mcp` probe fails, use these fallback patterns: | Need | Browser Use-Only Approach | Limitation | |------|--------------------------|------------| | Console errors | The `browser_evaluate` error hook (§4.1) | Sees only errors after the hook is installed | | Network trace | `performance.getEntriesByType('resource')` via `browser_evaluate` (§4.2) | URL, status and timing; no request or response bodies | | JavaScript execution | `browser_evaluate(script="document.title")` | None — direct eval in the live page | | Computed styles | `browser_evaluate(script="getComputedStyle(document.querySelector('.x')).color")` | None | | Application state | `browser_evaluate` on the store (`window.__STORE__`), or `browser_extract_content` | Store must be reachable from `window` | ### Fallback Debugging Report When running Browser Use-only, be explicit about what you could and could not check: ```markdown ## Debugging Report (Browser Use-Only Mode) **Checked** (via Browser Use): - Visual state: screenshot before/after interaction - DOM state: interactive_elements - Page HTML: class names, inline styles, aria attributes - Computed CSS and application state, through `browser_evaluate` **Not Checked** (requires claude-in-chrome): - Console errors raised before the hook was installed (page load) - Request and response bodies **Recommendation**: Install the claude-in-chrome extension and re-run for complete analysis. ``` --- ## 6. Parallel Execution for Efficiency When using both tools in a hybrid workflow, run independent operations in parallel: ``` # SEQUENTIAL (slow): browser_click(...) # 1. Click browser_screenshot(...) # 2. Screenshot read_console_messages(...) # 3. Console read_network_requests(...) # 4. Network # PARALLEL (fast) — screenshot + console + network can all run after the click: browser_click(...) # 1. Click [then simultaneously]: browser_screenshot(...) # 2a. Visual state read_console_messages(...) # 2b. Console errors read_network_requests(...) # 2c. Network trace ``` Use Claude Code's parallel tool calling by making all three tool calls in the same response turn after the click action completes. --- ## 7. Key Decision: Which Tool Owns Navigation? In a hybrid workflow, Browser Use always owns navigation (page loads, clicks, form fills). claude-in-chrome observes passively — it reads the state of the current page without navigating itself. ``` Browser Use: DRIVER (navigates, clicks, types, extracts) claude-in-chrome: OBSERVER (reads console, network, runs JS queries) ``` Never use claude-in-chrome's `computer` tool for navigation if Browser Use is active — it could click into a different Chrome window than the one Browser Use is controlling.