browser-use--browser-harness/interaction-skills/connection.md

Connection & Tab Visibility

The omnibox popup problem

When Chrome opens fresh, the only CDP type: "page" targets are chrome://inspect and chrome://omnibox-popup.top-chrome/ (a 1px invisible viewport). If the daemon attaches to the omnibox popup, all subsequent work — including new_tab() and goto_url() — happens on tabs that exist in CDP but may not be visible in the Chrome UI.

The daemon's attach_first_page() handles this by creating an about:blank tab when no real pages exist. If you still end up on an invisible tab, use switch_tab() which calls Target.activateTarget to bring the tab to front.

Startup sequence

1. Check if a daemon is already running with daemon_alive()
2. If stale sockets exist but daemon is dead, clean them up
3. List open tabs with list_tabs() to see what's available
4. ensure_real_tab() attaches to a real page
5. switch_tab(target_id) both attaches AND activates (brings to front)

if not daemon_alive():
    import os, ipc
    ipc.cleanup_endpoint("default")
    pid = ipc.pid_path("default")
    if pid.exists(): pid.unlink()
    ensure_daemon()

tabs = list_tabs()
for t in tabs:
    print(t["url"][:60])

tab = ensure_real_tab()

Bringing Chrome to front

If Chrome is behind other windows or on another desktop:

import subprocess
subprocess.run(["osascript", "-e", 'tell application "Google Chrome" to activate'])

Navigating

Prefer navigating an existing tab over new_tab(). Tabs created via CDP's Target.createTarget are visible but may open behind the active tab.

tab = ensure_real_tab()
goto_url("https://example.com")