chromeboost CLAUDE.md

ChromeBoost — repo-developer guide

This file is for developers working ON chromeboost. The usage reference for agents (Claude Code, Codex, etc.) lives in packages/plugin/skills/chromeboost/ (and skills-codex/chromeboost/ for the Codex variant). When in doubt, the canonical user-facing docs are in the skill, not here.

What chromeboost is

ChromeBoost is a Chrome extension + MCP server pair that lets coding agents drive the user's real Chrome browser. The extension attaches via CDP; the MCP server exposes 35 tools (click_element, fill_input, type_text, get_page_text, hover, drag, probe_point, hud, etc.) over the standard Model Context Protocol. Agents call those tools; the extension performs the operations in the user's logged-in Chrome window.

The core differentiator is the click + keystroke pipeline: a humanlike CDP bezier sequence with pointerType: "mouse" (firing PointerEvent isPrimary=true alongside MouseEvent), settle-hover micro-tremor, post-click jitter, and isTrusted=true keystrokes. This is what defeats anti-bot checks on Reddit, X / Twitter, and similar isTrusted-strict React UIs.

ChromeBoost adds two things on top of that inherited pipeline:

Occlusion-aware cursor control. Clicks hit-test before firing (content/hittest.ts) instead of aiming at an element's geometric centre and hoping nothing is on top. Covered targets are detected and reported; covering layers are temporarily neutralised with pointer-events: none so the same real CDP click reaches the target, then restored exactly. hover and drag cover the UI that is not click-shaped at all.

A HUD the user owns. The on-page status panel (content/hud.ts) is draggable, collapsible, dismissible, and persists its position — replacing a fixed, pointer-events: none badge welded to the top-right corner.

Repository layout

packages/
  extension/                # Chrome MV3 extension (TypeScript)
    src/
      background.ts         # MCP message dispatcher, CDP helpers, ~3700 lines
      content/              # Content-script handlers (shadow-piercing DOM ops)
        hittest.ts          # Occlusion-aware hit testing + overlay piercing
        hud.ts              # Draggable / hideable on-page HUD (closed shadow root)
      offscreen.ts          # Persistent WebSocket connection to MCP server
      popup/                # Browser-action popup UI
      page-shims.ts         # MAIN-world page shims (focus, WebRTC, etc.)
    build.mjs               # esbuild
    pack.mjs                # Zip the dist/ for Chrome Web Store
    manifest.json
  mcp-server/               # MCP server bundled to packages/plugin/server/
    src/
      index.ts              # Tool registration entry
      ws-bridge.ts          # WebSocket server (extension <-> MCP)
      tools/                # Tool definitions per family
        cursor.ts           # hover, drag, probe_point, hud
      types.ts              # Message types between MCP and extension
    package.json            # Published to npm as "chromeboost"
  plugin/                   # Claude Code / Codex plugin manifest + skill
    .claude-plugin/
      plugin.json
    skills/chromeboost/
      SKILL.md              # User-facing routing + common patterns
      references/           # Topic-specific deep references
    skills-codex/chromeboost/
      SKILL.md              # Codex variant
      references/           # Same references, copied
    server/
      chromeboost.mjs        # Bundled MCP server (esbuild output)
    scripts/
      build-server.sh       # Bundle script