Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

installation instruction fixed (playwright package missing)

Gregor Žuničd3821c76d6ca
diff --git a/.cursor/rules/browser-use-rules.mdc b/.cursor/rules/browser-use-rules.mdc
index 9041d265d..86552b8fc 100644
--- a/.cursor/rules/browser-use-rules.mdc
+++ b/.cursor/rules/browser-use-rules.mdc
@@ -1,22 +1,24 @@
---
-description:
-globs:
+description:
+globs:
alwaysApply: true
---
+
## 🧠 General Guidelines for Contributing to `browser-use`
-**Browser-Use** is an AI agent that autonomously interacts with the web. It takes a user-defined task, navigates web pages using Chromium via Playwright, processes HTML, and repeatedly queries a language model (like `gpt-4o`) to decide the next action—until the task is completed.
+**Browser-Use** is an AI agent that autonomously interacts with the web. It takes a user-defined task, navigates web pages using Chromium via CDP, processes HTML, and repeatedly queries a language model (like `gpt-4o`) to decide the next action—until the task is completed.
### 🗂️ File Documentation
When you create a **new file**:
-* **For humans**: At the top of the file, include a docstring in natural language explaining:
+- **For humans**: At the top of the file, include a docstring in natural language explaining:
+
+ - What this file does.
+ - How it fits into the browser-use system.
+ - If it introduces a new abstraction or replaces an old one.
- * What this file does.
- * How it fits into the browser-use system.
- * If it introduces a new abstraction or replaces an old one.
-* **For LLMs/AI**: Include structured metadata using standardized comments such as:
+- **For LLMs/AI**: Include structured metadata using standardized comments such as:
```python
# @file purpose: Defines <purpose>
@@ -26,7 +28,7 @@ When you create a **new file**:
### 🧰 Development Rules
-* ✅ **Always use [`uv`](mdc:https:/github.com/astral-sh/uv) instead of `pip`**
+- ✅ **Always use [`uv`](mdc:https:/github.com/astral-sh/uv) instead of `pip`**
For deterministic and fast dependency installs.
```bash
@@ -35,14 +37,15 @@ source .venv/bin/activate
uv sync
```
-* ✅ **Use real model names**
+- ✅ **Use real model names**
Do **not** replace `gpt-4o` with `gpt-4`. The model `gpt-4o` is a distinct release and supported.
-* ✅ **Type-safe coding**
+- ✅ **Type-safe coding**
Use **Pydantic v2 models** for all internal action schemas, task inputs/outputs, and controller I/O. This ensures robust validation and LLM-call integrity.
-* ✅ **Pre-commit formatting**
-ALWAYS make sure to run pre-commit before making PRs.
+- ✅ **Pre-commit formatting**
+ ALWAYS make sure to run pre-commit before making PRs.
+
---
## ⚙️ Adding New Actions
@@ -64,8 +67,8 @@ async def search_web(query: str, page: Page):
### Notes:
-* Use descriptive names and docstrings for each action.
-* Prefer returning `ActionResult` with structured content to help the agent reason better.
+- Use descriptive names and docstrings for each action.
+- Prefer returning `ActionResult` with structured content to help the agent reason better.
---
diff --git a/README.md b/README.md
index a277ed928..5f9172de2 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,6 @@
[![Twitter Follow](https://img.shields.io/twitter/follow/Magnus?style=social)](https://x.com/intent/user?screen_name=mamagnus00)
[![Weave Badge](https://img.shields.io/endpoint?url=https%3A%2F%2Fapp.workweave.ai%2Fapi%2Frepository%2Fbadge%2Forg_T5Pvn3UBswTHIsN1dWS3voPg%2F881458615&labelColor=#EC6341)](https://app.workweave.ai/reports/repository/org_T5Pvn3UBswTHIsN1dWS3voPg/881458615)
-
🌤️ Want to skip the setup? Use our <b>[cloud](https://cloud.browser-use.com)</b> for faster, scalable, stealth-enabled browser automation!
# Quick start
@@ -28,7 +27,7 @@ pip install browser-use
Install the browser:
```bash
-playwright install chromium --with-deps --no-shell
+uvx playwright install chromium --with-deps --no-shell
```
Spin up your agent:
@@ -131,38 +130,38 @@ from browser_use.mcp.client import MCPClient
async def main():
# Initialize controller
controller = Controller()
-
+
# Connect to multiple MCP servers
filesystem_client = MCPClient(
server_name="filesystem",
command="npx",
args=["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/documents"]
)
-
+
github_client = MCPClient(
- server_name="github",
+ server_name="github",
command="npx",
args=["-y", "@modelcontextprotocol/server-github"],
env={"GITHUB_TOKEN": "your-github-token"}
)
-
+
# Connect and register tools from both servers
await filesystem_client.connect()
await filesystem_client.register_to_controller(controller)
-
+
await github_client.connect()
await github_client.register_to_controller(controller)
-
+
# Create agent with MCP-enabled controller
agent = Agent(
task="Find the latest pdf report in my documents and create a GitHub issue about it",
llm=ChatOpenAI(model="gpt-4.1-mini"),
controller=controller # Controller has tools from both MCP servers
)
-
+
# Run the agent
await agent.run()
-
+
# Cleanup
await filesystem_client.disconnect()
await github_client.disconnect()
@@ -172,7 +171,6 @@ asyncio.run(main())
See the [MCP documentation](https://docs.browser-use.com/customize/mcp-server) for more details.
-
# Vision
Tell your computer what to do, and it gets it done.
@@ -180,20 +178,25 @@ Tell your computer what to do, and it gets it done.
## Roadmap
### Agent
+
- [ ] Make agent 3x faster
- [ ] Reduce token consumption (system prompt, DOM state)
### DOM Extraction
+
- [ ] Enable interaction with all UI elements
- [ ] Improve state representation for UI elements so that any LLM can understand what's on the page
### Workflows
+
- [ ] Let user record a workflow - which we can rerun with browser-use as a fallback
### User Experience
+
- [ ] Create various templates for tutorial execution, job application, QA testing, social media, etc. which users can just copy & paste.
### Parallelization
+
- [ ] Human work is sequential. The real power of a browser agent comes into reality if we can parallelize similar tasks. For example, if you want to find contact information for 100 companies, this can all be done in parallel and reported back to a main agent, which processes the results and kicks off parallel subtasks again.
## Contributing