Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Tools

Reference for the six browser tools agents call.
Every tool returns the same envelope: { ok: true, ...payload } on success, or { ok: false, error } for model-fixable failures (unknown session ID, thrown Playwright code). Errors include a next step when possible. Host misconfiguration (missing API keys) and domain policy violations throw instead of returning { ok: false }.

browser_open

Open a new browser session through the configured provider. Optionally opens url at session create (providers that support preload) or after connect. Returns a sessionId for later tools.
path urlstring
Optional start URL for the session. Use a full https:// URL, or omit url and navigate with browser_exec via await page.goto(...). Kernel and Libretto Cloud can open this before CDP attach; other providers navigate after connect.
path authProfilestring | false
Named browser state for signed-in sessions. On supported providers, omit to use default, or pass false for a session with no saved state. See Auth profiles.
Success: { ok: true, sessionId }.
If navigation fails, the session is closed and the tool returns { ok: false, error } so the agent can open again.

browser_connect

Attach to an already-running browser via its CDP websocket URL. Returns a session ID like browser_open, but browser_close detaches without killing the externally managed browser.
path cdpUrlstringrequired
CDP websocket URL, for example ws://127.0.0.1:9222/devtools/browser/....
Success: { ok: true, sessionId }.
Use this for Electron apps or any Chromium already started with remote debugging. See CDP attach.

browser_exec

Run Playwright code against an open session. The code runs as the body of a fresh async function — use return to produce a result.
Nothing persists between calls (no variables, no imports). The browser is the only state. In scope: page, context, browser. TypeScript is fine (stripped with Sucrase). console.log / console.error are captured as stdout / stderr.
Results are JSON-serialized when possible; values that cannot be serialized become strings.
path sessionIdstringrequired
Session ID from browser_open or browser_connect.
path codestringrequired
Playwright/TypeScript body to run. Example: return await page.title().
path pageIdstring
Optional page ID from browser_status. Defaults to the most recently opened tab.
path diffSnapshotboolean
When true, capture a compact accessibility-tree baseline before the exec, wait for the page to settle after success, then return snapshotDiff against a fresh after-tree. Use for exploratory mutations when you do not know what will change. Defaults to off.
path timeoutMsnumber
Max wall-clock time to wait for this exec in milliseconds. Defaults to 10000 (10 seconds). A timeout returns { ok: false, error } and stops waiting — it does not cancel in-flight Playwright work. Raise timeoutMs, simplify the code, or call browser_close then browser_open if the session may still be running the timed-out work.
Success:
{
  ok: true,
  result: unknown,
  stdout: string,
  stderr: string,
  snapshotDiff: string, // set when diffSnapshot is true; empty when off or unchanged
}
Code-level failures return { ok: false, error, stdout?, stderr? } — fix the code and retry.

Snapshot vs snapshotDiff

  • Call browser_snapshot to orient on a full accessibility tree before interacting, or to verify state after a change.
  • Pass diffSnapshot: true on browser_exec when you want a page-change diff after an exploratory mutation. Prefer that before taking another full snapshot when you do not know what changed.

browser_snapshot

Capture the current page as a compact text accessibility tree. Nodes include ref handles (for example l7) so the agent can refer to structure while writing Playwright locators in browser_exec.
path sessionIdstringrequired
Session ID from browser_open or browser_connect.
path screenshotboolean
When true, also return a PNG as { base64, mimeType: "image/png" }. Framework adapters (AI SDK, Pi) can surface that image to the model.
path pageIdstring
Optional page ID from browser_status. Defaults to the most recently opened tab.
Success: { ok: true, tree, screenshot? }.

browser_status

Inspect open sessions and pages. Start here when the agent is unsure which tab to target.
ArgsReturns
(none){ ok: true, sessions } — each session lists sessionId, provider, pages, and authProfile when set
sessionId{ ok: true, pages } for that session
sessionId + pageIdPage detail: url, title, viewport, active, readyState
path sessionIdstring
Session ID from browser_open or browser_connect.
path pageIdstring
Page ID from a prior browser_status call. Requires sessionId.

browser_close

Close a session by ID. For provider-owned sessions this releases the remote browser. For browser_connect sessions it detaches without killing the external browser.
path sessionIdstringrequired
Session ID to close.
Success: { ok: true }.
Calling dispose() on the toolkit closes every session that toolkit still owns.
Powered byHolocron