Metadata-Version: 2.5
Name: brosh
Version: 1.0.1
Summary: Browser screenshot tool using Playwright async API
Project-URL: Documentation, https://github.com/twardoch/brosh#readme
Project-URL: Issues, https://github.com/twardoch/brosh/issues
Project-URL: Source, https://github.com/twardoch/brosh
Author-email: Adam Twardoch <adam+github@twardoch.com>
License: MIT
License-File: LICENSE
Keywords: automation,browser,capture,mcp,playwright,screenshot,web
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.8.0
Requires-Dist: fire>=0.5.0
Requires-Dist: html2text>=2025.4.15
Requires-Dist: loguru>=0.7.0
Requires-Dist: pillow>=11.2.1
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: pyoxipng>=9.1.0
Provides-Extra: all
Requires-Dist: absolufy-imports>=0.3.1; extra == 'all'
Requires-Dist: autoflake>=2.3.0; extra == 'all'
Requires-Dist: coverage[toml]>=7.6.12; extra == 'all'
Requires-Dist: isort>=6.0.1; extra == 'all'
Requires-Dist: mypy>=1.15.0; extra == 'all'
Requires-Dist: myst-parser<4; extra == 'all'
Requires-Dist: pre-commit>=4.1.0; extra == 'all'
Requires-Dist: pyinstaller>=6.0.0; extra == 'all'
Requires-Dist: pytest-asyncio>=1.0.0; extra == 'all'
Requires-Dist: pytest-benchmark[histogram]>=5.1.0; extra == 'all'
Requires-Dist: pytest-cov==5.0.0; extra == 'all'
Requires-Dist: pytest-xdist>=3.6.1; extra == 'all'
Requires-Dist: pytest>=8.3.4; extra == 'all'
Requires-Dist: pyupgrade>=3.19.1; extra == 'all'
Requires-Dist: ruff>=0.9.7; extra == 'all'
Requires-Dist: setuptools>=70.0.0; extra == 'all'
Requires-Dist: sphinx-autodoc-typehints<3; extra == 'all'
Requires-Dist: sphinx-rtd-theme>=3.0.2; extra == 'all'
Requires-Dist: sphinx<8; extra == 'all'
Requires-Dist: uv>=0.2.0; extra == 'all'
Requires-Dist: uzpy>=1.0.0; extra == 'all'
Provides-Extra: binary
Requires-Dist: pyinstaller>=6.0.0; extra == 'binary'
Requires-Dist: setuptools>=70.0.0; extra == 'binary'
Provides-Extra: dev
Requires-Dist: absolufy-imports>=0.3.1; extra == 'dev'
Requires-Dist: autoflake>=2.3.0; extra == 'dev'
Requires-Dist: isort>=6.0.1; extra == 'dev'
Requires-Dist: mypy>=1.15.0; extra == 'dev'
Requires-Dist: pre-commit>=4.1.0; extra == 'dev'
Requires-Dist: pyupgrade>=3.19.1; extra == 'dev'
Requires-Dist: ruff>=0.9.7; extra == 'dev'
Requires-Dist: uv>=0.2.0; extra == 'dev'
Requires-Dist: uzpy>=1.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser<4; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints<3; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=3.0.2; extra == 'docs'
Requires-Dist: sphinx<8; extra == 'docs'
Provides-Extra: test
Requires-Dist: coverage[toml]>=7.6.12; extra == 'test'
Requires-Dist: pytest-asyncio>=1.0.0; extra == 'test'
Requires-Dist: pytest-benchmark[histogram]>=5.1.0; extra == 'test'
Requires-Dist: pytest-cov==5.0.0; extra == 'test'
Requires-Dist: pytest-xdist>=3.6.1; extra == 'test'
Requires-Dist: pytest>=8.3.4; extra == 'test'
Description-Content-Type: text/markdown

# brosh

<img src="docs/assets/icon.png" alt="A browser window unspooling a whole web page into one long scroll" width="180" align="right">

Full-page browser screenshots, from the command line or from your own code, with the pixels, the text, and the HTML all handed back together.

Brosh drives a real browser (Chrome, Edge, or Safari) via Playwright, scrolls through a page, and captures each section as an image — plus the visible text as Markdown and, if you want it, the underlying HTML. Built for AI agents that need to *see* a page, not just fetch its source.

- Scrolling capture: single shot, frame series, or animated PNG of the whole scroll
- Extracts visible text (Markdown) and optionally minified HTML alongside every screenshot
- CLI, sync/async Python API, and an MCP server for Claude and other AI tools
- Connects to your existing Chrome/Edge session (cookies, logins, extensions included) or launches a fresh one
- Cross-platform: macOS, Windows, Linux

## Quick Start

```bash
pip install brosh
playwright install
```

That second command matters: Playwright needs its own browser binaries, and `pip install brosh` doesn't fetch them. Skip it and every capture fails with a browser-not-found error.

Then:

```bash
brosh shot "https://example.com"
```

Screenshots land in `~/Pictures/brosh` by default, named `{domain}-{timestamp}-{scroll%}-{section}.png`.

## Installation

```bash
# uv (recommended)
uv tool install brosh

# pip
pip install brosh

# run without installing
uvx brosh shot "https://example.com"
```

Whichever route you pick, don't forget `playwright install` afterward.

See [Installation](https://twardoch.github.io/brosh/installation) for binary releases, pipx, and from-source setups.

## CLI Usage

```bash
# Basic capture
brosh shot "https://example.com"

# Animated PNG of the whole scroll
brosh shot "https://example.com" --output_format apng

# Custom viewport, JSON output with HTML included
brosh --width 1920 --height 1080 shot "https://example.com" --fetch_html --json > page.json

# Reuse a running browser instance across multiple shots
brosh --app chrome run
brosh --app chrome shot "https://example.com"
brosh --app chrome quit
```

Global options (`--app`, `--width`, `--height`, `--zoom`, `--output_dir`, `--subdirs`, `--verbose`, `--json`) go *before* the command; command options go after. Full option tables: [CLI Reference](https://twardoch.github.io/brosh/cli-reference).

## Python API

```python
from brosh import capture_webpage

result = capture_webpage(
    url="https://example.com",
    width=1280,
    height=720,
    output_format="jpg",
    scale=75,
)
for path, metadata in result.items():
    print(path, metadata["text"][:80])
```

```python
import asyncio
from brosh import capture_webpage_async

async def main():
    result = await capture_webpage_async(
        url="https://docs.python.org/3/",
        fetch_html=True,
        max_frames=3,
    )
    print(list(result))

asyncio.run(main())
```

Both APIs return a dict mapping saved file paths to metadata (`selector`, `text`, optionally `html`). Details and convenience functions: [Python API](https://twardoch.github.io/brosh/python-api).

## MCP Server Mode

Brosh ships an MCP server so AI tools can request a screenshot mid-conversation.

```bash
claude mcp add brosh -- brosh-mcp
```

Or drop this into your MCP client's config:

```json
{
  "mcpServers": {
    "brosh": {
      "command": "brosh-mcp"
    }
  }
}
```

Restart your client, then ask it to "use brosh to capture example.com and show me the text." Full setup, including `uvx`-based configs: [MCP Server Mode](https://twardoch.github.io/brosh/mcp-server).

## Documentation

Everything else — architecture, full command reference, output/JSON format, troubleshooting — lives at **[twardoch.github.io/brosh](https://twardoch.github.io/brosh/)**.

## License

MIT. See [LICENSE](LICENSE).

Built by [Adam Twardoch](https://github.com/twardoch) on [Playwright](https://playwright.dev/), [python-fire](https://github.com/google/python-fire), and [FastMCP](https://github.com/jlowin/fastmcp).
