brosh CLAUDE.md

=== USER INSTRUCTIONS ===

brosh is a browser screenshot tool that captures scrolling screenshots of webpages using Playwright's async API. The tool has been refactored from a monolithic script into a modular Python package with the following structure:

src/brosh/
├── __init__.py      # Package exports
├── __main__.py      # CLI entry point
├── api.py           # Public API functions (sync and async)
├── cli.py           # Fire-based CLI interface
├── tool.py          # Main BrowserScreenshotTool class
├── browser.py       # Browser management utilities
├── capture.py       # Screenshot capture logic
├── image.py         # Image processing utilities
├── models.py        # Data models and enums
├── mcp.py           # MCP server functionality
└── texthtml.py      # HTML/text processing utilities

Legacy implementation:

• brosh_sel.py: Selenium-based synchronous implementation (deprecated)

Commands

Installation

# Install the package in development mode
pip install -e .
# Or install from PyPI (when published)
pip install brosh
# Install Playwright browsers
playwright install

Running the Tools

The package provides two command-line tools:

• brosh: Main CLI for screenshot capture
• brosh-mcp: MCP server for AI tool integration

Primary Tool (brosh)

# Basic usage
brosh shot "https://example.com"
# Start browser in debug mode
brosh --app chrome run
# Take screenshots with options
brosh --app chrome --width 1920 --height 1080 shot "https://example.com" --scroll_step 80 --format png
# Run MCP server
brosh mcp
# Or use the dedicated command
brosh-mcp

Development Mode

# Run from source during development
python -m brosh shot "https://example.com"
# Or use the development script (if maintaining the monolithic version)
./brosh.py shot "https://example.com"

Architecture

Module Structure

The project has been refactored into a modular architecture:

• api.py: Public API with capture_webpage (sync) and capture_webpage_async (async) functions
• browser.py: BrowserManager class handles browser detection, launching, and connection
• capture.py: CaptureManager class handles screenshot capture and scrolling logic
• image.py: ImageProcessor class handles image scaling, conversion, and APNG creation
• tool.py: BrowserScreenshotTool orchestrates the other modules
• cli.py: BrowserScreenshotCLI provides the Fire-based command interface
• mcp.py: FastMCP server implementation for AI tool integration
• models.py: Data models including ImageFormat enum and MCP-specific types
• texthtml.py: DOMProcessor for HTML compression and text extraction