Coming from agent-browser

KMPwright adapts agent-browser to a Kotlin library. There are two ways to use what you know:

1. page.runCommand("…") accepts agent-browser command lines for the core agent loop (open, snapshot, act on @e refs, read, wait). Hand it to an LLM as a single tool.
2. The typed Kotlin API covers almost every agent-browser command, including the ones runCommand does not parse (network, tabs, state, recording, diffs and more).

// agent-browser                       // KMPwright
// agent-browser open example.com      page.runCommand("open example.com")
// agent-browser snapshot -i           page.runCommand("snapshot -i")
// agent-browser click @e2             page.runCommand("click @e2")
//                                     // or, typed:
//                                     page.locator("@e2").click()

The comparison was made against agent-browser 0.39.0. The machine-readable inventory is docs/compatibility/agent-browser-compatibility.json.

Out of scopeCopy Anchor Link

KMPwright is a library you embed. These agent-browser parts are intentionally not included:

• the CLI executable and its daemon (sessions, --session, --namespace, --idle-timeout, --json, batch, get cdp-url),
• the MCP stdio server (mcp),
• executable plugins (plugin, --plugins),
• the chat gateway (chat, --model),
• installation management (install, upgrade, doctor, skills).

Your Kotlin code owns browser and page lifetimes, output formatting and tool wiring instead.

runCommand: the supported grammarCopy Anchor Link

page.runCommand(command) parses one command line. Arguments are split on whitespace; single or double quotes group words; a backslash escapes the next character. It returns AgentCommandResult(command, output, snapshot, screenshot): output is plain text for a person or a model; snapshot and screenshot carry structured data when the command produces it. Unknown or malformed commands throw KmpwrightException with a usage hint.

A target is a snapshot ref (@e3, e3, ref=e3) or any selector that page.locator accepts: CSS, text=Save, role=button[name="Save"], label=Email, xpath=….

NavigationCopy Anchor Link

ObserveCopy Anchor Link

snapshot output is the snapshot text and result.snapshot holds the Snapshot. The text uses agent-browser's format, one element per line; elements that can be targeted start with their ref, children are indented two spaces, and page text is printed as JSON string literals:

@e1 [heading] "Example Domain" [level=1]
@e2 [button] "Submit"
@e3 [input type="email"] placeholder="Email"
@e4 [checkbox] "Remember me" [checked]
@e5 [link] "Learn more" url="https://example.com/more"

• -i prints only elements with refs (buttons, links, inputs, iframes, and named headings and landmarks) as a flat list; refs nested inside a ref, such as iframe content, are indented.
• -u adds each link's resolved href as url="…".
• -c drops structural nodes that contain no refs or values.
• -C also includes elements that are interactive only through cursor: pointer or onclick.
• With no output, the text is (no interactive elements) for -i and (empty page) otherwise.

screenshot output is Screenshot <width>×<height>, followed with --annotate by one @eN role: name line per drawn ref; the image is in result.screenshot. No path argument: write result.screenshot!!.bytes yourself.

ActCopy Anchor Link

QueryCopy Anchor Link

WaitCopy Anchor Link

Every wait form accepts --timeout <ms>. The default is 10 000 ms for runCommand waits (not the configured TimeoutConfig). Put the target or milliseconds first: wait @e3 --timeout 5000.

PageCopy Anchor Link

Helpers on AgentCommands: HELP (the reference text, suitable for a tool description), tokenize(command) and normalizeUrl(input).

Not parsed by runCommandCopy Anchor Link

These agent-browser commands are not part of the runCommand grammar. Use the typed API (next section) and, if your agent needs them, expose them as additional tools: find, upload, pdf, read, keyboard, mouse, clipboard, set …, network …, tab, window, frame, dialog, diff …, trace, profiler, pushstate, react, vitals, addinitscript, removeinitscript, auth, state, stream, a11y, webmcp, record, cookies set, storage … set. runCommand also has no --json output mode.

Every command, mapped to the Kotlin APICopy Anchor Link

Status comes from the compatibility inventory: Supported means the documented core behavior has a public entry point; Partial means one exists but backend, lifecycle, output or option semantics differ; Unsupported means there is none.

Navigation and interactionCopy Anchor Link

Observation and contentCopy Anchor Link

Browser settingsCopy Anchor Link

Network, storage and stateCopy Anchor Link

Tabs, windows and recordingCopy Anchor Link

Unsupported commandsCopy Anchor Link

Global flagsCopy Anchor Link

Behavior differencesCopy Anchor Link

• Refs are per snapshot. A ref resolves against the latest snapshot of that page. page.locator("@e3") does not take a new snapshot for you; take one after the page changes.
• Errors are exceptions. runCommand throws KmpwrightException (or KmpwrightTimeoutException) instead of printing an error and exiting. Catch it and return the message to the model.
• No implicit session. There is no daemon keeping a browser alive between calls. Keep your Browser and Page for as long as the agent runs, and close them when done.
• Capabilities vary by backend. The same command can be Supported on JVM and Partial or Unsupported on a mobile WebView. Check page.capabilities() and its notes; see Capabilities.
• Security flags are APIs. See Security for setAllowedDomains, action policies, confirmation callbacks and content boundaries.