From deb1ed0e67d6ca71953f0a78f72b9916c8bc8ed5 Mon Sep 17 00:00:00 2001 From: Tam Nhu Tran Date: Sun, 26 Jul 2026 09:35:42 -0400 Subject: [PATCH] docs(readme): route user guides to canonical docs --- README.md | 7 +- docs/browser-automation.md | 304 ++++++------------------------------- docs/image-analysis.md | 123 +-------------- 3 files changed, 56 insertions(+), 378 deletions(-) diff --git a/README.md b/README.md index 537f711f..fca54735 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,8 @@ The proxy also supports request-time `profile:model` selectors, scenario-based model routing through `proxy.routing`, and explicit activation helpers such as `ccs proxy activate --fish`. -Guide: [OpenAI-Compatible Provider Routing](./docs/openai-compatible-providers.md) +Guide: +[OpenAI-Compatible Provider Routing](https://docs.ccs.kaitran.ca/features/proxy/openai-compatible-providers). ### Related Project: claude-code-router @@ -166,7 +167,7 @@ CCS can provision first-class local tools like WebSearch and image analysis for third-party launches instead of leaving you to wire them by hand. Browser automation now has a first-class setup path as well. Deep dive: [WebSearch](https://docs.ccs.kaitran.ca/features/ai/websearch) | -[Browser Automation](./docs/browser-automation.md). +[Browser Automation](https://docs.ccs.kaitran.ca/features/workflow/browser-automation). ## Docs Matrix @@ -183,7 +184,7 @@ reference material. | Compare OAuth providers, Claude accounts, and API profiles | [Provider Overview](https://docs.ccs.kaitran.ca/providers/concepts/overview) | | Learn the dashboard structure and feature pages | [Dashboard Overview](https://docs.ccs.kaitran.ca/features/dashboard/overview) | | Configure profiles, paths, and environment variables | [Configuration](https://docs.ccs.kaitran.ca/getting-started/configuration) | -| Understand browser attach vs Codex browser tooling | [Browser Automation](./docs/browser-automation.md) | +| Understand browser attach vs Codex browser tooling | [Browser Automation](https://docs.ccs.kaitran.ca/features/workflow/browser-automation) | | Keep OpenCode aligned with your live CCS setup | [OpenCode Sync Plugin](https://docs.ccs.kaitran.ca/features/workflow/opencode-sync) | | Browse every command and flag | [CLI Commands](https://docs.ccs.kaitran.ca/reference/cli-commands) | | Recover from install, auth, or provider failures | [Troubleshooting](https://docs.ccs.kaitran.ca/reference/troubleshooting) | diff --git a/docs/browser-automation.md b/docs/browser-automation.md index aeb5e617..d27a323f 100644 --- a/docs/browser-automation.md +++ b/docs/browser-automation.md @@ -1,273 +1,61 @@ -# Browser Automation +# Browser Automation Developer Contract -Last Updated: 2026-05-11 +User setup and troubleshooting live in the canonical +[Browser Automation guide](https://docs.ccs.kaitran.ca/features/workflow/browser-automation). +This local file retains security-sensitive runtime invariants that contributors +must preserve until the public guide covers them fully. -CCS provides browser automation through two separate runtime paths: +## Exposure And Runtime Ownership -- **Claude Browser Attach**: reuses a running Chrome/Chromium session through the CCS-managed local `ccs-browser` MCP runtime -- **Codex Browser Tools**: injects Playwright MCP tooling into Codex-target launches +- Claude Browser Attach and Codex Browser Tools are separate lanes; they do not + promise a shared browser session. +- New installs and upgrades without saved browser settings default both lanes + to `enabled: false` and `policy: manual`. +- `--browser` and `--no-browser` are one-run exposure overrides. They do not + change saved policy. +- CCS owns `mcpServers.ccs-browser`, the + `~/.ccs/mcp/ccs-browser-server.cjs` runtime, and Codex `ccs_browser` + overrides. Generic MCP editors are not the primary setup surface. -These are related, but they are not the same implementation and they do not promise a shared browser session. -On new installs, and on upgrades that do not already have explicit browser settings, both lanes -start **disabled** and **manual** so browser tooling is not auto-exposed until you opt in. - -## How Browser Automation Works - -### Claude Browser Attach - -Claude-target CCS launches can provision a managed local MCP server named `ccs-browser`. -That path is designed for workflows where you want Claude to interact with a browser session -that already has useful authenticated state. - -Claude Browser Attach requires a browser launched in attach mode with remote debugging -enabled. A recent Chrome update alone is not sufficient. - -### Codex Browser Tools - -Codex-target CCS launches use a separate managed path: CCS injects Playwright MCP overrides -for the `ccs_browser` runtime config entry. - -This is configured from the same Browser settings surface, but it is distinct from Claude -Browser Attach. - -## Configuration - -### Via Dashboard - -Open `ccs config` -> `Settings` -> `Browser`. - -The Browser screen exposes two sections: - -- **Claude Browser Attach** - - enable/disable the Claude attach lane - - choose the Chrome user-data directory - - set the expected DevTools port - - review readiness and next-step guidance - - copy a generated browser launch command -- **Codex Browser Tools** - - enable/disable CCS-managed browser tooling for Codex-target launches - - review whether the detected Codex build supports managed browser overrides - -Browser policy controls are CLI-first in this release. The dashboard remains the shared setup and -status surface, while `ccs browser policy` is the authoritative place to decide whether browser -tooling is auto-exposed or kept manual by default. Fresh installs, plus upgrades without an -existing browser section, surface both lanes as off/manual until you explicitly enable them. - -### Via CLI - -```bash -ccs help browser -ccs browser setup -ccs browser status -ccs browser doctor -ccs browser policy -ccs browser policy --all manual -``` - -Use `ccs browser setup` for the primary one-command setup path. Use `ccs browser status` for -the current state, `ccs browser doctor` for read-only troubleshooting guidance, and -`ccs browser policy` to control default browser exposure. If you only want browser access for one -run, keep policy manual and add `--browser` to that launch. - -### Via Config File - -Edit `~/.ccs/config.yaml`: - -```yaml -browser: - claude: - enabled: false - policy: manual - user_data_dir: "~/.ccs/browser/chrome-user-data" - devtools_port: 9222 - codex: - enabled: false - policy: manual -``` - -Notes: - -- `claude.policy` and `codex.policy` accept `auto` or `manual` -- `claude.user_data_dir` is a **Chrome user-data directory**, not a display-name browser profile -- `claude.devtools_port` is the expected remote debugging port for attach mode -- `codex.enabled` controls whether CCS injects browser tooling into Codex-target launches -- New installs, plus upgrades without saved browser settings, default both lanes to `enabled: false` and `policy: manual` -- `manual` keeps the lane configured but hidden until a launch explicitly opts in with `--browser` - -## Runtime Policy Controls - -CCS now separates **lane enablement** from **default exposure policy**: - -- `enabled: false` - - the lane is off; this is the default for both lanes on new installs and upgrades without saved browser settings -- `enabled: true` + `policy: auto` - - the lane is exposed automatically on matching launches -- `enabled: true` + `policy: manual` - - the lane stays configured, but CCS keeps browser tooling hidden unless the current launch uses - `--browser` - -One-run launch overrides: - -```bash -ccs browser policy --all manual -ccs glm --browser "inspect the page" -ccs glm --no-browser "summarize the docs" -ccs default --target codex --browser "use the browser tools for this run" -``` - -- `--browser` forces browser tooling on for the current launch when that lane is enabled -- `--no-browser` suppresses browser tooling for the current launch even when policy is `auto` - -## Environment Variable Overrides - -CCS still supports environment-variable overrides for backward compatibility. - -| Variable | Description | -|----------|-------------| -| `CCS_BROWSER_USER_DATA_DIR` | Preferred override for Claude Browser Attach user-data dir | -| `CCS_BROWSER_PROFILE_DIR` | Legacy alias for the same attach directory | -| `CCS_BROWSER_DEVTOOLS_PORT` | Explicit DevTools port override | -| `CCS_BROWSER_INTERCEPT_FULFILL_MODE=enabled` | Dangerous local-testing opt-in for Browser MCP response fulfillment; disabled by default | -| `CCS_BROWSER_UPLOAD_ROOTS` | Optional `path.delimiter`-separated allowlist for local files that browser upload tools may read | -| `CCS_BROWSER_DOWNLOAD_ROOTS` | Optional `path.delimiter`-separated allowlist for caller-provided browser download directories | - -If an override is active, Browser status surfaces should report that the current session is being -managed externally by environment variables. - -Browser MCP request interception can continue or fail matched requests by default. Synthetic response -fulfillment (`action: fulfill`) is more sensitive because it can serve caller-supplied response -content inside the attached browser's target origin. CCS therefore hides and blocks fulfillment unless -`CCS_BROWSER_INTERCEPT_FULFILL_MODE=enabled` is set for a trusted local test session. - -The saved browser policy still controls default exposure. Env overrides change the effective attach -path/port for the current shell; they do not bypass `policy: manual`. - -Override precedence is: +## Attach Override Precedence 1. `CCS_BROWSER_USER_DATA_DIR` -2. `CCS_BROWSER_PROFILE_DIR` -3. the persisted `browser.claude.user_data_dir` config value +2. legacy `CCS_BROWSER_PROFILE_DIR` +3. persisted `browser.claude.user_data_dir` -Config-backed Browser Attach always passes an explicit DevTools port to the runtime, even when the -effective value is the default `9222`. Metadata-based port discovery is preserved only for the -legacy `CCS_BROWSER_PROFILE_DIR` flow when `CCS_BROWSER_DEVTOOLS_PORT` is not set. +Config-backed attach always passes an explicit DevTools port, including the +default `9222`. Metadata-based port discovery exists only for the legacy +profile-dir override when `CCS_BROWSER_DEVTOOLS_PORT` is unset. -### Browser File Transfer Safety +## Interception Safety -Claude Browser Attach file-transfer tools intentionally use a deny-by-default filesystem boundary: +Request interception may continue or fail matched requests by default. +Synthetic fulfillment can serve caller-supplied content inside the target +origin, so it must stay hidden and blocked unless +`CCS_BROWSER_INTERCEPT_FULFILL_MODE=enabled` is explicitly set for a trusted +local test. -- Downloads without an explicit `downloadPath` go to a CCS-created temporary session directory. -- A caller-provided `downloadPath` must be inside that temporary session directory or inside one of - the directories listed in `CCS_BROWSER_DOWNLOAD_ROOTS`. -- Local upload and drag-and-drop files must be inside the temporary session download directory or - inside one of the directories listed in `CCS_BROWSER_UPLOAD_ROOTS`. -- Hidden path segments and common secret locations/files, such as `.ssh`, `.aws`, `.ccs`, - `.claude`, `.env`, and private-key filenames, are rejected even inside an allowed root. -- Each file-transfer call is limited to 10 files, and each local file must be at most 10 MiB. +## Event Observation Safety -Set upload/download roots only to purpose-built scratch directories. Do not point these variables at -your home directory, a source checkout with secrets, or a real cloud/tooling config directory. +- `browser_wait_for_event` requires `urlIncludes` for network-request events. +- Download events require either `urlIncludes` or + `suggestedFilenameIncludes`. +- Returned navigation, request, and download URLs must redact query strings, + fragments, and path-scoped bearer values before reaching the MCP caller. -## Managed Runtime Files +## File Transfer Safety -- `~/.claude.json` -> CCS manages `mcpServers.ccs-browser` for Claude Browser Attach -- `~/.ccs/mcp/ccs-browser-server.cjs` -> local Claude Browser Attach MCP runtime -- `Codex runtime config overrides` -> CCS manages the `ccs_browser` MCP entry for Codex-target launches +Browser file transfer is deny-by-default: -Do not treat the generic Codex MCP editor as the primary browser setup path. CCS-managed browser -entries should be configured from `Settings -> Browser`. +- implicit downloads use a CCS-created temporary session directory; +- explicit download paths must remain inside that session directory or a + `CCS_BROWSER_DOWNLOAD_ROOTS` allowlisted root; +- uploads and drag-and-drop files must remain inside the session directory or a + `CCS_BROWSER_UPLOAD_ROOTS` allowlisted root; +- hidden segments and common secret locations/files (`.ssh`, `.aws`, `.ccs`, + `.claude`, `.env`, private keys) remain denied inside allowed roots; +- each call permits at most 10 files, each no larger than 10 MiB. -## Primary Setup Flow - -The shortest supported setup path is: - -```bash -ccs browser setup -``` - -That flow: - -1. enables Claude Browser Attach in the saved CCS browser config -2. leaves launch exposure under the saved policy, so `policy: manual` still requires `--browser` -3. keeps the configured DevTools port normalized -4. creates the configured browser user-data directory if needed -5. prints the exact browser launch command for the current platform -6. re-checks readiness and reports the next step if Chrome still needs manual attention - -## Launching Chrome For Claude Attach - -Claude Browser Attach needs a browser launched with remote debugging. - -Typical examples: - -```bash -# 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" -``` - -Using a dedicated CCS browser data dir is recommended. It avoids profile-locking issues and keeps -automation state separate from your daily browser profile. - -When Claude Browser Attach uses the recommended managed path (`~/.ccs/browser/chrome-user-data`), -CCS now creates that directory automatically the first time it needs it. After that bootstrap step, -the remaining requirement is a running Chrome session started with `--remote-debugging-port`. - -## Troubleshooting - -### Browser status says Claude Browser Attach is disabled - -Run `ccs browser setup`, enable Claude Browser Attach in `Settings -> Browser`, or edit the -browser config block in `~/.ccs/config.yaml`. - -### Browser status says the path is missing - -The configured Chrome user-data directory does not exist yet. - -1. Run `ccs browser setup` -2. If Chrome still is not ready, use the generated launch command -3. Rerun `ccs browser doctor` - -If you are using the CCS-managed default path, this usually means the path could not be created -automatically and now needs manual attention. - -### Browser status says no running browser session was found - -CCS could not find usable DevTools attach metadata for the configured user-data directory. - -1. Run `ccs browser setup` -2. If needed, make sure Chrome was started with `--remote-debugging-port=` -3. Make sure it is using the same `user_data_dir` configured in CCS -4. Rerun `ccs browser doctor` - -For the CCS-managed default path, this is the normal first-run state after CCS bootstraps the -directory for you. - -### Browser status says the DevTools endpoint is unreachable - -CCS found attach metadata, but the endpoint did not answer successfully. - -1. Run `ccs browser setup` -2. If needed, restart the attach browser session -3. Confirm the expected port matches the real remote debugging port -4. Rerun `ccs browser status` - -### Codex Browser Tools are unavailable - -Codex browser tooling depends on a Codex build that supports `--config` overrides. - -If CCS reports `unsupported_build`, upgrade Codex and rerun `ccs browser status`. - -## Security Notes - -- Browser automation may operate inside authenticated browser sessions -- Prefer a dedicated automation user-data dir instead of your everyday browser profile -- Do not commit browser paths, secrets, or generated session state to version control -- Treat `~/.ccs/config.yaml`, `~/.claude.json`, and the browser user-data directory as local machine state -- `browser_wait_for_event` requires explicit scoping for network request events (`urlIncludes`) and download events (`urlIncludes` or `suggestedFilenameIncludes`) -- Event details redact observed navigation, request, and download URLs before returning them to the MCP caller so observed browser metadata does not expose query strings, fragments, or path-scoped bearer values +Allowlist only purpose-built scratch directories. Never allowlist a home +directory, source checkout containing secrets, or real tooling configuration +directory. diff --git a/docs/image-analysis.md b/docs/image-analysis.md index 0e5b525d..718f2f18 100644 --- a/docs/image-analysis.md +++ b/docs/image-analysis.md @@ -1,119 +1,8 @@ -# Image Analysis Configuration Guide +# Image Analysis -CCS provides first-class image and PDF analysis for third-party Claude launches that do not have reliable native vision support. +User setup, routing behavior, and troubleshooting live in the canonical +[Image Analysis guide](https://docs.ccs.kaitran.ca/features/ai/image-analysis). -## How Image Analysis Works - -Native Claude accounts keep Anthropic's own vision flow. - -Third-party profiles now use a CCS-managed local MCP tool named `ImageAnalysis` when the runtime is available. CCS also appends a short steering hint so Claude prefers that tool over `Read` for local image and PDF files. - -Healthy Claude-target launches suppress the legacy CCS `Read` hook so MCP stays authoritative. If the managed runtime cannot be provisioned, CCS keeps the old `Read` hook available only as a compatibility fallback when that path is still viable. If runtime/auth/proxy readiness is degraded beyond that, CCS falls back to native `Read` instead of failing the whole launch. - -## Routing Model - -ImageAnalysis requests go straight to the CCS-managed provider route: - -```text -Claude -> ccs-image-analysis MCP -> CCS provider route -> /api/provider//v1/messages -``` - -Important: -- CCS does not relay image analysis through Claude Code, another CLI, or a second model wrapper. -- For bridge-backed settings profiles, CCS resolves the backend and provider path before launch. -- CCS avoids leaking a profile's ordinary third-party `ANTHROPIC_BASE_URL` or token into image analysis unless that profile is explicitly using a CLIProxy bridge. - -## Profile Behavior - -| Profile Type | Image Method | -|--------------|--------------| -| Claude `default` / `account` | Native Claude vision / native `Read` | -| Third-party settings / CLIProxy / Copilot | CCS local `ImageAnalysis` MCP tool when ready | -| Third-party when MCP provisioning fails but provider-backed analysis is still viable | Legacy CCS `Read` hook fallback | -| Third-party when runtime/auth/proxy is unavailable | Native `Read` fallback | - -## Configuration - -Configure via dashboard (`Settings -> Image`) or `~/.ccs/config.yaml`: - -```yaml -image_analysis: - enabled: true - timeout: 60 - fallback_backend: agy - provider_models: - agy: gemini-3-1-flash-preview - codex: gpt-5.1-codex-mini - ghcp: claude-haiku-4.5 -``` - -Useful commands: - -```bash -ccs config image-analysis -ccs config image-analysis --enable -ccs config image-analysis --disable -ccs config image-analysis --set-fallback agy -ccs config image-analysis --set-profile-backend glm agy -ccs config image-analysis --clear-profile-backend glm -``` - -## Prompt Templates - -CCS installs editable prompt templates at: - -```text -~/.ccs/prompts/image-analysis/ -``` - -Templates: -- `default.txt` -- `screenshot.txt` -- `document.txt` - -CCS automatically selects `screenshot` for screenshot-like filenames, `document` for PDFs, and `default` otherwise. - -## Runtime Environment - -Key runtime env vars: - -| Variable | Purpose | -|----------|---------| -| `CCS_IMAGE_ANALYSIS_SKIP` | Disable image analysis for the current launch | -| `CCS_IMAGE_ANALYSIS_SKIP_HOOK` | Suppress only the legacy CCS `Read` hook while keeping MCP ImageAnalysis available | -| `CCS_IMAGE_ANALYSIS_RUNTIME_BASE_URL` | Explicit CCS runtime base URL | -| `CCS_IMAGE_ANALYSIS_RUNTIME_PATH` | Provider route such as `/api/provider/agy` | -| `CCS_IMAGE_ANALYSIS_RUNTIME_API_KEY` | Explicit CCS runtime auth key | -| `CCS_IMAGE_ANALYSIS_MODEL` | Force a single image-analysis model | -| `CCS_DEBUG` | Verbose runtime logging | - -## Self-Heal - -CCS now auto-heals stale managed image-analysis state in three places: - -- Healthy Claude launches remove stale CCS-managed image `Read` hooks from the active profile settings before launch. -- `Settings -> Image` save/provisioning repairs managed MCP runtime files, syncs managed MCP entries into isolated Claude config dirs, and cleans stale CCS-managed image hooks from `~/.ccs/*.settings.json`. -- `ccs doctor --fix` repairs invalid image-analysis config, removes stale CCS-managed image hooks, and resyncs managed `ccs-image-analysis` MCP entries into isolated configs. - -## Troubleshooting - -### Claude still uses `Read` - -- Confirm `ccs config image-analysis` shows `enabled: true` -- Check the active profile resolves to a configured backend -- Run `ccs doctor --fix` to repair stale managed hooks or missing managed MCP sync -- Run with `CCS_DEBUG=1` to see runtime preparation details - -### ImageAnalysis is not exposed - -- Verify CLIProxy auth for the resolved backend -- Verify the local or remote CLIProxy target is reachable -- Check `~/.claude.json` and inherited account configs for `ccs-image-analysis` - -### I need to prove requests are going directly to the provider route - -Run with `CCS_DEBUG=1` and inspect the resolved runtime path. The request target should be provider-scoped, for example: - -```text -/api/provider/agy/v1/messages -``` +Contributor implementation contracts are enforced by the source and focused +tests under `src/utils/image-analysis/`, `src/utils/hooks/`, and +`src/web-server/routes/`.