BrowseBot

AI-powered browser automation using natural language instructions

---

BrowseBot is a lightweight, developer-friendly Python library that lets you automate web browsing tasks using natural language instructions. Inspired by OpenClaw's browser capabilities but focused specifically on being a minimal, composable toolkit for browser automation.

Architecture

graph TD
    A[User Code] -->|natural language instruction| B[BrowseBot Core]
    B --> C[Task Planner]
    C -->|step list| D[Action Executor]
    D --> E[Playwright Browser]
    D --> F[Element Resolver]
    F -->|CSS/XPath selectors| E
    B --> G[Config Manager]
    G -->|pydantic settings| B
    E -->|page state| H[State Observer]
    H -->|extracted data| A

Loading

Features

• Natural language element selection — describe what you want to click, fill, or extract in plain English
• Multi-step task execution — give a high-level instruction and let BrowseBot figure out the steps
• Async-first design — built on asyncio and Playwright for non-blocking automation
• Screenshot capture — grab screenshots at any point for debugging or verification
• Configurable via environment — pydantic-based settings with .env support
• Retry logic built in — automatic retries with exponential backoff for flaky operations

Quickstart

Installation

pip install browsebot

Or install from source:

git clone https://github.com/officethree/BrowseBot.git
cd BrowseBot
make install

Basic Usage

import asyncio
from browsebot import BrowseBot

async def main():
    bot = BrowseBot()
    await bot.start()

    await bot.navigate("https://example.com")
    await bot.click("the main heading link")
    content = await bot.extract("the first paragraph")
    print(content)

    await bot.screenshot("result.png")
    await bot.stop()

asyncio.run(main())

Execute Complex Tasks

async def main():
    bot = BrowseBot()
    await bot.start()

    result = await bot.execute_task(
        "Go to Hacker News, find the top post, and extract its title and URL"
    )
    print(result)

    await bot.stop()

Configuration

Copy .env.example to .env and set your values:

cp .env.example .env

Variable	Default	Description
OPENAI_API_KEY	—	API key for LLM-powered element resolution
BROWSER_HEADLESS	true	Run browser in headless mode
LOG_LEVEL	INFO	Logging verbosity

Development

make install    # Install dependencies
make test       # Run tests
make lint       # Run linter

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE for details.

---

Built by Officethree Technologies | Made with ❤️ and AI