Docs

How it works

Three pieces, all on your computer

There is no BrowserZap server. What your agent reads on a page goes to the agent you chose, under its terms.

Sessions and tabs

• Each agent conversation is a session with its own labelled tab group.
• The first tab is the session's main tab. Tabs it opens for side trips, and tabs a site opens from it, are helpers; the agent closes them with browser_close_tab and returns to the main tab.
• At most 5 tabs while it works, at most 3 once it has been idle for two minutes, and none after the agent ends (or after 30 seconds if its connection dropped and did not come back).
• A tab you are looking at or typing in is never closed, and a tab you drag out of the BrowserZap group becomes yours: the session can no longer see or touch it.
• A session can never see, switch to or close another session's tabs.

Exact targets, or nothing

The agent names what it wants by role and name ("button Add to cart"), optionally scoped: within: "Trail Runner 2". Look-alike controls are told apart by their row, card, form, section or dialog. When more than one element matches, nothing happens and the agent gets the candidates (TARGET_AMBIGUOUS). BrowserZap never clicks "the first one".

After every action it checks what actually changed and says so: the page navigated, a dialog opened, the field holds the value, or nothing happened.

You stay in control

Approvals

Clicks and Enter presses that submit, send, delete, post or pay wait for Approve once in the side panel. The element is ringed on the page while it waits. An approval is for that one action on that site, never a blanket permission.

Hand-offs

BrowserZap never types into password, one-time-code, card or government-ID fields, and never solves CAPTCHAs. When the agent reaches one, the page shows Your turn, focuses the field and rings it; you type, press Done, and the agent carries on. What you type is never seen or logged. An agent can also hand you a step on purpose (task_pause).

Stop

The pill at the top of the page and the switch in the side panel take the tab back at once. Neither can be pressed by the agent: both act only on your real clicks.

Waiting for slow sites

Before acting, BrowserZap lets the page settle (its own requests finish, at most a few seconds). An action waits for its target to appear and become usable, up to the time the agent allows (timeoutMs, up to two minutes). Every slow or failed step says why, as likelyCause: server_slow (naming the request), downloading, still_rendering, page_busy, server_error, site_error (the site's own error page) or not_on_page. There are no fixed sleeps.

Chrome opens itself

If Chrome is closed when your agent makes its first browser call, BrowserZap opens it with your usual profile and waits for the extension to connect. Turn this off with BROWSERZAP_AUTO_LAUNCH=0. It never starts a second Chrome when one is already running.

"BrowserZap started debugging this browser"

BrowserZap uses Chrome's debugger interface to click and type the way a person does, so Chrome shows that bar while it is attached. It is attached only to tabs an agent acts on, and lets go when the session ends, when you press Stop or are handed a step, and after a minute without agent actions. Pressing Cancel on the bar stops BrowserZap in that tab until you hand control back.

Background tabs

In a tab that is not in front, clicks are made inside the page instead of through Chrome's input pipeline (the result says clickVia: "dom"). A site that insists on a real user click needs the tab in front.