Wave Ecosystem Guide

Description

The Wave ecosystem is a collection of browser automation tools built in 100% Python. No Node.js, no Chromium download, no Selenium, no Playwright. This skill helps you choose the right Wave tool for each use case and understand how the pieces fit together.

When to Invoke

• Choosing between cdpwave, bidiwave, wavexis, or wavexis-mcp for a browser automation task
• Understanding the Wave ecosystem architecture and how the repos relate
• Migrating from Playwright, Selenium, pyppeteer, or Puppeteer to the Wave ecosystem
• Deciding between CDP (Chromium-specific) and BiDi (W3C cross-browser) backends
• Setting up browser automation in a Python project for the first time
• Answering "which Wave tool should I use for X?"

1. Architecture

wavexis-mcp (MCP server, 220 tools, 13 tiers)
└─ wraps → wavexis (CLI, 130+ commands, 480+ sub-commands)
               ├─ cdpwave (CDP backend, 60 domains, 689 methods)
               └─ bidiwave (BiDi backend, W3C cross-browser)

Each layer builds on the one below:

2. Tool Selection

Decision Tree

What do you need?
│
├── LLM / AI agent needs to control a browser
│   └──► wavexis-mcp
│        (MCP server, 220 tools, works with Claude, Cursor, Windsurf, VS Code)
│
├── Quick one-off task from the command line
│   ├── Screenshot / PDF / scrape a single page
│   ├── CI assertion (title contains X, exit code 0/1)
│   ├── Batch process multiple URLs
│   └──► wavexis CLI
│        (130+ commands, REPL, multi-action YAML, stealth, serve mode)
│
├── Programmatic browser control in Python
│   ├── Chrome / Edge only
│   │   └──► cdpwave
│   │        (60 CDP domains, 689 typed methods, no driver needed)
│   │
│   ├── Cross-browser (Chrome + Firefox + Edge)
│   │   └──► bidiwave
│   │        (W3C WebDriver BiDi, 12 modules, Pydantic v2 models)
│   │
│   └── Both backends with a unified API
│       └──► wavexis as a library
│            (AbstractBackend interface, switch with --backend bidi)
│
└── Not sure?
    └──► Start with wavexis CLI for quick tasks
         Move to cdpwave/bidiwave when you need programmatic control
         Move to wavexis-mcp when you need LLM integration

Quick Reference

3. Backend Comparison: CDP vs BiDi

When to use which

• cdpwave — You only target Chrome/Edge and need maximum CDP coverage (debugging, profiling, heap snapshots, DOM debugger, WebAuthn, Bluetooth, Cast)
• bidiwave — You need cross-browser support (Firefox), W3C standard compliance, or network interception with a clean API
• Both — Use wavexis which abstracts both behind a unified AbstractBackend interface. Switch with --backend bidi

4. Installation

cdpwave (CDP backend)

pip install cdpwave

Requirements: Python 3.11+, a Chromium-based browser already installed.

bidiwave (BiDi backend)

pip install bidiwave

Requirements: Python 3.11+, a BiDi-capable browser endpoint (ChromeDriver, Firefox with --remote-debugging-port, or EdgeDriver).

wavexis (CLI)

# CDP backend (default, recommended)
pip install wavexis[cdp]

# BiDi backend
pip install wavexis[bidi]

# Serve mode + image extras
pip install wavexis[cdp,serve,image]

wavexis-mcp (MCP server)

pip install wavexis-mcp[cdp]

# Or run without installing
uvx wavexis-mcp --caps all

5. Quick Start Examples

cdpwave — Screenshot and evaluate

import asyncio
from cdpwave import CDPClient

async def main() -> None:
    async with await CDPClient.launch(headless=True) as client:
        session = await client.new_page("https://example.com")
        result = await session.runtime.evaluate("document.title", return_by_value=True)
        print(result["result"]["value"])  # "Example Domain"
        await session.close()

asyncio.run(main())

bidiwave — Cross-browser evaluate

import asyncio
from bidiwave import BiDiClient, StringValue

async def main():
    async with await BiDiClient.connect("ws://localhost:9515/session") as client:
        async with await client.browsing.open("https://example.com") as page:
            result = await page.evaluate("document.title")
            match result:
                case StringValue(value=title):
                    print(f"Title: {title}")

asyncio.run(main())

wavexis CLI — Screenshot and scrape

# Screenshot
wavexis screenshot https://example.com -o out.png

# Full-page screenshot
wavexis screenshot https://example.com -o full.png --full-page

# Scrape content
wavexis scrape https://example.com --selector "article"

# Evaluate JavaScript
wavexis eval https://example.com -e "document.title"

wavexis-mcp — MCP config

{
  "mcpServers": {
    "wavexis": {
      "command": "uvx",
      "args": ["wavexis-mcp", "--caps", "all"]
    }
  }
}

Then ask your LLM: "Take a full-page screenshot of https://example.com"

6. Migration Paths

From Playwright

Key differences:

• No browser download (uses your existing Chrome/Edge)
• No Node.js required (100% Python)
• CDP + BiDi dual backend (Playwright is CDP-only for Chromium)
• 220 MCP tools vs ~21 in Playwright MCP

From Selenium

Key differences:

• No ChromeDriver needed for CDP (direct WebSocket)
• No Selenium Server / Grid needed (wavexis serve mode)
• Async-first (Selenium is sync)
• Full CDP domain access (Selenium hides most CDP)

From pyppeteer / pychrome

See references/migration-pyppeteer.md for detailed migration guide.

7. Feature Parity Matrix

8. Ecosystem Links

9. Best Practices

• Start simple — Use wavexis CLI for one-off tasks before writing Python scripts
• Choose backend early — CDP for Chrome-only, BiDi for cross-browser. Switch in wavexis with --backend bidi
• Use stealth for scraping — --stealth hides navigator.webdriver and fakes browser fingerprints
• Leverage capability tiers — In wavexis-mcp, start with --caps core (72 tools) and add tiers as needed to save tokens
• Use multi-action YAML — Chain actions in a single browser session to avoid launch overhead
• Close sessions — Always close sessions in wavexis-mcp to avoid resource leaks
• Use the escape hatch — session.send("Any.CDPMethod", params) in cdpwave for any uncovered CDP method
• Preload scripts for monitoring — Inject JS before page load with bidiwave's client.preload.add_preload_script()
• CI assertions — Use --assert with eval for CI gates that pass/fail based on page state
• Action caching — Use --cache-ttl to avoid re-analyzing pages in repeated multi-action workflows

10. Common Pitfalls

11. References

• references/ecosystem-comparison.md — Full feature comparison table with all 220 MCP tools
• references/decision-tree.md — Detailed flowchart for tool and backend selection
• references/migration-pyppeteer.md — Step-by-step migration from pyppeteer/pychrome to cdpwave
• assets/ecosystem-cheatsheet.md — Quick reference card for printing
• Related skills: wavexis-cli-automation, wavexis-mcp-agent-integration, cdpwave-testing, bidiwave-cross-browser