Skip to content
CMMD Docs

Agent Browser

@cmmd-center/agent-browser is the shared browser-control package for CMMD systems. It gives agents a stable browser API while allowing each host app to choose the right browser surface: Playwright, CDP, Chrome extension transport, Electron, Tauri, or an embedded app-owned browser.

Use it when an app needs agent-controlled tabs, DOM snapshots, screenshots, locator actions, CUA/DOM-CUA actions, event streams, screenshot artifacts, or a shared browser session that both the user and the agent can observe.

Architecture

Section titled “Architecture”
Host app or agent runtime
  -> Agent Browser API
  -> backend adapter
  -> real browser surface
  -> event and artifact stores

The package keeps browser automation infrastructure separate from product orchestration. Forge, CMMD Center, and future private apps should consume the package through documented imports instead of copying source files or reaching into package internals.

Primary Surfaces

Section titled “Primary Surfaces”
  • createAgentBrowserRuntime: multi-backend runtime for browser/session lookup.
  • AgentBrowser: action-recording browser controller with safety policy support.
  • createHostBrowserBridge: app-facing session and command bridge for product UIs.
  • createBrowserHttpServer: local or service HTTP API for browser tools.
  • AgentBrowserHttpClient: typed client for agent tool routers.
  • Electron and Tauri adapters: IPC/event routing around the same host bridge.

Installation

Configure GitHub Packages, install the private package, and choose optional peers.

Runtime API

Create browser runtimes, open tabs, use locators, and record safe browser actions.

Host Bridge

Connect app-owned browser surfaces to agent sessions and UI event streams.

Forge Integration

Wire Forge through EnvironmentApi.browser without coupling Forge to package internals.

Section titled “Recommended Path”
  1. Install the private package from GitHub Packages.
  2. Import only the subpaths needed by the consuming app.
  3. Use the host bridge when the product owns the visible browser surface.
  4. Use the HTTP client/server when the browser controller runs as a local service.
  5. Keep product-specific state, permissions, identity, and UI outside the package.

For Forge, the correct direction is an EnvironmentApi.browser adapter backed by createHostBrowserBridge, not a source-copy into the Forge repository.