BrowserForce — Your Real Chrome Browser

BrowserForce gives you the user's actual Chrome browser — all their logins, cookies, and extensions already active. No headless browser, no fresh profiles.

Prerequisites

The user must have:

1. BrowserForce Chrome extension installed and connected (green icon)
2. The relay auto-starts on first command — no manual step needed

Check with: browserforce status

Use commands first

Session commands share one persistent browser session (including the active tab and snapshot refs) across CLI calls. The same command language powers the MCP browserforce tool:

browserforce tabs                # List tabs: stable t<N> handles + names
browserforce use t2              # Switch the active tab
browserforce open <url> --as docs  # Open a new tab, optionally named
browserforce snapshot            # Accessibility tree + @eN refs
browserforce click @e2           # Act on a ref from the last snapshot
browserforce screenshot [n]      # Screenshot tab n (PNG to stdout)
browserforce -e "<code>"         # Raw Playwright JavaScript (one-shot escape hatch)

Use -e only when the command layer cannot express the task.

Put your name on the cursor

If the user has the ghost cursor on, the cursor shows which agent is driving — but only if you say who you are. Export this before running any command:

export BROWSERFORCE_AGENT_NAME="Claude"

Max 24 characters, allowed: A-Z a-z 0-9 space . _ -. Anything else is stripped (not rejected), whitespace runs collapse, longer names are truncated, and a name that sanitizes to nothing shows no label at all. Pick a name that survives intact.

Sharing the machine with other agents? Also export a distinct BF_SESSIOND_LOCK_PATH=/tmp/bf-<your-name>.json. One session daemon serves every CLI caller over a single connection and takes its name from whichever environment started it, so without your own daemon your clicks are attributed to the first agent's name.

Core Workflow: Observe → Act → Observe

browserforce open https://example.com/login
browserforce snapshot                      # find the email/password/submit refs
browserforce fill @e3 "user@example.com"
browserforce fill @e4 "hunter2"
browserforce click @e5
browserforce wait url "**/dashboard"
browserforce snapshot                      # verify the result

Refs go stale the moment the page changes — always re-snapshot before the next ref interaction.

Multi-tab work

browserforce open https://docs.example.com --as docs
browserforce open https://app.example.com --as app
browserforce snapshot --tab app            # read app without switching tabs
browserforce click @e2 --tab app
browserforce use docs                      # or switch the active tab

Target tabs by stable handle (t2) or name — never by list position. Tab names are unique; pass --replace only when you intentionally want to move a name to another tab.

Stable handles and names persist for the lifetime of the session; use browserforce tabs to discover them. A handle survives the idle reconnect; it is invalidated only by reset.

Handing browser work to a subagent

Subagents share your browser session automatically — one daemon per machine, so they see your tabs, your logins and your snapshot refs with no setup. Paste one of these into the subagent's prompt.

Sequential subagents. They share your active tab:

Browser: use the browserforce CLI. It is already connected to the user's real Chrome and shares this session's tabs. Run browserforce tabs to see them, browserforce use <handle> to pick one, then snapshot / click @eN / fill @eN <text>.

Parallel subagents. Give each one its own id, and its active tab is its own:

Browser: use the browserforce CLI with BROWSERFORCE_CLIENT_ID=<your-name> exported. You share the session's tabs and logins with the other agents, but your active tab is your own — use and open will not move theirs.

For a client that cannot set the id, pin every run instead: pass --tab <handle> on snapshot, click, fill, type, press, hover, wait, get and eval, and do not run use or open. tabs needs no --tab and does not accept one.

A subagent that should keep its own session. Give it its own daemon:

Browser: use the browserforce CLI with BF_SESSIOND_LOCK_PATH=/tmp/bf-<name>.json and BROWSERFORCE_CDP_CLIENT_LABEL=<name> exported. You get your own session state and your own Chrome window for tabs you create.

That last one separates session state and where new tabs open. It is not a sandbox: every BrowserForce client can see and drive every tab in the browser. If a tab must not be touched, do not delegate work that reaches it.

Handles (t<N>) are stable for the session, so a handle you pass to a subagent still names the same tab when it runs.

Command reference

browserforce snapshot [--tab docs] [--selector "#main"] [--search "login"] [--interactive]
browserforce hover @e3                         # Hover a ref
browserforce type @e2 "more text"              # Type without clearing
browserforce press Enter                        # Send a key
browserforce wait text "Saved"                  # Wait for text
browserforce wait url "**/dashboard"            # Wait for a URL glob
browserforce wait load domcontentloaded          # Wait for a load state
browserforce wait fn "window.ready === true"    # Wait for a JavaScript predicate
browserforce get url|title                      # Read the current page
browserforce get text|html @e5                  # Read a referenced element
browserforce eval --stdin                       # Run piped JS in the persistent session
browserforce rename docs api-docs                # Rename a tab
browserforce forget api-docs                     # Remove a tab name
browserforce run "click @e2 --tab docs"         # Run a command string

Refs accept @e1, e1, or ref=e1. Ref/read commands accept --tab <handle|name|text> without changing the active tab. eval uses the same guarded boundary as MCP exec; it exposes page, context, state, and snapshot(), and state persists between session commands. Add --json for machine-readable command results.

Extract data

browserforce get url                       # current URL
browserforce get text @e5                  # text content of a ref
browserforce get html @e5                  # innerHTML of a ref
echo "return await page.title();" | browserforce eval --stdin

One-shot -e (escape hatch)

Each browserforce -e call is independent (state does NOT persist between -e calls). Do everything in a single snippet:

browserforce -e "
  state.page = await context.newPage();
  await state.page.goto('https://example.com');
  await waitForPageLoad();
  return await snapshot();
"

Rules

1. snapshot over screenshot — snapshot returns text (fast, cheap); use a screenshot only for visual layout verification.
2. Re-snapshot after every page change — refs go stale immediately.
3. Don't navigate existing tabs — open your own via browserforce open.
4. Commands over -e — reach for raw Playwright only when the command layer cannot express the task.
5. Command errors teach the next step — stale ref → re-snapshot; unknown tab → browserforce tabs. Fix and retry.
6. Backend fallback is visible — auto uses real Chrome when the extension is connected and warns if it falls back to managed Chrome; use --real to fail instead of falling back.

A rendered page is not proof

The tab you read may have been open, and logged in, before your change — the page can render correctly for reasons that have nothing to do with it. Corroborate a browser result against independent evidence (a fresh navigation, a server log, a test) before calling a flow verified.

Troubleshooting

Error Recovery

• "Unknown ref": the page changed — browserforce snapshot, use the new refs
• "No tab named …": browserforce tabs, target a listed handle or name
• Connection lost: user must check browserforce status
• No tabs: browserforce open https://example.com
• Element not found: browserforce snapshot --search "button"

Important

This is the user's REAL browser. Be respectful:

• Don't close tabs you didn't open
• Don't navigate tabs you didn't create
• Don't modify browser settings or stored data