woniu9524/open-web-bridge/owb

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: