realbrowser

Files (8)

• SKILL.md
• commands.md · references/
• design-notes.md · references/
• workflows.md · references/
• realbrowser · scripts/
• realbrowser.cmd · scripts/
• realbrowser.mjs · scripts/
• realbrowser.ps1 · scripts/

SKILL.md (first lines)

# Realbrowser

Use `realbrowser` when a task needs the user's local browser state or a fast
managed browser. Target-first: resolve or create one tab target, then pass
`-t <label>` or `--handle` on every read, action, screenshot, console,
network, state, dialog, performance, download, or export command. Pointer
drag/drop is available through `action drag` with refs/selectors or viewport
CSS pixel coordinates.

The design is site-agnostic and OS-portable. Do not encode site names, UI
copy, or language-specific picker labels into the workflow. Use generic
browser state: profile/context, target, active root, refs, accessibility
labels, structural selectors, viewport/topmost checks, network entries,
downloads, artifacts. Site-specific CSS or text is only a last-mile selector
chosen after a scoped read proves it correct for the current page.

**Read the full SKILL.md once before the first browser action.** End to end
(no `head`/`tail`/`sed -n '1,N p'` slices). Efficiency Rules and Operating
Loop contain non-negotiable rules whose absence drives cost and failure loops.

## Fast Start

CLI at `scripts/realbrowser` (Node: `scripts/realbrowser.mjs`). Set
`REALBROWSER="<skill-directory>/scripts/realbrowser"` (POSIX) or
`$Realbrowser = Join-Path "<skill-directory>" "scripts\realbrowser.ps1"`
(PowerShell).

```bash
# Anonymous (isolated temp state, not visible Incognito)
"$REALBROWSER" tab ensure https://example.com --anonymous --session check --label page --background
"$REALBROWSER" read observe -t page --anonymous --session check

# Signed-in profile or existing Chrome
"$REALBROWSER" profile list --active
"$REALBROWSER" tab ensure <url> --profile chrome:Default --label app --background
"$REALBROWSER" read observe -t app --profile chrome:Default

# Default context for repeated work; owner scoping for parallel sessions
"$REALBROWSER" session use profile:chrome:Default
export REALBROWSER_OWNER=my-project   # parallel sessions
"$REALBROWSER" tab ensure <url> --label app --background
```

Visible Incognito only when the user asks for a visible Incognito window: add
`--incognito` (or `--private`) with `--front`.

**Pick by URL stability:**

- **Stable-URL sites** (search engines, wikis, code hosts, news, docs):
  deep-link FIRST. Verify with `read observe`; fall back to homepage UI on
  "404"/"Not Found"/"error"/"Pardon".
- **Stateful SPAs** (URL not source of truth — content hydrated from
  session/cookie state or form-driven): **homepage + UI FIRST.** Constructed
  deep-links frequently 404; the probe wastes 20-40s. Skip unless you have
  evidence (bookmark, prior-session success in this Chrome).

Stateful-SPA cold-start (canonical 5 cmds; typical 2-5 min, varies with bot
defenses):

```bash
"$REALBROWSER" tab ensure <homepage> --profile chrome:Default --label app --background
"$REALBROWSER" read tree -t app -i -c                    # find c<n> chips + HINT line
"$REALBROWSER" action click -t app c1                    # chip pre-fills form (if one matches)
"$REALBROWSER" action submit -t app --text "Search"      # exact visible label (localize as needed)
"$REALBROWSER" wait ready -t app --visual-stable --timeout 30000
```

No matching chip? Picker UI fallback in `references/workflows.md`.

**Don't add `--allow-browser-scope-target` reflexively.** Tabs created via
`tab ensure --profile` are profile-proven — later `-t app` works without it.
Only needed when claiming an existing user tab on a browser-scoped CDP
endpoint (rare).

Creation = `tab ensure`/`tab new`; navigation = `tab navigate <t> <url>`;
reads/actions require a target. `profile list` reports CDP scope (`profile`
= one profile, `browser` = inspect-only for existing tabs). `--background`
uses only background-safe paths. Running browser-scoped profiles are never
OS-launched in background; use `--front` for explicit visual handoff. Mutating
commands claim a target lease — don't navigate/click/close/focus/reload/download a leased target
without `--take-lease` or explicit handoff. Full/responsive/device/annotated
screenshots also require the lease.

## Tab Ownership And Task Registry

Each invocation has a *task*. Agent tabs tracked per-task, separate from
user tabs. `tab list --mine` shows only this task's tabs; `tab list` shows
everything with `mine` / `user` / `other-agent` column.

**Same task + same origin = same tab.** A second `tab ensure
<same-origin-url>` reuses the original; passing a new label aliases the old.
If the new label points elsewhere, realbrowser refuses with
`duplicate_task_origin` and lists recovery commands verbatim. **USE the
existing handle** — do not invent a new label. Mutating commands
(`tab navigate`, `tab close`) refuse user-owned tabs by default; opt in with
`tab select --take-lease` or `tab navigate --allow-user-tab-mutation`.

End of task: `tab done` marks complete, leaves open (safe default). Add
`--close` or use `tab close --mine` to close only agent tabs.

Failure modes the registry prevents: inventing `app2`/`app3` after a click
fails; closing one of the user's tabs thinking it was the agent's; losing
track of which tab is owned.

`background_create_unavailable` on `tab ensure --background`? Do not switch to
anonymous or another profile unless the user approves. Use an existing proven
tab, ask for `--front`, or ask for a one-shot profile relaunch if CDP is locked.

**User tab in conflicting state.** If `tab list <site>` shows a user tab
already on a page that doesn't match what the task needs (e.g. user is
mid-flow on a stateful SPA), don't `--take-lease` and don't probe with a
deep-link — for stateful SPAs the deep-link will 404 or 500. Open a
fresh agent tab via the homepage with `tab ensure <homepage> --force-new
--label <new> --profile <p> --background`. The new tab carries its own
session-scoped state from the same cookies, leaving the user's tab untouched.

## Operating Loop

1. **Classify scope:** existing tab, signed-in profile, anonymous, debug,

From darkamenosa/pi-setup, Apache-2.0.

More from darkamenosa/pi-setup