Browser Extension System
Relevant source files
The following files were used as context for generating this wiki page:
The Browser Extension System in OpenWork provides a robust mechanism for agents to interact with web content using a built-in browser instance controlled via the Chrome DevTools Protocol (CDP). This system transitions from legacy, static Model Context Protocol (MCP) implementations to a dynamic plugin-based architecture, primarily powered by the opencode-chrome-devtools plugin.
The system integrates directly with the user interface through the Composer, providing "extension chips" for quick prompting, and a dedicated Extensions panel for management. It ensures high technical accuracy by requiring specific CDP endpoints (typically on port 9223 or 9222) for tool execution.
Sources: evals/browser-extension-flows.md:1-20, apps/server/src/workspace-init.ts:36-50
Architecture and Tooling
The browser extension system relies on the opencode-chrome-devtools plugin, which must be declared in the workspace opencode.jsonc file. When active, this plugin provides the agent with a suite of browser-specific tools.
Core Browser Tools
The system exposes the following tools to the agent:
browser_navigate: Navigates to a specific URL.browser_snapshot: Captures an accessibility tree with UIDs for interaction.- browser_click / browser_fill: Interacts with elements based on snapshot UIDs.
browser_eval: Executes JavaScript within the page context.browser_list: Discovers available targets on the CDP endpoint.browser_screenshot: Captures a visual representation of the current page.
Sources: evals/browser-extension-flows.md:36-80, apps/server/src/workspace-init.ts:42-45
Connection Logic
The agent interacts with the browser via a CDP URL. In local development or desktop environments, this is typically exposed on port 9223 or 9222. The agent is instructed to use the built-in browser target and avoid navigating the OpenWork application target itself.
The diagram shows the logic flow from an agent's request to browser interaction, highlighting the importance of the plugin and CDP connection.
Sources: evals/browser-extension-flows.md:55-65, apps/server/src/workspace-init.ts:46-50
User Interface Integration
Composer Extensions
The Composer interface includes an "Extensions" menu that lists enabled extensions from the catalog. Selecting the "OpenWork Browser" extension injects a predefined composerPrompt (e.g., "Use the OpenWork Browser extension to ") into the text area.
Sources: apps/app/src/react-app/domains/session/surface/composer/composer.tsx:430-440, evals/browser-extension-flows.md:105-125
Extension Management
Extensions can be managed through the Settings/Extensions panel. Key states include:
- Enabled/Disabled: Controlled via
localStoragekeys (e.g.,openwork.extension.disabled.openwork-browser). Disabling an extension removes it from the Composer menu. - Hidden: A "Finder-style" hidden view allows users to hide extensions from the catalog and composer without uninstalling them.
- Preview Status: Indicates extensions still in early release stages.
Sources: apps/app/src/react-app/domains/settings/extension-state.ts, evals/browser-extension-flows.md:130-175
Extension Details
The ExtensionDetailModal provides comprehensive information regarding the extension's capabilities and configuration.
| Field | Description |
|---|---|
| Kind | Categorizes the extension as MCP, Plugin, Skill, UI Control, or OpenWork Extension. |
| Status | Shows if the extension is Connected, Installed, or Offline. |
| Visibility | Indicates if the item is "Hidden" or "Shown" in the normal catalog. |
| Setup Instructions | Declarative instructions provided by the extension manifest. |
| Trigger Phrases | Specifically for Skills, identifies user phrases that activate the tool. |
Sources: apps/app/src/react-app/design-system/extension-detail-modal.tsx:160-260
Workspace Migration and Initialization
The system includes a migration path for workspaces created under older architectures. Legacy MCP keys are removed and replaced by the unified plugin architecture.
Legacy Cleanup
During workspace initialization, the server checks for stale MCP keys in opencode.jsonc.
| Legacy Key | Action |
|---|---|
openwork-browser | Removed |
chrome | Removed |
chrome-devtools | Removed |
control-chrome | Removed |
Sources: apps/server/src/workspace-init.ts:7-8, evals/browser-extension-flows.md:150-165
Automated Initialization Logic
When a workspace is initialized, the server ensures the existence of the opencode-chrome-devtools plugin and the openwork default agent.
The sequence diagram illustrates the automated migration and initialization process performed by the server to ensure the Browser Extension system is correctly configured.
Sources: apps/server/src/workspace-init.ts:168-205, apps/server/src/workspace-init.test.ts:75-90
Extension State and Persistence
Extension visibility and enablement are persisted across sessions. The system uses a custom event openwork:extension-state-changed to trigger UI re-renders when states change.
| Storage Key Pattern | Value | Purpose |
|---|---|---|
openwork.extension.disabled.[id] | "1" | Persists the disabled state of an extension. |
openwork.extension.hidden.[id] | "1" | Persists the hidden (catalog-only) state. |
Sources: apps/app/src/react-app/domains/settings/extension-state.ts, evals/browser-extension-flows.md:143-148
Summary
The Browser Extension System provides a standardized interface for web automation within OpenWork. By consolidating legacy MCP configurations into the opencode-chrome-devtools plugin and providing a clean UI for management, the system enables agents to perform multi-step browser tasks—such as navigation, form filling, and snapshot analysis—with high reliability and user visibility. All states, from enablement to visibility, are persisted at the workspace level and integrated into the primary Composer workflow.
Sources: evals/browser-extension-flows.md:85-100, apps/server/src/workspace-init.ts:100-110