Browsing

Rust-native browser automation — 20+ CDP managers, MCP server, zero AI deps

🗺️ Where Does Browsing Fit?

Browsing gives you Playwright's feature coverage (dialogs, file choosers, device presets, permissions, HAR, tracing, touch, workers, service workers) in a Rust-native, zero-bloat package with an MCP server for LLM integration.

🎯 Key Features

🏗️ Architecture

• Trait-based — BrowserClient, DOMProcessor, ActionHandler for mocking and backends
• 20+ typed managers — Each wraps a CDP domain: Dialog, FileChooser, Permissions, HAR, Interceptor, Performance, Coverage, Tracing, Touch, Worker, ServiceWorker, Viewport (with device presets, color scheme, vision deficiency, locale), Auth, Console, Cookies, PDF
• Headless by default — 17+ lightweight Chrome flags; BrowserProfile::default() runs --headless=new
• Raw CDP access — Browser::raw_cdp_command() for anything the managers don't cover
• Zero AI dependencies — Pure Rust, no LLM lock-in

📦 Installation

As a Library

[dependencies]
browsing = "0.1"
tokio = { version = "1.40", features = ["full"] }

As a CLI Tool

cargo install --path . --bin browsing

As an MCP Server

cargo build --release --bin browsing-mcp

🚀 Quick Start

1️⃣ CLI Usage

# Run a browser automation task (headless by default)
browsing run "Navigate to example.com and extract content" --url https://news.ycombinator.com

# Run with visible browser
browsing run "Navigate to example.com and extract content" --url https://news.ycombinator.com --no-headless

# Launch a headless browser and get CDP URL (headless by default)
browsing launch

# Launch with visible browser
browsing launch --no-headless

# Connect to existing browser
browsing connect ws://localhost:9222/devtools/browser/abc123

📖 Full CLI Documentation

2️⃣ MCP Server Usage

Configure in Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "browsing": {
      "command": "/path/to/browsing/target/release/browsing-mcp",
      "env": {
        "BROWSER_USE_HEADLESS": "true"
      }
    }
  }
}

Then ask Claude:

"Navigate to rust-lang.org, get the links, follow the second link, and screenshot the main content area"

📖 Full MCP Documentation

3️⃣ Library Usage

use anyhow::Result;
use browsing::Browser;
use browsing::browser::BrowserProfile;

#[tokio::main]
async fn main() -> Result<()> {
    browsing::init();

    let mut browser = Browser::new(BrowserProfile::default());
    browser.start().await?;

    browser.navigate("https://example.com").await?;

    let title = browser.get_current_page_title().await?;
    println!("Title: {}", title);

    let _ = browser.stop().await;
    Ok(())
}

📖 Full Library Documentation

Browser Launch Options

use browsing::{Browser, BrowserProfile};

// Option 1: Auto-launch headless browser (default)
let profile = BrowserProfile::default(); // headless = true by default
let browser = Browser::new(profile);

// Option 2: Launch with visible browser
let profile = BrowserProfile::default().with_headless(false);
let browser = Browser::new(profile);

// Option 3: Connect to existing browser
let browser = Browser::new(BrowserProfile::default())
    .with_cdp_url("http://localhost:9222".to_string());

// Option 4: Custom browser executable
use browsing::browser::launcher::BrowserLauncher;
let launcher = BrowserLauncher::new(profile)
    .with_executable_path(std::path::PathBuf::from("/path/to/chrome"));

📚 Quick Example

use browsing::browser::{Browser, BrowserProfile};

#[tokio::main]
async fn main() -> browsing::Result<()> {
    let mut browser = Browser::new(BrowserProfile::default());
    browser.start().await?;

    browser.navigate("https://example.com").await?;

    // Use any manager
    let viewport = browser.viewport_manager()?;
    viewport.preset_device(&browsing::DevicePreset::iphone_15()).await?;

    // Or send raw CDP
    let result = browser
        .raw_cdp_command("Runtime.evaluate", json!({"expression": "1+1"}))
        .await?;

    Ok(())
}

More examples: See examples/ — device emulation, dialog handling, HAR capture, permissions, touch gestures, raw CDP access.

🏗️ Architecture

┌──────────┬──────────────┬────────────────────────┐
│ Browser  │ DOMProcessor │        Tools           │
│ (trait)  │   (trait)    │                        │
└────┬─────┴──────┬───────┴───────────────┬────────┘
     │            │                       │
┌────▼────┐  ┌───▼────┐       ┌─────────▼──────┐
│ Browser │  │ DomSvc │       │   Handlers     │
│ Session │  │        │       │ (nav, click,   │
│ + 20+   │  │ CDP    │       │  tabs, content)│
│ managers│  │ HTML   │       │                │
└─────────┘  └────────┘       └────────────────┘

See docs/ARCHITECTURE.md for full design.

📁 Project Structure

browsing/
├── src/
│   ├── agent/              # Agent view types (used by tools layer)
│   │   ├── views.rs        # Data types
│   │   └── memory.rs       # Session memory types
│   ├── browser/            # Browser management
│   │   ├── session.rs      # Browser session (BrowserClient impl)
│   │   ├── tab_manager.rs  # Tab operations
│   │   ├── navigation.rs   # Navigation operations
│   │   ├── screenshot.rs   # Screenshot operations
│   │   ├── cdp.rs          # CDP WebSocket client
│   │   ├── launcher.rs     # Browser launcher
│   │   ├── profile.rs      # Browser configuration
│   │   ├── auth.rs         # HTTP auth / proxy / extra headers
│   │   ├── console.rs      # Console log capture
│   │   ├── cookies.rs      # Cookie management
│   │   ├── coverage.rs     # JS/CSS coverage tracking
│   │   ├── dialog.rs       # Dialog handling (alert/confirm/prompt)
│   │   ├── download.rs     # Download monitoring
│   │   ├── filechooser.rs  # File chooser interception
│   │   ├── har.rs          # Network traffic HAR capture
│   │   ├── interceptor.rs  # Network request interception
│   │   ├── pdf.rs          # PDF export
│   │   ├── performance.rs  # Performance metrics
│   │   ├── permissions.rs  # Browser permissions API
│   │   ├── serviceworker.rs # Service worker management
│   │   ├── touch.rs        # Touch gesture emulation
│   │   ├── tracing.rs      # Chrome tracing / CPU profiling
│   │   ├── viewport.rs     # Viewport / device emulation
│   │   ├── worker.rs       # Web worker management
│   │   └── views.rs        # Data types
│   ├── dom/                # DOM processing
│   │   ├── processor.rs    # DOMProcessor trait impl
│   │   ├── serializer.rs   # Text serialization
│   │   ├── tree_builder.rs # DOM tree construction
│   │   ├── cdp_client.rs   # CDP wrapper for DOM
│   │   └── html_converter.rs # HTML to markdown
│   ├── tools/              # Action system
│   │   ├── service.rs      # Tools registry
│   │   ├── handlers/       # Action handlers
│   │   │   ├── navigation.rs
│   │   │   ├── interaction.rs
│   │   │   ├── tabs.rs
│   │   │   ├── content.rs
│   │   │   └── advanced.rs
│   │   └── params.rs       # Parameter extraction
│   ├── traits/             # Core trait abstractions
│   │   ├── browser_client.rs  # BrowserClient trait
│   │   └── dom_processor.rs   # DOMProcessor trait
│   ├── actor/              # Low-level interactions
│   │   ├── page.rs         # Page operations
│   │   ├── element.rs      # Element operations
│   │   ├── mouse.rs        # Mouse interactions
│   │   └── keyboard.rs     # Keyboard input
│   ├── config.rs           # Configuration
│   ├── error.rs            # Error types
│   ├── logging.rs          # Logging setup
│   ├── metrics.rs          # Metrics collection
│   ├── utils.rs            # Utilities
│   └── views.rs            # Shared data types
└── Cargo.toml

🧪 Testing

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_browser_navigation

# Run integration tests only
cargo test --test integration

Test Coverage

360+ tests, all passing, 0 ignored. Every manager has unit tests. Mock implementations for deterministic testing without real browsers.

⚠️ Data Retention

Browser data is never deleted to prevent accidental loss of real profiles. Temp directories in /tmp/browser-use-* are left for inspection; clean them manually.

rm -rf /tmp/browser-use-*

🔧 Configuration

use browsing::BrowserProfile;

let profile = BrowserProfile::default();          // headless, lightweight flags
let profile = BrowserProfile::default().with_headless(false); // visible
let profile = BrowserProfile {
    user_data_dir: Some("/path/to/profile".into()),
    ..Default::default()
};

📖 API Documentation

Generate and view API docs:

cargo doc --open