clawdesk-browser

Headless browser automation tools for web scraping, page interaction, and content extraction. Provides browser tools that agents can use for web-based tasks.

Dependencies

Internal: clawdesk-types

External: tokio, serde, tracing, thiserror

Modules

Module	Description
browser	Headless browser instance management
page	Page navigation, interaction, and content extraction
screenshot	Screenshot capture and image generation
tools	Agent-callable browser tools (navigate, click, extract, etc.)

Key Types

/// Headless browser instance
pub struct Browser {
    config: BrowserConfig,
}

impl Browser {
    pub async fn new(config: BrowserConfig) -> Result<Self, BrowserError> { /* ... */ }

    /// Navigate to a URL and return page content
    pub async fn navigate(&self, url: &str) -> Result<Page, BrowserError> { /* ... */ }

    /// Take a screenshot of the current page
    pub async fn screenshot(&self, page: &Page) -> Result<Vec<u8>, BrowserError> { /* ... */ }
}

/// Browser configuration
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BrowserConfig {
    pub headless: bool,
    pub timeout_secs: u64,
    pub user_agent: Option<String>,
    pub viewport: Viewport,
}

/// A loaded web page
pub struct Page {
    pub url: String,
    pub title: String,
    pub content: String,
    pub html: String,
}

impl Page {
    /// Extract text content from the page
    pub fn text(&self) -> &str { &self.content }

    /// Extract content matching a CSS selector
    pub fn select(&self, selector: &str) -> Vec<String> { /* ... */ }

    /// Click an element
    pub async fn click(&self, selector: &str) -> Result<(), BrowserError> { /* ... */ }

    /// Fill a form field
    pub async fn fill(&self, selector: &str, value: &str) -> Result<(), BrowserError> { /* ... */ }
}

/// Browser tools exposed to agents
pub struct BrowserTools;

impl BrowserTools {
    pub fn navigate_tool() -> ToolDefinition { /* ... */ }
    pub fn extract_tool() -> ToolDefinition { /* ... */ }
    pub fn screenshot_tool() -> ToolDefinition { /* ... */ }
    pub fn click_tool() -> ToolDefinition { /* ... */ }
}

Example Usage

use clawdesk_browser::{Browser, BrowserConfig, Viewport};

let browser = Browser::new(BrowserConfig {
    headless: true,
    timeout_secs: 30,
    user_agent: None,
    viewport: Viewport { width: 1280, height: 720 },
}).await?;

let page = browser.navigate("https://example.com").await?;
println!("Title: {}", page.title);
println!("Text: {}", page.text());

// Extract specific elements
let headings = page.select("h1, h2, h3");
for heading in headings {
    println!("Heading: {heading}");
}

// Screenshot
let screenshot = browser.screenshot(&page).await?;

warning

Browser automation requires a compatible browser runtime (Chromium). The Docker image includes this by default; for local development, install Chromium or Chrome.