# AGENTS.md

This file provides guidelines and commands for agentic coding tools working in this repository.

## Project Overview

This is a Rust implementation of Browser-Use, a library for making websites accessible to AI agents. It provides autonomous web automation through browser control, DOM extraction, and LLM integration.

## Build and Test Commands

### Building the Project
```bash
cargo build
cargo build --release  # Optimized release build
```

### Running Tests
```bash
# Run all tests
cargo test

# Run a single test (replace with actual test name)
cargo test test_name_here

# Run tests in a specific file
cargo test --lib browser::session
cargo test --test integration_test

# Run tests with output
cargo test -- --nocapture

# Run tests in release mode
cargo test --release
```

### Code Quality Checks
```bash
# Check code without building
cargo check

# Format code
cargo fmt

# Run lints
cargo clippy

# Check for unused dependencies
cargo machete  # if installed
```

### Documentation
```bash
# Generate documentation
cargo doc --open
```

## Code Style Guidelines

### Rust Edition
- Uses Rust 2024 edition
- Follow idiomatic Rust patterns and conventions

### Module Structure
- Each major component has its own module under `src/`
- Public modules use `pub mod` declarations in `mod.rs` files
- Re-export important types at the module level and in `src/lib.rs`

### Error Handling
- Use the `Result<T>` type alias defined in `error.rs` for all public functions
- Error types are defined using `thiserror` for proper error descriptions
- Use `?` operator for error propagation
- Avoid panic! in library code - handle errors gracefully

### Async Code
- Uses `tokio` as the async runtime
- Async functions use `async fn` syntax
- Use `.await` for async operations
- Prefer returning `Result<T>` from async functions

### Import Organization
- Standard library imports first, grouped by category
- External crates next, grouped by crate
- Internal modules last, grouped by module
- Use `use crate::` for internal imports
- Example:
```rust
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex};

use anyhow::Result;
use serde::{Deserialize, Serialize};
use tokio::time::{sleep, Duration};

use crate::browser::session::Browser;
use crate::error::Result as BrowserUseResult;
```

### Naming Conventions
- Functions and methods: snake_case
- Types and structs: PascalCase
- Constants: SCREAMING_SNAKE_CASE
- Private fields: snake_case with leading underscore if needed
- Modules: snake_case (directory and file names)

### Documentation
- All public modules, functions, and structs should have doc comments
- Use `//!` for module documentation
- Use `///` for item documentation
- Include examples in documentation where appropriate
- Document error conditions and behavior

### Testing
- Unit tests go in the same module with `#[cfg(test)]`
- Integration tests go in the `tests/` directory
- Test functions should use descriptive names starting with `test_`
- Use `tokio::test` for async tests
- Test fixtures should be minimal and focused

### Structs and Enums
- Use `#[derive(Debug)]` for most types
- Add `Clone`, `Copy`, `PartialEq`, `Eq` as appropriate
- Use `#[derive(Serialize, Deserialize)]` for data structures
- Enum variants should be descriptive
- Use `thiserror` for error enums

### Traits
- Define traits with clear purposes
- Use async traits with `async-trait` crate when needed
- Implement traits for external types when useful
- Document trait contract and invariants

### Dependencies
- Check `Cargo.toml` before adding new dependencies
- Prefer commonly used, well-maintained crates
- Keep dependencies minimal
- Use feature flags appropriately

### Performance
- Avoid unnecessary allocations
- Use references instead of copies when possible
- Consider using `Arc` for shared data in async contexts
- Profile performance-critical code

### Code Organization
- Keep functions focused and small (ideally under 50 lines)
- Extract helper functions when needed
- Group related functionality together
- Use consistent patterns across modules

## Important Notes

1. **CDP Integration**: The project uses Chrome DevTools Protocol (CDP) for browser automation
2. **LLM Integration**: Implement the ChatModel trait for your LLM provider
3. **Token Tracking**: The project tracks LLM token usage - maintain this in all changes
4. **Browser Lifecycle**: Ensure proper cleanup of browser resources in all code paths
5. **Error Recovery**: The agent system includes error recovery mechanisms
6. **Serialization**: Many data structures are serialized for LLM communication

## Common Patterns

### Async Resource Management
```rust
pub async fn example_function() -> Result<()> {
    let resource = create_resource().await?;
    
    // Use the resource
    
    Ok(()) // Resource is automatically dropped
}
```

### Error Handling
```rust
pub fn example_function() -> Result<OutputType> {
    let value = some_operation()?;
    let result = another_operation(value)?;
    
    Ok(result)
}
```

### Module Re-exports
```rust
pub mod service;
pub mod views;

pub use service::MainType;
pub use views::*;
```