# CODEBUDDY.md This file provides guidance to CodeBuddy Code when working with code in this repository.

## Project Overview

`browser-use` is a Rust library for browser automation via Chrome DevTools Protocol (CDP). It provides:

- A browser session manager wrapping `headless_chrome`
- A tool system for common browser operations (navigate, click, input, extract, etc.)
- DOM extraction with indexed interactive elements
- An MCP (Model Context Protocol) server for AI-driven browser automation

## Common Commands

### Building

```bash
cargo build                    # Build library
cargo build --bin mcp-server  # Build MCP server binary
cargo build --release         # Production build
```

### Testing

```bash
cargo test                     # Run unit tests only
cargo test -- --ignored        # Run integration tests (requires Chrome installed)
cargo test dom_integration     # Run specific test file
```

### Running

```bash
cargo run --bin mcp-server              # Run MCP server (headless)
cargo run --bin mcp-server -- --headed  # Run with visible browser
```

### Development

```bash
cargo check        # Fast compile check
cargo clippy       # Linting
cargo fmt          # Format code
```

## Architecture

### Module Structure

The codebase is organized into five main modules:

**1. `browser/` - Browser Management**

- `session.rs`: `BrowserSession` wraps `headless_chrome::Browser` and manages tabs
- `config.rs`: `LaunchOptions` and `ConnectionOptions` for browser initialization
- Key APIs: `launch()`, `connect()`, `navigate()`, `extract_dom()`

**2. `dom/` - DOM Extraction & Indexing**

- `tree.rs`: `DomTree` represents page structure with indexed interactive elements
- `element.rs`: `ElementNode` is a serializable DOM node with visibility/interactivity metadata
- `extract_dom.js`: JavaScript injected into pages to extract DOM as JSON
- Flow: JS extraction → JSON → `ElementNode` tree → index interactive elements → `DomTree.selectors`

**3. `tools/` - Browser Automation Tools**

- Each tool is in its own file: `navigate.rs`, `click.rs`, `input.rs`, `extract.rs`, `screenshot.rs`, `evaluate.rs`, `wait.rs`
- All tools implement the `Tool` trait with type-safe parameter structs (e.g., `ClickParams`, `NavigateParams`)
- `ToolRegistry` manages tools and executes them with `ToolContext` (contains `BrowserSession` + optional cached `DomTree`)
- Element selection: tools accept either CSS selectors OR numeric indices (from `DomTree`)
- **⚠️ IMPORTANT: When adding a new tool, remember to register it in `src/mcp/mod.rs` using the `register_mcp_tools!` macro**

**4. `mcp/` - Model Context Protocol Server**

- `handler.rs`: `BrowserServer` wraps `BrowserSession` in `Arc<Mutex<>>` for thread-safe MCP access
- `mod.rs`: Uses `register_mcp_tools!` macro to auto-generate MCP tool wrappers from internal tools
- Runs as stdio-based MCP server via `rmcp` crate

**5. `error.rs` - Error Handling**

- `BrowserError` enum with variants for launch/connection/navigation/DOM/tool failures
- Converts `anyhow::Error` from `headless_chrome` and `serde_json::Error`

### Key Design Patterns

**Tool System**: The `Tool` trait uses associated types for compile-time parameter validation:

```rust
trait Tool {
    type Params: Serialize + Deserialize + JsonSchema;
    fn execute_typed(&self, params: Self::Params, context: &mut ToolContext) -> Result<ToolResult>;
}
```

**DOM Indexing**: Interactive elements get numeric indices for easier LLM targeting:

- Extract DOM → Traverse tree → Detect interactive elements (buttons, links, inputs)
- Assign indices only to visible + interactive elements
- Tools can use `{"index": 5}` instead of complex CSS selectors

**Dual Element Selection**: Tools accept both:

- CSS selector: `{"selector": "#submit-btn"}`
- Numeric index: `{"index": 5}` (requires DOM extraction first)

**MCP Integration**: The `register_mcp_tools!` macro automatically wraps internal tools:

- Takes tool type + MCP name + description
- Generates async function that locks session, calls tool, converts result
- All registered in `tool_router` for `rmcp` dispatcher

### Testing Approach

- Unit tests in each module for struct/enum behavior
- Integration tests in `tests/` require Chrome (`#[ignore]` attribute)
- Run ignored tests with: `cargo test -- --ignored`
- Tests use `data:` URLs to avoid network dependencies

## Important Implementation Notes

- The MCP server runs in a single-threaded Tokio runtime (`#[tokio::main(flavor = "current_thread")]`)
- `BrowserSession` holds a `headless_chrome::Browser` and manages one active tab at a time
- DOM extraction executes JavaScript in the browser and parses the returned JSON
- All tools work on the active tab; use `switch_tab()` to change context
- Element indices are only valid for the specific DOM extraction they came from
- Re-extracting the DOM rebuilds the selector list on `DomTree` and reassigns all indices
- **When writing JavaScript to be executed in the browser, always use `JSON.stringify()` to ensure the result is returned properly** - this prevents issues with complex objects and ensures consistent serialization

## Crate Dependencies

- `headless_chrome`: CDP client for Chrome/Chromium automation
- `rmcp`: Model Context Protocol (MCP) server framework
- `serde`/`serde_json`: JSON serialization for params and DOM
- `schemars`: JSON Schema generation for tool parameters
- `thiserror`: Ergonomic error definitions
- `tokio` (optional): Async runtime for MCP server
- `clap` (optional): CLI arg parsing for MCP server binary

## File Locations

- MCP server binary: `src/bin/mcp_server.rs`
- DOM extraction script: `src/dom/extract_dom.js` (embedded via `include_str!`)
- Integration tests: `tests/dom_integration.rs`