Integrate Chrome DevTools Protocol CLI Tool for Browser Automation

[ballidev]

Integrate Chrome DevTools Protocol CLI Tool for Browser Automation

Summary

Request to integrate chrome-ws (Chrome DevTools Protocol CLI tool) into the browser container system as a lightweight alternative to Playwright for browser automation and testing.

Background

The Playwright MCP currently has significant performance issues when dealing with complex web pages, returning massive YAML snapshots (100KB+) that consume excessive context and are impractical for automation tasks. The chrome-ws tool provides a zero-dependency alternative that works directly with Chrome via DevTools Protocol.

Upstream Project

• Repository: https://github.com/obra/superpowers-chrome
• Tool Location: skills/browsing/ directory
• Key Files:
  • chrome-ws - Main executable (bash script)
  • chrome-ws-lib.js - Core library
  • Documentation: SKILL.md, COMMANDLINE-USAGE.md, EXAMPLES.md

Technical Requirements

Dependencies

• Node.js 16+ (already available)
• Chrome with remote debugging port enabled
• No npm packages required (zero-dependency design)

Wayland Compatibility

Successfully tested on Wayland with the following Chrome flags:

google-chrome \
  --remote-debugging-port=9222 \
  --no-sandbox \
  --enable-features=UseOzonePlatform \
  --ozone-platform=wayland \
  --user-data-dir=/path/to/profile \
  --no-first-run \
  --no-default-browser-check \
  --disable-default-apps \
  --disable-sync

Environment Variables

export DISPLAY=:0
export WAYLAND_DISPLAY=wayland-0

Key Advantages

1. Minimal Output: Returns clean text instead of massive YAML structures

   • Example.com extraction: "Example Domain" (8 bytes)
   • vs Playwright MCP: 100KB+ YAML snapshot

2. Performance:

   • Complex page extraction: 0.05 seconds
   • Amazon homepage: 84 lines, 4KB output

3. Simplicity:

   • Direct bash commands
   • No complex dependencies
   • Works with existing browser sessions

4. Functionality:

   • Navigation and page loading
   • Content extraction (text, HTML, markdown)
   • Element interaction (click, type, select)
   • JavaScript evaluation
   • Cookie/authentication support
   • Multi-tab management
   • Screenshot capture

Proven Use Cases

Successfully demonstrated:

• Extracting structured data from HackerNews (story titles)
• Navigating between pages with visual confirmation
• Clicking links and interacting with elements
• Running JavaScript to extract specific DOM elements
• Exporting pages as markdown

Implementation Options

Option 1: Install as-is

• Clone upstream repository
• Symlink chrome-ws and chrome-ws-lib.js to /usr/local/bin/
• Add to container build process

Option 2: Fork and customize (Recommended)

• Fork repository for our specific needs
• Add Wayland-specific wrapper script
• Pre-configure chrome launch flags for container environment
• Add integration with existing test frameworks
• Maintain as part of fedora-desktop tooling

Recommended Approach

Create a fork with the following customizations:

1. Wrapper Script (/usr/local/bin/chrome-ws-wayland):

   • Auto-configures Wayland environment variables
   • Provides sensible defaults for Chrome flags
   • Handles profile management for ephemeral containers

2. Helper Functions:

   • chrome-start - Launch Chrome with correct flags
   • chrome-stop - Clean shutdown
   • chrome-auth - Set authentication cookies via JavaScript

3. Integration:

   • Add to browser container image
   • Document usage patterns for test automation
   • Provide examples for common scenarios

Testing Confirmation

All features tested and working on Fedora/Wayland:

• ✅ Chrome launches in headed mode with Wayland
• ✅ Remote debugging port accessible
• ✅ CLI commands work correctly
• ✅ Content extraction produces minimal output
• ✅ Interactive browser control functions properly
• ✅ No popup dialogs when using suppression flags

Questions for Discussion

1. Should we install upstream as-is or maintain a fork?
2. Where should the tool be installed? (/usr/local/bin/, /opt/chrome-ws/, etc.)
3. Should Chrome launch be automatic or manual in tests?
4. Do we need additional wrapper scripts for common operations?
5. Should this replace Playwright MCP entirely or complement it?

References

• Upstream repository: https://github.com/obra/superpowers-chrome/tree/main/skills/browsing
• Chrome DevTools Protocol: https://chromedevtools.github.io/devtools-protocol/
• Alternative to Playwright MCP which has known performance issues with large pages

[LTSCommerce]

Implementation Complete ✅

The chrome-ws CLI tool has been successfully integrated into the ccb browser container!

What Was Done

1. Installed chrome-ws Tool

• Added chrome-ws and chrome-ws-lib.js to /opt/chrome-ws/
• Created symlink to /usr/local/bin/chrome-ws for easy access
• Zero dependencies - works with Node.js already in container

2. Added Claude Code Skills

• Installed browsing skill documentation in /root/.claude/skills/browsing/
• Includes:
  • SKILL.md - Claude Code integration guide with MCP tool usage
  • COMMANDLINE-USAGE.md - CLI reference
  • EXAMPLES.md - Practical examples

3. Updated Container and Wrapper

• Bumped Dockerfile version: 1.0 → 1.1
• Bumped claude-browser wrapper: 1.0.0 → 1.1.0
• Updated startup info to mention chrome-ws capability
• Modified playbook to deploy all chrome-ws files and skills

Files Changed

M  files/opt/claude-browser/ccb-startup-info.txt
M  files/var/local/claude-yolo/Dockerfile.browser
M  files/var/local/claude-yolo/claude-browser
M  playbooks/imports/optional/common/play-install-claude-browser.yml
A  files/opt/claude-browser/chrome-ws/chrome-ws
A  files/opt/claude-browser/chrome-ws/chrome-ws-lib.js
A  files/opt/claude-browser/skills/browsing/SKILL.md
A  files/opt/claude-browser/skills/browsing/COMMANDLINE-USAGE.md
A  files/opt/claude-browser/skills/browsing/EXAMPLES.md

How to Use

After rebuilding the container (automatic on next ccb --rebuild):

1. Start ccb:

   ccb

2. Use chrome-ws directly:

   chrome-ws navigate 0 "https://example.com"
   chrome-ws extract 0 text "h1"

3. Or use via Claude with the browsing skill:

   • Claude will have access to the skill documentation
   • Can use the use_browser MCP tool mentioned in SKILL.md
   • chrome-ws serves as the reference implementation

Next Steps

Users should:

1. Run ccb --rebuild to rebuild the container with chrome-ws
2. Test chrome-ws functionality within the container
3. Use either Playwright MCP (high-level) or chrome-ws (low-level CDP) based on needs

Benefits Delivered

✅ Zero-dependency tool (no npm packages)
✅ Minimal output (text vs 100KB+ YAML from Playwright)
✅ Direct CDP access for advanced automation
✅ Complements Playwright MCP (not a replacement)
✅ Includes comprehensive Claude Code skill documentation
✅ Auto-deploys with Ansible playbook

Commit: b5bba5b