Browser Automation
Relevant source files
The following files were used as context for generating this wiki page:
- src/commands/browser-command.ts
- tests/unit/utils/browser/chrome-reuse.test.ts
- tests/unit/utils/browser/browser-status.test.ts
- tests/unit/hooks/browser-mcp-session-and-intercepts.test.ts
- ui/tests/unit/ui/pages/browser-section.test.tsx
- src/utils/browser/chrome-reuse.ts (Referenced via tests)
- src/utils/browser/browser-status.ts (Referenced via tests)
Browser Automation in CCS provides a bridge between AI runtimes and local web browsing capabilities. It enables AI models to interact with web pages, perform clicks, type text, and intercept network traffic. The system is split into two primary "lanes": Claude Browser Attach, which reuses a local Chrome session for Claude-target launches, and Codex Browser Tools, which inject managed Playwright MCP (Model Context Protocol) overrides into Codex-target launches. Sources: src/commands/browser-command.ts:117-122, README.md
The system prioritizes local privacy and developer control, using existing local Chrome profiles rather than cloud-based headless browsers. Access is governed by a Browser Tool Policy that can be set to auto or manual, determining whether browser tools are exposed to the AI by default or only when explicitly requested. Sources: src/commands/browser-command.ts:31, tests/unit/commands/browser-command.test.ts:211-218
System Architecture
The browser automation architecture revolves around a Model Context Protocol (MCP) server that mediates between the AI agent and the browser instance.
The diagram above illustrates how CCS manages the connection between different AI runtimes and local browser instances via a managed MCP server. Sources: src/commands/browser-command.ts:117-124, tests/unit/commands/browser-command.test.ts:60-94
Claude Browser Attach
This lane facilitates the reuse of a local Chrome user data directory. It relies on the Chrome DevTools Protocol (CDP) and requires Chrome to be launched with a specific remote debugging port. Sources: src/commands/browser-command.ts:117, tests/unit/utils/browser/chrome-reuse.test.ts:153-170
Codex Browser Tools
This lane utilizes a managed Playwright MCP implementation. It supports configuration overrides that allow CCS to inject specific browser tool capabilities into Codex sessions. Sources: src/commands/browser-command.ts:119-120, tests/unit/commands/browser-command.test.ts:95-106
Configuration and Policies
The behavior of browser automation is managed through the browser section of the CCS unified config.
| Option | Type | Default | Description |
|---|---|---|---|
enabled | boolean | false | Global toggle for the specific browser lane (Claude or Codex). |
policy | auto | manual | manual | If auto, tools are exposed by default. If manual, tools stay hidden unless --browser is used. |
user_data_dir | string | (Managed) | Path to the Chrome user data directory. |
devtools_port | number | 9222 | The HTTP port for Chrome remote debugging. |
eval_mode | readonly | disabled | readonly | Controls whether the model can execute JavaScript in the browser. |
Sources: src/commands/browser-command.ts:31, tests/unit/unified-config.test.ts:110-125, tests/unit/utils/browser/browser-status.test.ts:255-265
Manual Launch Overrides
Users can override the saved policy during individual CLI launches using the following flags:
--browser: Forces browser tooling on for the current launch.--no-browser: Suppresses browser tooling for the current launch.
Sources: src/commands/browser-command.ts:127-130
Browser Discovery and Reuse
CCS identifies running Chrome instances by inspecting the DevToolsActivePort file within the specified user data directory. This file contains the port and a unique websocket target for automation. Sources: tests/unit/utils/browser/chrome-reuse.test.ts:153-170
The discovery flow ensures that CCS only attempts to attach to browser instances that are actively listening for remote debugging connections. Sources: tests/unit/utils/browser/chrome-reuse.test.ts:192-205, tests/unit/utils/browser/browser-status.test.ts:133-155
Tool Capabilities
The Browser MCP server exposes a wide array of tools to the AI models. These tools are categorized into navigation, interaction, inspection, and network interception. Sources: tests/unit/hooks/browser-mcp-session-and-intercepts.test.ts:22-66
Interaction Tools
browser_navigate: Changes the URL of the current page.browser_click: Simulates mouse clicks with offsets and button selection.browser_type: Simulates keyboard input into focused elements.browser_drag_element: Performs drag-and-drop operations.
Inspection Tools
browser_get_dom_snapshot: Retrieves the full DOM structure.browser_get_visible_text: Extracts readable text from the viewport.browser_take_screenshot: Captures a visual image of the current page.
Network Interception
CCS supports advanced network interception, allowing the AI to monitor and modify outgoing requests. This is governed by the CCS_BROWSER_INTERCEPT_FULFILL_MODE environment variable. Sources: tests/unit/hooks/browser-mcp-session-and-intercepts.test.ts:684-706
- Continue: Allows a request to proceed normally.
- Fail: Blocks the request.
- Fulfill: (Requires opt-in) Allows providing a mock response, including status codes, headers, and body content. Sources: tests/unit/hooks/browser-mcp-session-and-intercepts.test.ts:708-735
Troubleshooting and Remediation
CCS includes built-in diagnostics through the doctor and status subcommands to help users resolve connectivity issues.
- State Detection: CCS identifies states such as
ready,disabled,browser_not_running, andunsupported_build. Sources: src/commands/browser-command.ts:13-25, tests/unit/commands/browser-command.test.ts:114-124 - Launch Guidance: If a browser is not running, CCS generates platform-specific launch commands (for Darwin, Linux, and Win32) that include the necessary
--remote-debugging-portand--user-data-dirflags. Sources: src/commands/browser-command.ts:153-156, tests/unit/utils/browser/browser-status.test.ts:58-62 - Setup Flow: The
ccs browser setupcommand automates the creation of a managed browser profile directory and ensures the MCP server is correctly provisioned. Sources: src/commands/browser-command.ts:175-185, tests/unit/utils/browser/browser-setup.test.ts:133-176
Summary
Browser Automation in CCS transforms AI runtimes from text-based assistants into interactive agents capable of web-based task execution. By bridging local Chrome instances via the Model Context Protocol, CCS maintains a balance between powerful automation capabilities and user-controlled local privacy. The dual-lane approach ensures compatibility across both Claude and Codex ecosystems, while the policy-driven configuration provides a safe-by-default environment for browser-based AI workflows.