How Browsergent works

The core principle

LLM does reasoning, JS does acting. The model’s only browser tool is run_js. It never calls Chrome APIs or touches the DOM directly — it writes JavaScript, and the @pi-oxide/extension-js runtime turns that into typed page.* commands executed against the active tab.

The brain is a Rust state machine compiled to WASM (@pi-oxide/pi-host-web) running in a Web Worker. The LLM is called over the Anthropic Messages API. Side effects happen only through the typed command protocol.

That separation is the product thesis: an open-source browser agent can stay powerful without giving the model raw chrome.* access.

The agent loop

1. Observe — snapshot the active tab into a structured element list (refs, roles, labels).
2. Reason — send the task + history + snapshot to the LLM.
3. Act — the model returns JavaScript via run_js; the runtime dispatches page.* commands.
4. Observe again — the result feeds back into the next turn.
5. Stop — the model signals completion or you stop the run.

If you have used Claude Code, the rhythm will feel familiar: plan, tool call, observation, repeat. Browsergent applies that loop to a live Chrome tab instead of a local filesystem.

The command protocol

Every browser action is a typed BrowserCommand. A few examples:

type BrowserCommand =
  | { kind: "page.snapshot"; options?: SnapshotOptions }
  | { kind: "page.click";   refId: RefId }
  | { kind: "page.fill";    refId: RefId; text: string }
  | { kind: "page.select";  refId: RefId; value: string }
  | { kind: "page.scroll";  direction: "up" | "down" }
  | { kind: "page.goto";    url: string }
  | { kind: "page.wait";    ms: number };

Results are BrowserResult — an ok value or a typed error with a machine-readable code (e.g. E_STALE, E_NOT_FOUND). The model sees errors and recovers.

Configuration

Open Settings in the side panel and provide:

Compatible providers: Anthropic, DeepSeek (api.deepseek.com/anthropic), z.ai / GLM, or any endpoint implementing the Anthropic Messages API. Your key stays in the browser — it’s only ever sent to the base URL you configure.

Prefer the prebuilt Chrome extension zip if you just want to try the agent. Build from source when you want to inspect or modify the runtime.

Skills & files

• /skill:<name> activates a reusable skill at compose time — its instructions are folded into the prompt.
• @[file:name.ext] attaches a session file (stored in OPFS) into the task.
• The Files panel lets you upload, edit, and manage session files.

Known limitations

• Chrome only. MV3 side panel + content scripts; not ported to Firefox/Safari.
• Anthropic Messages API only. OpenAI-native function-calling isn’t supported on the wire.
• Drives your real tab (not a remote browser farm).
• Closing the side panel stops agent runs (by design). While the panel stays open, other sessions may keep running in the background of that panel (not on the chat frontend).
• Context-bound. Long sessions are compacted, but very long tasks may lose earlier detail.
• Single tab. The agent operates on one active tab at a time.
• Stale refIds. Snapshot refs (eNNN) are single-use within an observation — reusing one is the most common failure.

Experimental & safety

Browsergent is experimental. Its current philosophy is to expose everything the Chrome extension can access so we can learn the boundary of browser-agent capability. It may read page content, cookies, auth headers, and request/response metadata. Always review its actions and avoid using it on accounts where that level of access is unacceptable.

More context: FAQ · use cases.

Going deeper

• Source on GitHub
• Architecture (docs/ARCHITECTURE.md)
• Contributor conventions (AGENTS.md)
• Download the latest release →