{
  "markdown": "# Superpowers Chrome - Claude Code Plugin\n\nDirect browser control via Chrome DevTools Protocol. Two modes available:\n\n1. **Skill Mode** - CLI tool for Claude Code agents (`browsing` skill)\n2. **MCP Mode** - Ultra-lightweight MCP server for any MCP client\n\n## Features\n\n- **Zero dependencies** - Built-in WebSocket, no npm install needed\n- **Idiotproof API** - Tab index syntax (`0`, `1`, `2`) instead of WebSocket URLs\n- **Platform-agnostic** - `chrome-ws start` works on macOS, Linux, Windows\n- **17 commands** covering all browser automation needs\n- **Complete documentation** with real-world examples\n\n## Installation\n\n```bash\n/plugin marketplace add obra/superpowers-marketplace\n/plugin install superpowers-chrome@superpowers-marketplace\n```\n\n## Quick Start\n\n```bash\n# Find your plugin installation path (varies by marketplace and version)\n# Common locations:\n#   ~/.claude/plugins/cache/superpowers-marketplace/superpowers-chrome/<version>/skills/browsing\n#   ~/.claude/plugins/cache/superpowers-chrome/skills/browsing\n\ncd ~/.claude/plugins/cache/superpowers-marketplace/superpowers-chrome/*/skills/browsing\n./chrome-ws start                        # Launch Chrome\n./chrome-ws new \"https://example.com\"   # Create tab\n./chrome-ws navigate 0 \"https://google.com\"\n./chrome-ws fill 0 \"textarea[name=q]\" \"test\"\n./chrome-ws click 0 \"button[name=btnK]\"\n```\n\n**Port allocation:** Chrome gets a dynamically allocated port (range 9222-12111) to avoid conflicts. Port assignment is persisted per profile in `~/.cache/superpowers/browser-profiles/{name}.meta.json`. Override with `--port=N` flag or `CHROME_WS_PORT` env var. Multiple profiles can run in parallel on different ports.\n\n**Parallel MCPs on one host** (3.0+): the bridge auto-disambiguates the default profile. The first MCP claims `superpowers-chrome:9222`, the next silently falls through to `superpowers-chrome-2:9223`, then `-3:9224`, etc., each driving its own Chrome with its own profile dir. To intentionally **share** a Chrome between processes (e.g., a `chrome-ws` CLI session + a Claude MCP attaching to it), set a fixed profile via `CHROME_WS_PROFILE=name` (env var) or call `{action: \"set_profile\", payload: \"name\"}` at runtime — explicit profiles share rather than disambiguate.\n\n**Windows tip:** The tooling defaults to `127.0.0.1` for DevTools traffic. Override via `CHROME_WS_HOST` / `CHROME_WS_PORT` or `--port=N` if you forward Chrome elsewhere.\n\n**Linux/WSL2 tip:** For headed mode (visible browser), the MCP server needs the `DISPLAY` environment variable. If `show_browser` doesn't work, configure `\"env\": {\"DISPLAY\": \":0\"}` in your MCP server config. See [mcp/README.md](mcp/README.md#linuxwsl2-headed-mode) for details. Running as root or inside a container is detected automatically and disables Chrome's sandbox; on a headless box add `CHROME_EXTRA_ARGS=\"--headless=new --disable-gpu\"`.\n\n**Custom Chrome flags:** Set `CHROME_EXTRA_ARGS` to a whitespace-separated list of flags that will be appended to the Chrome command line on launch. Useful for headless containers that need software WebGL:\n\n```\nCHROME_EXTRA_ARGS=\"--use-gl=angle --use-angle=swiftshader-webgl --enable-unsafe-swiftshader\"\n```\n\n## Windows Verification (November 7, 2025)\n\n- `node skills/browsing/chrome-ws start` launched Chrome with remote debugging enabled on a fresh Windows 11 Pro install.\n- `node skills/browsing/chrome-ws tabs` and `node skills/browsing/chrome-ws navigate 0 https://example.com` confirmed CLI control with the IPv4 default binding.\n- `codex exec -c \"mcp_servers.superpowers-chrome.enabled=true\" \"List Chrome tabs via MCP to verify the Windows override patch.\"` listed the Example Domain tab through the MCP server, demonstrating that the overrides also work through Codex.\n\n## Commands\n\n- **Setup**: `start` (auto-detects platform)\n- **Tab management**: `tabs`, `new`, `close`\n- **Navigation**: `navigate`, `wait-for`, `wait-text`\n- **Interaction**: `click`, `fill`, `select`\n- **Extraction**: `eval`, `extract`, `attr`, `html`\n- **Export**: `screenshot`, `markdown`\n- **Raw protocol**: `raw` (full CDP access)\n\n## Dialog Handling\n\nPages that open JavaScript dialogs (`alert`, `confirm`, `prompt`, `beforeunload`), WebUSB/Bluetooth/Serial/HID device choosers, HTTP basic-auth challenges, or permission prompts (camera, microphone, notifications, geolocation, clipboard) no longer wedge the connection. The dialog is surfaced as a synthetic page response and the agent interacts with it using the existing `click` and `type` actions against a small `dialog::*` selector grammar.\n\n### What an agent sees\n\nWhile a dialog is open, any page-targeted action (`extract`, `screenshot`, `eval`, `attr`, `click <real-selector>`, etc.) returns a clear refusal with the dialog content and instructions:\n\n```\nPage is behind a dialog. Handle dialog::accept or dialog::dismiss first.\n\n# Dialog: confirm\nTab origin: https://example.com\n\n> Are you sure you want to leave?\n\nButtons:\n  - dialog::accept   (OK)\n  - dialog::dismiss  (Cancel)\n\nTo interact:\n  click selector=\"dialog::accept\"\n  click selector=\"dialog::dismiss\"\n```\n\nBrowser-targeted actions (`list_tabs`, `new_tab`, `close_tab`, etc.) pass through unaffected.\n\n### Selector grammar\n\n| Selector | Purpose |\n|---|---|\n| `click dialog::accept` | OK / Grant / Provide credentials, depending on dialog kind |\n| `click dialog::dismiss` | Cancel / Deny |\n| `type dialog::prompt <value>` | Stage prompt text; commit on `dialog::accept` |\n| `click dialog::device[id=\"…\"]` | Pick a device in the chooser (USB, BT, Serial, HID) |\n| `type dialog::username <value>` / `type dialog::password <value>` | Basic-auth credentials |\n\n### Worked example\n\n```\n# 1. Page on load: alert('Saved!')\nextract payload=text\n# → refused with synthetic dialog markdown\n\n# 2. Dismiss\nclick selector=\"dialog::accept\"\n\n# 3. Page is interactive again\nextract payload=text\n# → returns the page text\n```\n\nPermission prompts (`getUserMedia`, `Notification.requestPermission`, geolocation, clipboard) are caught by a `document_start` JS-API shim and surfaced through the same flow.\n\nSee `docs/superpowers/specs/2026-05-13-dialog-handling-design.md` for the full design.\n\n## MCP Server Mode\n\nUltra-lightweight MCP server with a single `use_browser` tool. Perfect for minimal context usage with automatic page captures.\n\n### Installation Options\n\n**Option 1: NPX from GitHub (Recommended)**\n```json\n{\n  \"mcpServers\": {\n    \"chrome\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"github:obra/superpowers-chrome\"\n      ]\n    }\n  }\n}\n```\n\n**Option 1b: NPX with Headless Mode**\n```json\n{\n  \"mcpServers\": {\n    \"chrome\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"github:obra/superpowers-chrome\",\n        \"--headless\"\n      ]\n    }\n  }\n}\n```\n\n**Option 2: Git Clone + Local Path (Current)**\n```bash\ngit clone https://github.com/obra/superpowers-chrome.git\ncd superpowers-chrome/mcp && npm install && npm run build\n```\n```json\n{\n  \"mcpServers\": {\n    \"chrome\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/path/to/superpowers-chrome/mcp/dist/index.js\"\n      ]\n    }\n  }\n}\n```\n\n\n### Auto-Capture Features\n\nDOM-changing actions (navigate, click, type, select, eval) automatically capture:\n- **Page HTML**: Full rendered DOM state\n- **Page Markdown**: Structured content extraction\n- **Screenshot**: Visual page state\n- **DOM Summary**: Token-efficient page structure\n- **Session Organization**: Time-ordered captures in temp directory\n\nResponse format:\n```\n→ https://example.com (capture #001)\nSize: 1200×765\nSnapshot: /tmp/chrome-session-123/001-navigate-456/\nResources: page.html, page.md, screenshot.png, console-log.txt\nDOM:\n  Example Domain\n  Interactive: 0 buttons, 0 inputs, 1 links\n  Layout: body\n```\n\n### Usage\n\n```json\n{\n  \"action\": \"navigate\",\n  \"payload\": \"https://example.com\"\n}\n```\n\nGet help: `{\"action\": \"help\"}` - Returns complete documentation\n\nSee [mcp/README.md](mcp/README.md) for complete documentation.\n\n## When to Use\n\n**Use Skill Mode when:**\n- Working with Claude Code agents\n- Need full CLI control with 17 commands\n\n**Use MCP Mode when:**\n- Using Claude Desktop or other MCP clients\n- Want minimal context usage (single tool)\n\n**Use Playwright MCP when:**\n- Need fresh browser instances\n- Complex automation with screenshots/PDFs\n- Prefer higher-level abstractions\n\n## Documentation\n\n- [SKILL.md](skills/browsing/SKILL.md) - Complete skill guide\n- [EXAMPLES.md](skills/browsing/EXAMPLES.md) - Real-world examples\n- [chrome-ws README](skills/browsing/README.md) - Tool documentation\n\n## License\n\nMIT\n",
  "bytes": 8513,
  "sha": "08db653a8dcf9ac538e3c62dcb06466d3c037cadc1d5e48123d271d5f8359813",
  "repo_slug": "obra/superpowers-chrome",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_obra_superpowers_chrome_skills_browsing__079e18b7/readme"
}