Browsegrab

browsegrab

한국어 문서 · llms.txt

Token-efficient browser agent for local LLMs — Playwright + accessibility tree + MarkGrab, MCP native.

browsegrab is a lightweight browser automation library designed for local LLMs (8B-35B parameters). It combines Playwright's accessibility tree with MarkGrab's HTML-to-markdown conversion to achieve 5-8x fewer tokens per step compared to alternatives like browser-use.

Features

• Token-efficient: ~500-1,500 tokens/step (vs 4,000-10,000 for browser-use)
• Local LLM first: Optimized for vLLM, Ollama, and OpenAI-compatible endpoints
• MCP native: Built-in MCP server with 8 browser automation tools
• MarkGrab integration: HTML → clean markdown for content extraction
• Accessibility tree + ref system: Stable element references (e1, e2, ...) without vision models
• Success pattern caching: Zero LLM calls on repeated workflows
• 5-stage JSON parser: Robust action parsing for local LLM outputs
• Minimal dependencies: Only playwright + httpx in core

Installation

pip install browsegrabplaywright install chromium

With optional features:

pip install browsegrab[mcp]      # MCP server supportpip install browsegrab[content]  # MarkGrab content extractionpip install browsegrab[cli]      # CLI with rich outputpip install browsegrab[all]      # Everything

Quick Start

Python API

from browsegrab import BrowseSession
async with BrowseSession() as session:    # Navigate and get accessibility tree snapshot    await session.navigate("https://example.com")    snap = await session.snapshot()    print(snap.tree_text)    # - heading "Example Domain" [level=1]    # - link "Learn more": [ref=e1]
    # Click using ref ID    result = await session.click("e1")    print(result.url)  # https://www.iana.org/help/example-domains
    # Type into search box    await session.navigate("https://en.wikipedia.org")    snap = await session.snapshot()    await session.type("e4", "Python programming", submit=True)
    # Extract compressed content (AX tree + markdown)    content = await session.extract_content()

CLI

# Accessibility tree snapshotbrowsegrab snapshot https://example.com
# JSON outputbrowsegrab snapshot https://example.com -f json
# Extract content (AX tree + markdown)browsegrab extract https://en.wikipedia.org/wiki/Python
# Agentic browse (requires LLM endpoint)browsegrab browse https://example.com "Find the about page"

MCP Server

browsegrab-mcp  # Start MCP server (stdio)

Claude Desktop / Cursor / VS Code config:

{  "mcpServers": {    "browsegrab": {      "command": "browsegrab-mcp"    }  }}

8 MCP tools: browser_navigate, browser_click, browser_type, browser_snapshot, browser_scroll, browser_extract_content, browser_go_back, browser_wait

How It Works

Agent Browse Loop

flowchart LR    A["🌐 URL + Goal"] --> B["Navigate"]    B --> C["AX Tree Snapshot\n~200–500 tokens"]    C --> D{"LLM\nDecision"}    D -->|"click / type / scroll"| E["Execute Action"]    E --> C    D -->|"goal reached"| F["Extract Content\n(MarkGrab)"]    F --> G["✅ Result"]

Token Efficiency

browsegrab separates structure (accessibility tree) from content (MarkGrab markdown), sending only what the LLM needs:

flowchart TD    A["Raw HTML"] --> B["Accessibility Tree"]    A --> C["MarkGrab Markdown"]    B --> D["Structure: ~200–500 tokens\nInteractive elements with ref IDs"]    C --> E["Content: ~300–800 tokens\nClean markdown · on-demand"]    D --> F["Combined: ~500–1,300 tokens/step\n⚡ 5–8× fewer than browser-use"]    E --> F

Token efficiency (measured)

Architecture

browsegrab/├── config.py                 # Dataclass configs (env var loading)├── result.py                 # Result types (ActionResult, BrowseResult, ...)├── session.py                # BrowseSession orchestrator├── browser/│   ├── manager.py            # Playwright lifecycle (async context manager)│   ├── snapshot.py           # Accessibility tree + ref system│   ├── selectors.py          # 4-strategy selector resolver│   └── actions.py            # navigate, click, type, scroll, go_back, wait├── dom/│   ├── ref_map.py            # ref ID ↔ element bidirectional mapping│   └── compress.py           # AX tree + MarkGrab → compressed context├── llm/│   ├── base.py               # LLMProvider ABC│   ├── provider.py           # vLLM, Ollama, OpenAI-compatible│   ├── prompt.py             # System prompts (~400 tokens)│   └── parse.py              # 5-stage JSON fallback parser├── agent/│   ├── history.py            # Sliding window history compression│   ├── cache.py              # Domain-based success pattern cache│   └── loop_guard.py         # Duplicate action detection├── __main__.py               # CLI (click)└── mcp_server.py             # FastMCP server (8 tools)

Configuration

All settings via environment variables (BROWSEGRAB_* prefix):

# BrowserBROWSEGRAB_BROWSER_HEADLESS=trueBROWSEGRAB_BROWSER_TIMEOUT_MS=30000
# LLM (for agentic browse)BROWSEGRAB_LLM_PROVIDER=vllm          # vllm | ollama | openaiBROWSEGRAB_LLM_BASE_URL=http://localhost:8000/v1BROWSEGRAB_LLM_MODEL=Qwen/Qwen3.5-32B-AWQ
# AgentBROWSEGRAB_AGENT_MAX_STEPS=10BROWSEGRAB_AGENT_ENABLE_CACHE=true

Part of the QuartzUnit Ecosystem

Development

git clone https://github.com/QuartzUnit/browsegrab.gitcd browsegrabpython -m venv .venv && source .venv/bin/activatepip install -e ".[dev]"playwright install chromium
# Unit tests (no browser needed)pytest tests/ -m "not e2e"
# Full suite including E2Epytest tests/ -v

License

MIT

_{Part of the QuartzUnit ecosystem — composable Python libraries for data collection, extraction, search, and AI agent safety.}