First browser session

This is the shortest useful loop. It deliberately avoids screenshots and JavaScript evaluation: read the page as text, act on an addressable control, wait for a condition, and verify the result.

Start the desktop app and connect hb-browser first.

1. Check the bridge

Call bridge_health with no arguments:

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"bridge_health","arguments":{}}}

Confirm that the app version is current and the input transport is cdp. cdp means input is sent as real browser input events and is not tied to the OS foreground window.

2. Navigate

{"name":"navigate_to","arguments":{"url":"https://news.ycombinator.com"}}

navigate_to returns after the page is ready enough to inspect and dismisses common cookie/GDPR overlays by default.

3. Read the page

{"name":"observe","arguments":{"as":"markdown","budget":12000}}

The response contains Markdown with inline [#id] marks and a paging cursor. If the page is longer than the budget, pass next_cursor back as cursor.

Use as:"text" for raw visible text, as:"ax" for the accessibility tree, or as:"som" for a numbered Set-of-Marks table. as:"components" returns decision-ready rows with the actions each component accepts.

4. Find a control

Prefer a semantic search over a hand-written selector:

{"name":"find","arguments":{"role":"link","name":"new","limit":5}}

find returns rows carrying mark ids. A mark id is re-resolved against the live DOM, so it survives layout shifts better than a CSS selector.

5. Act and wait in one call

{
  "name": "act",
  "arguments": {
    "mark_id": 12,
    "action": "click",
    "await_conditions": [
      {"type":"stable","target":"nodes","holdMs":400}
    ]
  }
}

act supports click, focus, hover, type, and press. For typing, pass text and optionally secret:true so the value is redacted from logs. Use clear_first:true when replacing a pre-filled value.

Do not use sleep. If the next step depends on readiness, use wait_for or act.await_conditions.

6. Read structured data

{"name":"extract","arguments":{"kind":"list","selector":".titleline"}}

Use kind:"table" for one table, kind:"tables" for all tables, kind:"app_data" for embedded JSON/state, and kind:"schema_org" for JSON-LD.

7. Handle a human-required page

If you hit a login, CAPTCHA, 2FA prompt, payment confirmation, or another blocker that should not be automated, call request_human_intervention with a short reason. The app alerts the operator and can bring the browser forward. The tool returns after the human resolves or cancels the request.

Minimal loop

bridge_health
  -> navigate_to
  -> observe(as:"markdown")
  -> find(role/name)
  -> act(mark_id, await_conditions)
  -> extract / observe

Read Browser MCP API for the full tool map and Error catalogue for recovery codes.