The CLI 'run' command now supports BROWSER_USE_API_KEY as an LLM option,
using ChatBrowserUse which is optimized for browser automation tasks.
This aligns the CLI behavior with the documented supported models at
https://docs.browser-use.com/supported-models which shows ChatBrowserUse
as a valid LLM option using BROWSER_USE_API_KEY.
Changes:
- Add ChatBrowserUse as first LLM option in get_llm() when BROWSER_USE_API_KEY is set
- Update error message to mention BROWSER_USE_API_KEY
<!-- This is an auto-generated description by cubic. -->
## Summary by cubic
Adds a fast, persistent CLI for browser automation with a background
session server. Enables quick, multi-step workflows with commands for
navigation, interaction, tabs, screenshots, JavaScript, Python, and
agent tasks.
- **New Features**
- New "browser-use" CLI (aliases: bu, browser) with a session server
over Unix sockets/TCP for low-latency commands.
- Commands: open, state (LLM-style output), click, type, input, scroll,
back, screenshot, switch, close-tab, keys, select, eval, extract;
sessions, close (--all), and server status/stop/logs; JSON output
supported.
- Python execution with a persistent namespace and a browser helper
(goto, click, type, scroll, screenshot, html).
- Agent task runner (requires API key) with interactive API key prompt
and config storage.
- Browser modes: chromium (headed/headless), real Chrome with profiles,
and remote cloud; added CLI docs and Claude Code SKILL.md.
- **Migration**
- CLI entry points updated: use browser-use as the main command; legacy
TUI is now browser-use-tui.
- For remote mode and agent tasks, set BROWSER_USE_API_KEY or add
{"api_key": "..."} to ~/.config/browser-use/config.json.
<sup>Written for commit b6bdc17bcb.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
- State command outputs same format that browser-use agents see
- Added aliases: bu, browser (all work the same)
- Headed mode now correctly shows browser window
- Change main entry point to 'browser-use'
- Move TUI to 'browser-use-tui'
- Add README with human instructions
- Update SKILL.md references
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update custom tool registry documentation to clarify correct parameter
naming and function signatures.
The previous documentation incorrectly showed `browser: Browser` as an
injectable parameter for custom tools. The agent injects parameters by
name matching, so the correct parameter name is `browser_session:
BrowserSession`. This PR fixes this, recommends async functions, and
adds a "Common Pitfalls" section to guide users.
---
[Slack
Thread](https://browser-use.slack.com/archives/C08TZGLPLER/p1768767006926899?thread_ts=1768767006.926899&cid=C08TZGLPLER)
<a
href="https://cursor.com/background-agent?bcId=bc-a9112a17-72ed-4ef2-acba-8d9873477a89"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/open-in-cursor-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/open-in-cursor-light.svg"><img alt="Open in
Cursor"
src="https://cursor.com/open-in-cursor.svg"></picture></a> <a
href="https://cursor.com/agents?id=bc-a9112a17-72ed-4ef2-acba-8d9873477a89"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/open-in-web-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/open-in-web-light.svg"><img alt="Open in Web"
src="https://cursor.com/open-in-web.svg"></picture></a>
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Clarified custom tool docs to use the correct `browser_session:
BrowserSession` injection and recommend async functions with
`ActionResult`, preventing silent tool failures. Added warnings and a
Common Pitfalls section to make name-based parameter injection clear.
- **Bug Fixes**
- Fixed examples to use `browser_session: BrowserSession` (not `browser:
Browser`), return `ActionResult`, and be `async`.
- Added warnings about name-based injection and a Common Pitfalls
section with wrong/correct examples.
- Updated AGENTS.md and tools docs (add.mdx, basics.mdx) for
consistency.
<sup>Written for commit 1c70a9dbc5.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> Clarifies custom tool docs and examples to correctly use
`browser_session: BrowserSession`, `async` functions, and
`ActionResult`, reducing silent failures from name-based injection
mismatches.
>
> - Update examples in `AGENTS.md`, `docs/customize/tools/basics.mdx`,
and `docs/customize/tools/add.mdx` to replace `browser: Browser` with
`browser_session: BrowserSession`, switch to `async`, and return
`ActionResult`
> - Add prominent warnings about name-based parameter injection and a
new **Common Pitfalls** section with wrong/correct examples
> - Minor note updates to reference deterministic Actor actions via
`browser_session`
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
1c70a9dbc5. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
- Fix basics.mdx: change browser: Browser to browser_session: BrowserSession
- Fix basics.mdx: use async functions and proper ActionResult return type
- Add Warning about parameter name matching in basics.mdx
- Add Warning and Common Pitfalls section in add.mdx with clear examples
- Update AGENTS.md embedded docs to match
The agent injects special parameters by name matching, not by type.
Using incorrect parameter names (e.g., browser instead of browser_session)
causes tools to fail silently, which was a common user confusion.
Co-authored-by: mailmertunsal <mailmertunsal@gmail.com>
<!-- This is an auto-generated description by cubic. -->
## Summary by cubic
Generate TOTP codes only when the placeholder key ends with
"bu_2fa_code". This supports multiple 2FA secrets and avoids false
matches in secret replacement.
<sup>Written for commit dd8a63ce41.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated description by cubic. -->
## Summary by cubic
Updated aiohttp dependency to >=3.13.3 to fix conflicts with internal
libraries and ensure compatibility. Bumped package version to 0.11.3.
<sup>Written for commit e1ee8b753f.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
CDP's dispatchKeyEvent doesn't trigger beforeinput events that Draft.js
relies on for text input. This causes the first character to be dropped.
Solution: Detect Draft.js editors via specific DOM attributes (DraftEditor
class, data-contents, data-block, data-offset-key) and prepend a sacrifice
space character that Draft.js will drop, preserving the actual text.
<!-- This is an auto-generated description by cubic. -->
## Summary by cubic
Adds a menu-aware retry to agent reruns: if a menu item can’t be
matched, the agent re-opens the dropdown and retries quickly. This
reduces flaky failures in multi-level dropdown flows.
- **Bug Fixes**
- Detects menu openers (aria-haspopup, toggleSubMenu, expand-button,
role with aria-expanded).
- Detects menu items (menuitem roles, gw-action--inner, menu-related
classes, stable ax_name).
- Re-executes the opener step with a short delay and retries without
consuming a retry attempt.
- Improves logging and preserves existing backoff behavior.
- Adds unit tests for opener/item detection.
<sup>Written for commit 147db04c1c.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated description by cubic. -->
## Summary by cubic
Added an Environment Variables section to the Agent parameters docs that
lists all timeout env vars with defaults and clear descriptions, plus
example usage. This lets users tune agent and browser behavior and
troubleshoot slow networks or complex pages without code changes.
<sup>Written for commit b71894b97b.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated description by cubic. -->
## Summary by cubic
Made the Agent event bus stop timeout configurable via the
TIMEOUT_AgentEventBusStop env var (default 3s) to let tests and
deployments tune shutdown wait time. This connects to Linear 3076 by
allowing environments to adjust the idle wait instead of using a fixed
value.
<sup>Written for commit 9c042d7d98.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
- Added 'row', 'cell', 'gridcell' to interactive_roles in ClickableElementDetector
- Added 'row', 'cell', 'gridcell' to interactive_ax_roles in ClickableElementDetector
- Verified logic with isolated test case
Auto-generated PR for branch: fix-scroll-action
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> Unifies scrolling terminology and simplifies guidance to reduce
over-scrolling and clarify browser state output.
>
> - Rename `SCROLL`/"scroll containers" to `scroll element` across DOM
serialization (`serializer.py`), system/code prompts, and `ScrollAction`
docs/descriptions (`service.py`, `views.py`)
> - Simplify page info in `prompts.py`: output `<page_info>` as `X
above, Y below`; drop total pages; prepend `[Start of page]` only when
no content above
> - Streamline `<page_stats>`: remove scroll container count from
summary text; minor formatting/whitespace fixes across prompts
> - Update code-use/system prompts to reflect new marker `|scroll
element|` and tidy guidance/examples
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
6bccc224ca. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Standardize “scroll element” terminology and reduce over-priming about
scrolling to prevent unnecessary scroll actions and improve clarity in
browser state output.
- **Refactors**
- Renamed “SCROLL”/“scroll containers” to “scroll element” in DOM
serialization, tool docs, and code-use prompt.
- Trimmed scrolling guidance in system prompts (removed offscreen scroll
advice and pages=10 chaining examples).
- Simplified browser state: removed scroll_containers from stats; page
info now “X above, Y below”; only add “[Start of page]” when there’s no
content above.
- Minor phrasing and whitespace fixes across prompts.
<sup>Written for commit 6bccc224ca.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
When use_vision is set to False, screenshots should not be sent to the
judge LLM. This is a privacy concern as websites may contain sensitive
data that users explicitly do not want shared with LLMs.
Changes:
- Add use_vision parameter to construct_judge_messages()
- Only encode and include screenshots when use_vision is not False
- Pass self.settings.use_vision from _judge_trace() to construct_judge_messages()
- Add comprehensive tests for all use_vision modes
Fixes#3726
This PR upgrades the Recording Watchdog to listen for
`AgentFocusChangedEvent`. This change ensures that when the agent
switches tabs, the video recording follows the agent's view, thus
supporting multi-tab tasks. Additionally, the video recorder currently
spawns a new ffmpeg subprocess for every single frame, which creates
massive overhead due to process initialization and I/O piping. This was
an attempt to avoid using the PIL dependency, but ended up not being
worth it. This PR fixes that by using Pillow to handle resizing and
padding in-memory before passing the numpy array to the video writer,
which is significantly faster and CPU-friendly.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Enable multi-tab video recording by switching the screencast to the
focused tab. Speed up frame processing by using Pillow for in-memory
resize and padding instead of spawning ffmpeg per frame.
- **New Features**
- Listen for AgentFocusChangedEvent and switch screencast to the focused
target/session.
- Stop screencast on the previous session and ignore stale frames to
avoid race conditions.
- **Performance**
- Replace per-frame ffmpeg subprocess with PIL-based resize/padding and
direct numpy writes via imageio.
- Reduce CPU overhead and I/O; use BICUBIC resize and apply black
padding only when needed.
<sup>Written for commit d9943a0246.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> Enables recording to follow the focused tab and streamlines frame
processing for better performance and reliability.
>
> - **Multi-tab recording**: Listen to `AgentFocusChangedEvent`, switch
screencast to the focused session via `_start_screencast`, stop previous
session, and ignore stale frames in `on_screencastFrame`.
> - **Session management**: Track `_current_session_id` and cache
`_screencast_params`; reset state on stop.
> - **Performance**: In `video_recorder.py`, replace per-frame `ffmpeg`
subprocess with Pillow-based in-memory resize/padding and direct NumPy
writes to `imageio`; remove `imageio_ffmpeg`/`subprocess` usage.
> - **Compatibility**: Pre-pad to macro-block size and set writer
`pixelformat='yuv420p'` with `macro_block_size=None`.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
d9943a0246. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
<!-- This is an auto-generated description by cubic. -->
## Summary by cubic
Adds AX_NAME (accessible name) fallback to history rerun element
matching to reduce failures on dynamic pages. Improves reliability when
hashes or XPath change, especially in SPAs and menu UIs.
- **New Features**
- Added Level 4 AX_NAME matching before ATTRIBUTE in the fallback order:
EXACT → STABLE → XPATH → AX_NAME → ATTRIBUTE.
- AX_NAME matching requires the same node type; logs available ax_names
when no match is found.
- Updated MatchLevel enum to include AX_NAME=4 and ATTRIBUTE=5.
- Added CI tests covering success cases, node-type constraints, and
matching order.
- Tweaked example rerun timing (max_step_interval=20,
delay_between_actions=1).
- **Bug Fixes**
- Corrected match-level reporting to use ATTRIBUTE for attribute-based
matches.
<sup>Written for commit 2c06eabf5f.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated description by cubic. -->
## Summary by cubic
Add a warning to the Browser recording docs that video capture requires
optional dependencies, with install commands: pip install
"browser-use[video]" or pip install imageio[ffmpeg] numpy. Addresses
Linear 3803 by adding the missing dependency install alert to the
recording section.
<sup>Written for commit 4c151c214c.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
BouquetAntoine
