> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Automation

> Claude Browser Attach and Codex Browser Tools setup, policy, and safe launch controls

# Browser Automation

CCS exposes browser automation through two separate lanes:

* **Claude Browser Attach** reuses a Chrome or Chromium session through the
  CCS-managed local `ccs-browser` MCP runtime.
* **Codex Browser Tools** injects Playwright MCP tooling into Codex-target
  launches through the managed `ccs_browser` runtime config entry.

These lanes share the Settings workspace, but they do not promise a shared
browser session.

## Safe Defaults

New installs, and upgrades without explicit saved browser settings, keep both
lanes disabled and manual:

```yaml theme={null}
browser:
  claude:
    enabled: false
    policy: manual
    user_data_dir: "~/.ccs/browser/chrome-user-data"
    devtools_port: 9222
  codex:
    enabled: false
    policy: manual
```

`policy: manual` means the lane stays hidden unless the current launch opts in
with `--browser`.

## Dashboard Setup

Open:

```bash theme={null}
ccs config
# Settings -> Browser
```

The Browser tab lets you enable or disable each lane, inspect readiness, choose
the Claude attach user-data directory and DevTools port, and copy the Chrome
launch command.

## CLI Setup

```bash theme={null}
ccs help browser
ccs browser setup
ccs browser status
ccs browser doctor
ccs browser policy
ccs browser policy --all manual
ccs browser enable claude
ccs browser disable codex
```

`ccs browser setup` is the primary remediation flow for Claude Browser Attach.
`ccs browser doctor` is read-only and explains what is missing.

## One-Run Overrides

```bash theme={null}
ccs browser policy --all manual
ccs glm --browser "inspect the page"
ccs glm --no-browser "summarize the docs"
ccs default --target codex --browser "use browser tools for this run"
```

* `--browser` forces browser tooling on for the current launch when the lane is
  enabled.
* `--no-browser` suppresses browser tooling for the current launch even when
  policy is `auto`.

## Claude Attach Requirements

Claude Browser Attach needs a browser launched with remote debugging:

```bash theme={null}
# macOS
open -na "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir="$HOME/.ccs/browser/chrome-user-data"

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.ccs/browser/chrome-user-data"

# Windows
chrome.exe --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\\.ccs\\browser\\chrome-user-data"
```

Use a dedicated CCS browser data directory instead of your everyday browser
profile.

## Managed Runtime Files

* `~/.claude.json` stores the managed `mcpServers.ccs-browser` entry for Claude
  Browser Attach.
* `~/.ccs/mcp/ccs-browser-server.cjs` is the local MCP runtime.
* Codex launches receive managed `ccs_browser` overrides when the Codex lane is
  enabled and exposed.

## Security Notes

Browser automation may operate inside authenticated browser sessions. Keep the
automation profile separate from your daily browser profile, and never commit
browser paths, secrets, or generated session state.

## Related

* [Settings Workspace](/features/dashboard/settings-workspace)
* [CLI Flags](/reference/cli-flags#browser-automation-flags)
* [Configuration Schema](/reference/config-schema#browser-automation-configuration)