Open Web Bridge Browser Control

owb (Open Web Bridge) — driving the user's real browser

owb, the Open Web Bridge CLI, operates the browser the user is using right now: their logged-in accounts, their settings, their open tabs. That is why you can reach content that exists only behind a login, and complete actions that require an identity.

For the same reason, every step lands on a real person's account and they may be using this browser beside you. Read freely; ask before changing anything; open pages in new tabs so you don't take over what they are looking at.

How to use this document

In a hurry? Read "Before you start" → "The shape of a task" → "The core loop". This file is the trunk; five reference files live in references/, read on demand:

For anything not documented here: this file cannot cover all 80 commands. owb help lists all 16 groups, owb help <group> expands one, and owb call <tool> --args '<json>' calls any underlying tool directly. Don't guess command names — look them up.

Before you start

owb          # self-check

• ✓ daemon + ✓ extension connected → go
• ✗ extension not connected → stop and tell the user to click the extension icon in their toolbar and check its status. Hammering the tools will only produce NO_EXTENSION forever.
• Command not found → npm i -g open-web-bridge, then owb setup
• [owb] daemon not running, starting it… on stderr during the first command is not an error — the CLI is starting the daemon. Wait for it to connect; don't report it as a fault.

The self-check reports one of two modes: local (default; daemon and browser on one machine) and relay (browser on the user's machine, agent elsewhere, paired through a public relay). Local mode needs no configuration. Everything about relay mode — setup, capability differences, troubleshooting — is in references/relay.md.

The shape of a task

Read this section first. Individual commands are documented below, but if you don't know where a piece of work begins and ends, you will pile dozens of unrelated tabs into one place and have to close them one by one — measured: 25 tabs in a single session.

For multi-step work (anything beyond opening one page for a single look), the four steps are:

owb task begin "competitor pricing research"  # ① open a task: creates a task group
owb open <url> --new-tab true                 # ② work: new tabs join that group
owb page / click / fill / wait                #    …normal operations
owb task end                                  # ③ close out: stop recording, archive, report tabs
owb tab close-group                           # ④ clean up: close every tab from this task

Each step earns its place:

⚠️ task end does not close tabs. It archives, clears task context and reports which tabIds were produced, but the pages stay open (sometimes you do want to keep the results visible). To actually clean up you must also run tab close-group. The word "end" does not mean what you would assume.

tab close-group closes the "OWB scratch" group plus every "task:" group; handoff groups are kept by default (that is the user's live workspace). To include them, pass --args '{"include_handoff":true}'. To close only the scratch group and keep task groups, pass --args '{"include_tasks":false}'.

A one-off look needs no task — owb open <url> --new-tab true is enough, and the tab lands in the "OWB scratch" group. The taskHint in the result tells you how many tabs are sitting there; a rising number is the signal to task begin.

⚠️ Losing task context has two consequences. Chrome reclaims idle MV3 service workers, and owb reload-ext or a daemon restart does the same; afterwards currentTask is gone. (1) The group survives but new tabs stop joining it and scatter into the scratch group — the symptom is tabs wandering off mid-task; just run task begin again (same title reuses the group). (2) task end reports NO_TASK and the task is never archived — though tab close-group still works, since it matches by group name. If you need the archive, confirm owb daemon-status still shows current_task before closing out.

🚨 Running several OWB missions at once (multiple agents/processes driving the same browser concurrently) is a different failure mode from the one above, and it's not idle recycling — it's contention. The daemon tracks "the current task" as one shared value, not one per caller. Whichever task begin runs last holds it; every earlier task's plain task end then either raises NO_TASK (if the pointer's since gone null) or — worse — returns ok:true while archiving someone else's task, with no error to catch it. New tabs opened in between two task begin calls get grouped under whichever task happened to be "current" at that exact moment, not the one that opened them — so tabs from different parallel missions end up scattered across each other's groups. Measured: 5 concurrent tasks, 5/5 hit this. What's fixed, and what still isn't:

• task begin returns task_id — hold onto it, and pass it back as task end --task-id <id> instead of a bare task end. That reliably archives your task's metadata even if the pointer has moved on (the result carries ended_stale: true when it wasn't the live one) — but it does not retroactively fix which group your tabs already landed in.
• task end's cleanup no longer reaches outside your task: it re-confirms ownership with the extension by task id before touching anything, and stops only the recorders on your task's tabs rather than every recorder in the browser. Tab ownership is tracked per task as you navigate, so it covers tabs you reused as well as ones you opened with --new-tab. If a recorder is running on a tab that genuinely isn't yours, task end leaves it alone and names it in recorders_not_archived — it is never silently dropped, but you do have to har save it yourself.
• Still unfixed — skip tab close-group when other missions might be running. It closes by group name, and group membership is exactly what's unreliable under concurrency — it can just as easily close another mission's live tabs as your own. Track the tabIds you actually opened yourself and owb tab close --tab <id> each one individually (or batch them with owb seq) instead.
• ⚠️ task end's result has group.cleared: true — that means the task context was cleared, not that any tab was closed (tabs_closed: false says so explicitly). Closing tabs is always a separate step.

Your tabs and the user's tabs

owb runs inside the browser the user is using right now, so there are always two populations of tabs. Confusing them means closing the user's work at best, and reading the wrong page without noticing at worst.

Guardrail: owb tab close only permits the first three. Closing an ungrouped tab raises FORBIDDEN. That is protection, not a fault — when you hit it, first ask yourself "did I grab the wrong tabId?" rather than reaching for --force true.

⚠️ Never assume a tab is still the one you left there. The user may have navigated it elsewhere, and other automation may reuse it. Measured: after a gap, an old tabId used with eval to read a chess position returned a completely unrelated search results page — every command "succeeded" and every piece of data was wrong, which is far harder to catch than an error. Before reusing a tabId across turns, confirm with owb tab list (or owb tab find --url-pattern "<regex>"), or just open a fresh one.

The core loop: look → point → act

owb page turns the page into a numbered list, one @eN per interactive element, so you act by number instead of guessing CSS selectors.

owb open https://example.com --new-tab true   # ← don't skip this, see below
owb page                      # @e1 @e2 … each with role, text, href
owb fill @e3 "keyword"
owb keys --keys Enter         # submit with a real Enter key
owb wait --text "results"     # wait for readiness, never sleep
owb click @e5

⚠️ --new-tab true is not optional. Skipping it navigates the user's current tab away from what they were reading. Only skip it when you specifically intend to operate on the current page.

💡 --active false opens the new tab in the background, so you don't steal their screen focus. Especially worth it when opening several pages to read.

🚨 But a background tab is not the active tab, so every later command needs an explicit --tab. Without --tab, page/eval/wait/click act on the active tab — which is not the one you just opened; it is the page the user is looking at. Skipping --tab does not produce an error, it produces a silent read of the user's private page treated as your task data (measured: open returned tabId A, and the very next page read the user's internal admin system).

owb open <url> --new-tab true --active false   # → note the tabId in the result
owb page --tab <that tabId>                    # ← carry it on every command

The open result includes backgroundTabHint naming the tabId to use. With an active task, forgetting --tab raises AMBIGUOUS_TAB — but without an active task there is no such protection, which is one more reason to task begin for multi-step work.

Keyboard: owb keys

fill only sets a value; it produces no key events. Submitting a search, dismissing a dialog, or using a shortcut all require keys:

owb keys --keys Enter                 # submit
owb keys --keys Escape                # close a dialog / exit fullscreen
owb keys --keys "ArrowDown ArrowDown Enter"   # space-separated, pressed in order
owb keys --keys "Ctrl+a"              # modifiers (Ctrl|Alt|Shift|Meta)
owb keys --text "typed text"          # insertText — produces no per-key events

⚠️ --text and --keys are mutually exclusive; passing both raises BAD_ARGS. To type and then press Enter, call it twice. Named keys and the full list are in references/commands.md.

Reading a snapshot

One line carries more than you might expect:

@e17 link "Technology" href=https://example.com/lists/65.html
@e2  textbox "Search models, datasets, users..."
@e48 textbox "< 1B 6B 12B" type=range
@e86 textbox "Filter by name" type=search
      checkbox "Subscribe to newsletter" checked
      link "Next page" href=... disabled

• Links always carry href — even when the name is empty, the URL tells you where it goes. This is an underrated fallback.
• Inputs carry type= (range/search/date/email…), and required, checked, disabled are all marked; <select> lists its values=[...].
• iframes lists the page's iframes and shadowRoots reports how much content comes from Web Components (snapshots descend into open shadow roots). To act inside an iframe: owb frames for the list, then owb eval --frame-pattern <regex>; contextId:null frames are cross-origin and cannot be evaluated.

⚠️ Refs expire

After a navigation or re-render, old numbers stop working and report REF_STALE. Run owb page again for fresh numbers — don't retry with the old ones.

⚠️ Notice when a snapshot was truncated

Roughly a quarter of sites hit the cap on the first screen (default 20000 chars / 400 nodes); the result then carries truncated: true and omittedNodes. Either raise the cap or narrow the scope:

owb page --max-nodes 1200 --max-chars 60000    # full detail (max-nodes caps at 2000)
owb page --mode article                         # article body only

Dense text-heavy sites hit the cap especially easily.

Saving tokens: incremental snapshots

After acting, do not re-read the whole page. Use --since-last to get only what changed:

owb fill @e86 "qwen3"
owb wait --network-idle true
owb page --since-last true
# → added=54 changed=6 removed=62 unchanged=340

Only 54 new entries enter your context instead of 400 elements. Whether a long session survives comes down to this one habit.

Three ways to read — pick the right one

💡 All three modes also expose text as an alias for that mode's main field, so scripts can read text without switching field names per mode.

⚠️ List pages and forum front pages return 0 characters in article mode — they have no "article body"; that is correct, not a failure. The reason field on an empty result explains why.

💡 Body reads as 0 characters while hiddenContentNote says the DOM holds thousands → switch to --mode text, which falls back to textContent automatically and marks the result textSource: "textContent-fallback" (measured: article 3 chars → text 25161). ⚠️ That fallback is DOM order, not visual order, and includes navigation chrome — fine for reading, not for judging layout. Why it happens: references/field-notes.md, symptom C.

💡 Body nearly empty and the DOM really is empty too (title renders, content doesn't — typical of client-side-rendered pages): the result carries a _hint that says which case you are in — still loading (→ wait --network-idle), a bot-check interstitial (→ handoff), an SPA shell whose data never arrived (→ check net list), or content behind interaction / inside an iframe. Follow the hint instead of re-reading in a loop.

Waiting and timeouts

owb wait --selector ".result-item"      # wait for an element
owb wait --text "128 results"           # wait for text
owb wait --url-pattern "search"         # wait for navigation
owb wait --network-idle true            # wait for requests to settle (best for SPAs)

Exactly one of the four; passing two raises BAD_ARGS. Never sleep.

⚠️ On SPAs, open returning loadCompleted:true does not mean the content has rendered. Measured: one news site returned complete in 2.3 seconds with only 6 elements in the snapshot. When a snapshot looks suspiciously small, run owb wait --network-idle true and read again.

⚠️ Three layers of timeout — the most common source of wasted effort

• ⚠️ --timeout is not forwarded to the tool; it only relaxes the CLI's wait for a result. To let owb open wait more than 30 seconds on a slow site, write --timeout-ms 60000. Writing --timeout 60 does nothing.
• ⚠️ owb wait waits only 10 seconds by default, not indefinitely. For slow sites pass --timeout-ms 60000 explicitly.
• ⚠️ When tool-internal waiting exceeds 110 seconds you must also raise --timeout, or you hit the 120-second envelope first (ctl call timeout). wait-user is the one exception — the CLI relaxes it automatically.
• ⚠️ The 30 seconds that owb shot and owb eval can hit is the CDP hard limit; no argument helps. That is a different problem — see the Reality check table.

Common tasks

Longer recipes — structured extraction, live-data provenance, click vs click --mouse, dragging and canvas, rich text editors (ProseMirror-style), speeding up slow sites, downloads and uploads, debugging a site, responsive/accessibility audits, saving logins, recording flows, high-frequency step sequences (owb seq) — live in references/recipes.md. The few below are either used constantly or easy to get wrong.

Reading content that requires a login

The user's session is already in the browser, so just open it:

owb open <article URL> --new-tab true
owb page --mode article

For multiple pages: owb page to find the "next page" number → owb click @eN → owb wait → read again.

Reading comment threads and forum discussions

Comments and replies are not article body — --mode article doesn't recognize them and returns 0 characters, while the default snapshot only draws structure (who posted how long ago, upvote/reply links) and never shows what was said. Skip snapshot and article for threads; go straight to text:

owb open https://news.ycombinator.com/item?id=<id> --new-tab true
owb page --mode text        # measured: the whole thread is here; snapshot/article are empty

The same applies to Reddit posts, forum replies, and Q&A answer lists.

Cross-site synthesis and verification

The genuinely valuable pattern: pull a repository link from a paper page → open GitHub to read stars and recent commits → conclude whether the code actually exists and whether the project is alive. That conclusion requires more than one site; no single-site scrape produces it. Pair it with task begin to keep the whole chain in one group.