Docs

Tools

Version 0.5.0 gives your agent 28 task-level tools; the next release adds 6 (marked). There is no "run this JavaScript" tool and there never will be.

Read the page

`browser_status`	Is the bridge up, is Chrome connected, which tab is the session on. Never starts Chrome.
`page_inspect`	A compact snapshot: controls with role, name, state and context (row, card, form, dialog), headings and visible text. Never field values. Page text is labelled untrusted.
`screenshot_capture`	A JPEG of the viewport or one element, on request only; saved on your computer.
`page_console`next release	Console messages, uncaught exceptions and the browser’s own messages, filtered by level or text.
`page_network`next release	The page’s requests with status, timing, size and failures. No headers, cookies or bodies.

Act exactly

`browser_navigate`	Go to an http(s) URL and wait until it is usable; reports redirects and HTTP errors.
`element_click`	Click exactly one element and report what changed. Ambiguous, hidden, disabled or covered targets are refused; risky clicks wait for your approval.
`field_fill`	Replace a text field’s content or set a checkbox or radio. Sensitive fields are refused and handed to you.
`select_option`	Pick a dropdown option by its exact label or value.
`browser_press_key`	One allowed key (Enter, Tab, Escape, arrows…). Enter that submits a form needs the same approval as its button.
`browser_scroll`	Scroll the page or one element, bounded.
`file_upload`next release	Attach one local file to a file input, after you approve that exact file. Secret-looking files are refused.
`browser_downloads`next release	What the browser downloaded during the session: name, size, path, still downloading or complete; can wait for one to finish.

Wait and hand over

`wait_for_state`	Wait for a URL, text or element to appear or disappear (up to 2 minutes, no fixed sleeps).
`task_pause`	Hand the tab to you with a message; the page shows “Your turn”.
`task_resume`	Wait for you to press Done, then look at the page again.

Tabs and profiles

`browser_new_tab`	Open a helper tab in the session’s group.
`browser_list_tabs`	The session’s tabs, with which is the main tab.
`browser_switch_tab`	Move to another tab of this session.
`browser_close_tab`	Close a helper tab and return to the main tab.
`browser_set_session_name`	Label the session’s tab group.
`browser_list_profiles`	The Chrome profiles that are connected.
`browser_select_profile`	Choose which profile (account) the session acts in.

Comment mode

`feedback_list`next release	Comment batches you sent from the side panel.
`feedback_get`next release	One batch: your notes, the elements, components and source files, and screenshots.

Workflows

`workflow_record`	Start, check, stop or discard recording this session’s steps.
`workflow_save`	Save a workflow from explicit steps.
`workflow_list`	Saved workflows with their parameters.
`workflow_get`	One workflow’s steps.
`workflow_run`	Replay a workflow with new values; every step gets the normal checks. Pro: many rows, background runs.
`workflow_status`	Pro: progress and the compact result of a background run.
`workflow_delete`	Delete a workflow.
`workflow_history`	Pro: versions and restore.
`workflow_reports`	Pro: local run reports.

Targets

Most tools take a target. Use what the page shows a person:

{ "role": "button", "name": "Add to cart", "within": "Trail Runner 2" }
{ "label": "Email address" }
{ "text": "Show more" }
{ "ref": "e14" }   // from page_inspect, short-lived

Matching is exact and never guesses: zero matches is TARGET_NOT_FOUND, more than one is TARGET_AMBIGUOUS with the candidates and the within that would tell them apart.

What every result looks like

{
  "ok": true,
  "state": "completed",          // or "needs_user", "failed"
  "summary": "Clicked button \"Add to cart\" in \"Trail Runner 2\"; the page changed.",
  "evidence": { "verified": true, "urlChanged": false, "dialogOpened": false },
  "nextAction": null,
  "error": null
}

Read state, summary and nextAction every time; they say what to do next.

Error codes you will see most

Code	Meaning	What to do
`TARGET_AMBIGUOUS`	More than one element matches	Add `within` from the candidates
`TARGET_NOT_FOUND`	Nothing matches (after waiting)	Read `likelyCause`; inspect the page
`USER_CONFIRMATION_REQUIRED`	Needs your approval	Approve in the side panel, then repeat with `approvalId`
`USER_ACTION_REQUIRED`	A password, code or CAPTCHA	Do it on the page, press Done
`SITE_ERROR`	The site showed its own error page	Retry later; nothing was assumed
`POLICY_BLOCKED`	Not allowed (site list, declined approval, secret file)	Choose another way
`PROFILE_REQUIRED`	Several Chrome profiles are connected	`browser_select_profile`
`TIMEOUT`	Waited as long as allowed	Allow more time (`timeoutMs`)