Browser Tools

Browser automation, debugging, and anti-detect browsing CLI. Provides:

• Chrome DevTools MCP wrapper — Snapshot-based page automation via chrome-devtools-mcp
• Persistent browser sessions — Long-lived Chrome instances with named profiles, daemon-based MCP reuse, and attach-to-running-browser support
• Frame-aware tools — Iframe/CDP frame tree management, execution context resolution, and storage inspection
• Interstitial detection — Multi-signal heuristic detection for Cloudflare, DataDome, Akamai, PerimeterX, Imperva, AWS WAF, and other challenge pages
• Camoufox anti-detect browsing — Fingerprint-injected Firefox-based browsing for bot-protected sites
• CPU profiling — Direct CDP-based JavaScript CPU profiling with threshold-triggered capture

Quick Start

Installation

# Using uv (recommended)
uv tool install browser-tools

# Or with pip
pip install browser-tools

Usage

# Run the CLI
browser-tools --help

# Navigate then snapshot. Pass --isolated (or --browser-url) so both commands
# reuse the SAME long-lived Chrome; a bare `browser-tools navigate` followed by
# a bare `browser-tools take-snapshot` would each spawn a throwaway browser and
# NOT share page or login state.
browser-tools --isolated navigate --url https://example.com
browser-tools --isolated take-snapshot

There is no --profile CLI flag. Named, login-bearing profiles are selected through a project config file (see Project Configuration) or the use_browser_session / attach_browser MCP tools. --isolated gives a dedicated persistent profile directory that is separate from named profiles.

Development setup

# Clone and install in editable mode
git clone https://github.com/dungle-scrubs/browser-tools.git
cd browser-tools
uv sync

Runtime requirements:

• Chrome Canary by default (the default channel is canary). Use another installed channel with --channel stable|beta|dev, e.g. --channel stable for regular Google Chrome.
• Node.js (>=20.19; Node 22+ recommended) for chrome-devtools-mcp
• Camoufox (camoufox fetch) for anti-detect Firefox workflows

Architecture

browser_tools_session.py     CLI entry point (argparse, command dispatch)
        |
        +-- browser_session.py       Tool-proxy session adapter (tool dispatch,
        |                           camoufox routing, auth-wall promotion)
        +-- chrome_config.py          MCP subprocess command builder
        +-- chrome_utils.py           MCP invocation, formatting, errors
        +-- mcp_response.py           Single owner of MCP response envelopes
        +-- tool_registry.py          Single source of truth for tool routing flags
        +-- persistent_browser.py     Chrome lifecycle: controller, reaper,
        |                           teardown, shared on-disk session layout
        |       +-- browser_state.py     Persisted state dataclasses
        |       +-- page_selection.py    Active-page tracking (restore, refresh, normalize)
        |       +-- mcp_session.py       Short-lived MCP session wrapper
        |       +-- daemon_client.py      Unix socket client
        |       +-- process_utils.py      Chrome process/port utilities
        |       +-- profile_catalog.py    Named-profile catalog & live discovery
        |       +-- session_store.py      Per-project session config & controller factories
        |       +-- mcp_daemon.py         Long-lived MCP daemon (dispatch_tool routes by registry flags)
        |               +-- mcp_broker.py      JSON-RPC-over-stdio request multiplexer
        |               +-- cdp_handler.py     CDP tool implementations
        |               +-- cdp_constants.py   Tuning constants (timeouts, thresholds)
        |               +-- cdp_client.py      CDP WebSocket client
        |               +-- frame_manager.py   Frame tree management
        |               +-- interstitial.py    Challenge detection
        |               +-- screenshot_utils.py Blank-frame detection
        +-- camoufox_session.py     Camoufox anti-detect wrapper
        +-- profiler.py            Standalone CPU profiler

Development

uv sync
uv run ruff check src/ tests/
uv run pytest

Project Configuration

Place a .browser-tools.json in your project root (searched upward from the project working directory):

{
  "preferredSession": {
    "mode": "headed-auth",
    "profile": "dev"
  }
}

This auto-selects a persistent headed browser session using the named profile.

The config is read either as a flat object or wrapped in a preferredSession (or preferred_session) key. Recognized fields:

Keeping login state across calls

Auth/login state lives in a Chrome profile directory and survives only while the same directory is reused. To keep a session logged in:

• Use a named profile (via the config above or use_browser_session(mode="headed-auth", profile="<name>")). Named profiles persist across restarts and are unaffected by headed↔headless switches, viewport, or which directory you invoke from.
• The default/isolated sessions are keyed per project and Chrome channel; they are not a stable place to keep a long-lived login.
• Camoufox persists login state only when you pass a profile to launch_camoufox; without it, every launch starts logged out.

License

MIT — see LICENSE.

Contributing

See CONTRIBUTING.md for development setup and guidelines. All contributors are expected to follow the Code of Conduct.

Security

Found a vulnerability? See SECURITY.md for responsible disclosure.