so it can return path if it needs; resolves 833 failures where agents
tried write_file with .png and got rejected
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added an optional file_name to the screenshot action so you can save a
PNG and get the path back. Keeps the old “include in next observation”
behavior and avoids failures where agents tried write_file with .png.
- **New Features**
- Added ScreenshotAction with file_name; sanitizes name and appends .png
if missing.
- When provided, saves viewport screenshot to the workspace directory
and returns the path in attachments; when omitted, sets
include_screenshot for the next observation.
<sup>Written for commit a81a493794.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Add `<critical_reminders>` section (12 items) to `system_prompt.md`
and `system_prompt_no_thinking.md` — covers action verification, popup
handling, filter application, loop avoidance, and max_steps behavior
- Add `<error_recovery>` section (8 items) — structured escalation from
screenshot verification through alternative approaches
- Add 3 new `<browser_rules>`: popup/modal handling, 403/bot detection
fallback, and unproductive loop detection
- Add action verification guidance to `<action_rules>` — verify state
between consequential actions
- Add 5 failure-mode memory examples (filter, popup, failed click,
captcha, 403) and 2 next_goal examples (close popup, apply filter)
- Strengthen filter rule from "try to apply filters" to "ALWAYS look for
filter/sort options FIRST"
- Fix captcha rule to include step budget ("3-4 steps") and fix
"trajactory" typo
All changes already existed in the anthropic prompt variants — this PR
brings the standard prompts (used by OpenAI, Gemini, and other
non-Anthropic models) to parity.
## Test plan
- [ ] Run `uv run pytest -vxs tests/ci` to confirm no regressions
- [ ] Verify `system_prompt.md` and `system_prompt_no_thinking.md` now
contain all sections present in their anthropic counterparts
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Backported robustness rules from the Anthropic prompt variants to the
standard prompts to improve web navigation reliability and reduce
unproductive loops.
- **New Features**
- Added <critical_reminders> (12 items) and <error_recovery> (8 items)
to both standard prompts.
- Browser rules: popup/modal handling, 403/bot detection fallback, and
loop detection.
- Action rules: verify state between consequential actions before
proceeding.
- Guidance: ALWAYS apply filters first when criteria exist; captcha
effort capped at 3–4 steps; fixed “trajectory” typo.
- Examples: added failure-mode memory entries and next_goal examples
(close popup, apply filter).
<sup>Written for commit 996c2cb38d.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- **Auto-sanitize filenames** instead of rejecting them — special chars
get stripped. Eliminates 148+ failures from filename format errors where
agents enter 15-30 retry loops.
- **Specific error messages for binary extensions** (.png, .jpg, .mp4,
etc.) telling the agent screenshots are automatic and it should not save
them as files. Stops 833+ infinite retry loops.
- **Allow dots, spaces, and parentheses in filenames** (e.g.
`report.v2.md`, `data (1).csv`, `my file.txt`)
- **Add .html and .xml** as supported file types — agents commonly
generate these
- **Improved tool description** with explicit filename rules, supported
extensions, and clarification that default mode overwrites (use
`append=true` to add content)
## Context
Analysis of judgements over 2 weeks revealed file-related failures as a
major pain point. The `write_file` tool was responsible due to strict
filename validation and failures where agents tried to save screenshots
as .png files. Agents entered severe retry loops (15-30+ identical
failed attempts) because:
1. The error message was generic and didn't explain what was wrong
2. The tool description didn't list filename rules
3. Valid-looking filenames with dots/spaces were rejected
4. Binary file attempts got the same generic error, causing endless
retries
## Test plan
- [x] All 55 existing filesystem tests pass
- [x] New tests for filename sanitization (spaces→hyphens, special char
removal, collapse hyphens, fallback name)
- [x] New tests for binary extension error messages (.png, .jpg)
- [x] New tests for unsupported extension error messages (.css, .doc)
- [x] New tests for HTML file writing
- [x] New tests for dots in filename (report.v2.md,
data.backup.2024.csv)
- [x] Pre-commit linting (ruff format, ruff check, pyright) all pass
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Medium Risk**
> Behavior of `write_file`/`append_file`/`replace_file_str` changes by
auto-sanitizing filenames and allowing additional characters/extensions,
which could alter file names created and downstream expectations. Risk
is mitigated by basename-only handling and expanded test coverage, but
this touches a core agent tool path.
>
> **Overview**
> **Improves file-writing ergonomics and failure recovery for agents.**
Filename validation is relaxed to allow dots/spaces/parentheses (while
still enforcing a supported extension), and invalid names are now
auto-sanitized (e.g., spaces→hyphens, unsupported chars removed) before
failing.
>
> **Adds clearer feedback and broader text support.**
`write_file`/`append_file`/`replace_file_str` now return specific,
actionable errors for missing/unsupported extensions and explicitly
reject common binary/image formats. The filesystem adds `.html` and
`.xml` file types and updates state restore logic to include them, and
the `write_file` tool description is updated to document overwrite
behavior, filename rules, and supported extensions.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
5e25d92bef. 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 step budget awareness to the agent so it warns at 75% of the step
limit and encourages saving partial results and calling done early.
Aligns with IMP-7a.
- **New Features**
- Injects a budget warning at >=75% of max steps (except the last step).
Message shows used/total, remaining steps, and clear guidance to save
partial results and call done.
- Hooks the warning into context preparation, so the model sees it
before choosing the next action.
- Updates all system prompts to include 75% budget guidance and
multi-item task heuristics (estimate per-item cost, prioritize, save
incrementally).
- Adds CI tests covering threshold behavior, last-step exclusion, small
budgets, percentage formatting, and actionable guidance.
<sup>Written for commit 48cc78928a.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Increases `MAX_MEMORY_LENGTH` from 1000 to 10000 characters in both
`extract` and `evaluate` actions
- Fixes bug where agent loses access to large JS evaluation results and
hallucinates placeholder text like `JSON_STRING_FROM_STEP_6`
- When results exceed the threshold, `long_term_memory` gets a useless
summary and full data only appears in `<read_state>` for one step —
increasing 10x keeps most results in persistent memory
## Root Cause
In `tools/service.py`, when `evaluate` returns >1000 chars:
1. `long_term_memory` = `"JavaScript executed successfully, result
length: 4387 characters."`
2. Full data → `extracted_content` with
`include_extracted_content_only_once = True`
3. Data shown once in `<read_state>`, then gone from context
4. Agent can't access data in later steps → hallucinates placeholder
variable names
## Test plan
- [ ] Run existing CI tests
- [ ] Test `evaluate` with results between 1000-10000 chars — should now
persist in memory
- [ ] Test `extract` with results between 1000-10000 chars — should now
persist in memory
- [ ] Verify results >10000 chars still use the one-time read_state
pattern
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Medium Risk**
> Medium risk because it changes agent memory persistence behavior (more
content kept in long-term context) and adds stricter file-upload
validation that can introduce new user-visible failures for empty files.
>
> **Overview**
> Improves agent reliability by keeping more `extract` and `evaluate`
output in long-term memory: increases `MAX_MEMORY_LENGTH` from `1000` to
`10000` before falling back to the one-time `<read_state>`/saved-file
pattern.
>
> Hardens file handling by rejecting empty (0-byte) uploads in both the
`upload_file` tool (local mode) and the CDP `UploadFileEvent` handler,
and makes external file reading treat any `FileSystem._file_types`
extension as text except `docx`/`pdf`/images.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
3ba50e68b0. 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
Increase MAX_MEMORY_LENGTH to 10,000 in extract/evaluate so larger
results persist across steps and reduce placeholder hallucinations. Also
block empty-file uploads and make text file detection dynamic for
structured reads.
- **Bug Fixes**
- Keep evaluate/extract results up to 10k chars in long_term_memory;
>10k still uses one-time read_state.
- Reject 0-byte uploads with clear errors (validated in service and CDP
watchdog).
- Derive text extensions from _file_types in read_file_structured,
removing the hardcoded list.
<sup>Written for commit 5524c986e5.
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
Improve handling of autocomplete/combobox inputs so the agent waits for
suggestions and selects the right option, with value readback to catch
JS rewrites and clearer guidance in results and prompts. Adds targeted
tests to prevent regressions and false positives.
- **New Features**
- Detect autocomplete fields (role=combobox, aria-autocomplete, list,
haspopup + controls/owns).
- After typing, read back the field’s actual value (non-sensitive) and
warn if it differs from the typed text.
- Show guidance for autocomplete fields: wait for suggestions and click
a suggestion; updated system prompts to reinforce this.
- Expose aria-autocomplete and list attributes in DOM views; added
interaction tests for combobox, datalist, rewrite, plain inputs, and
sensitive-data skip.
<sup>Written for commit 3d4dc6fe15.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
When evaluate or extract returns results longer than MAX_MEMORY_LENGTH,
the full data is placed in extracted_content (shown only once via
read_state) and long_term_memory gets a useless summary. This causes
the agent to lose access to the data in later steps and hallucinate
placeholder text like "JSON_STRING_FROM_STEP_6".
Increasing the threshold 10x means most real-world results will stay
in long_term_memory and persist across steps.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add 0-byte file check in upload_file handler to catch empty files early
with a clear error message instead of silently passing them to websites
- Add 0-byte file check in CDP upload watchdog before setFileInputFiles
to prevent uploading empty files that cause cascading failures
- Replace hardcoded text extension list in read_file_structured() with
dynamic derivation from _file_types, so new text-based file types
are automatically supported for external file reading
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Fix f-string quote style (double→single) in _build_filename_error_message
- Remove unused XmlFile import from test file
- Add missing blank lines before DEFAULT_FILE_SYSTEM_PATH
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Allow dots, spaces, and parentheses in filenames (e.g. report.v2.md, my file.csv)
- Auto-sanitize invalid filenames instead of rejecting them (spaces→hyphens, strip bad chars)
- Add specific error messages for binary extensions (.png, .jpg, etc.) to stop infinite retry loops
- Add specific error messages for unsupported extensions explaining which ones are valid
- Add .html and .xml as supported file types
- Improve write_file tool description with explicit filename rules and append behavior
- Add HtmlFile and XmlFile classes
- Add comprehensive tests for sanitization, new file types, and error messages
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
<!-- This is an auto-generated description by cubic. -->
## Summary by cubic
Updated all examples to use ChatBrowserUse(model='bu-2-0') so they run
against the current recommended model and produce consistent results. No
library code changes.
- **Refactors**
- Replaced ChatBrowserUse() with ChatBrowserUse(model='bu-2-0') across
example folders (browser, getting_started, features, integrations,
sandbox, use-cases).
- No API changes; examples remain runnable as before.
<sup>Written for commit 20f4f2a984.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
## Summary
This PR adds support for connecting to an existing browser instance via
Chrome DevTools Protocol (CDP) URL in the skill_cli commands.
## Why This Is Needed
The current `skill_cli` (used by `browser-use open`, `browser-use
state`, etc.) only supports three browser modes:
- `chromium`: Launches a new Playwright-managed Chromium
- `real`: Launches user's Chrome with their profile
- `remote`: Uses Browser-Use Cloud service
However, many use cases require connecting to an **already-running
browser**:
1. **Remote browser automation via SSH tunnels** - A server running
Claude Code can control a local browser on a developer's machine through
SSH RemoteForward (e.g., `RemoteForward 9222 127.0.0.1:9222`)
2. **Docker integration** - Connecting to browsers running in containers
3. **Reusing authenticated sessions** - Connect to a browser where the
user is already logged into services
4. **Headless CI/CD pipelines** - Connect to pre-configured browser
instances
The `BrowserSession` class already supports `cdp_url` parameter, and the
TUI mode (`browser-use-tui --cdp-url`) exposes it. However, the simple
CLI commands (`browser-use open`, `browser-use state`, `browser-use
click`, etc.) did not have this capability.
## Changes
| File | Change |
|------|--------|
| `skill_cli/main.py` | Added `--cdp-url` argument, pass through to
`ensure_server()` and server command |
| `skill_cli/server.py` | Accept `--cdp-url` arg, store in
`SessionServer`, pass to registry |
| `skill_cli/sessions.py` | Added `cdp_url` parameter to `SessionInfo`,
`get_or_create()`, and `create_browser_session()`. CDP URL takes
precedence over other modes |
## Usage
```bash
# Start Chrome with remote debugging on your machine
chrome --remote-debugging-port=9222
# Now use browser-use CLI to control it
browser-use --cdp-url http://localhost:9222 open https://example.com
browser-use --cdp-url http://localhost:9222 state
browser-use --cdp-url http://localhost:9222 click 5
browser-use --cdp-url http://localhost:9222 screenshot /tmp/screen.png
```
### Remote Server Example (SSH Tunnel)
```bash
# On your local machine - start Chrome with remote debugging
chrome --remote-debugging-port=9222
# SSH config with RemoteForward
# Host myserver
# RemoteForward 9222 127.0.0.1:9222
# On the remote server
browser-use --cdp-url http://localhost:9222 open https://github.com
```
## Testing
Tested with Chrome remote debugging over SSH tunnel:
- Successfully controlled a local macOS Chrome browser from a remote
Linux server
- Verified: `open`, `state`, `click`, `screenshot` commands all work
correctly
- The browser on the local machine responds to commands issued from the
remote server
## Notes
- Vibe coded with Claude Opus 4.5
- ~15 lines of code change across 3 files
- CDP URL takes precedence over `--browser` mode when both are specified
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add a --cdp-url flag to skill_cli to connect to an already-running
browser via Chrome DevTools Protocol. This enables remote and
containerized automation and reusing authenticated sessions; cdp_url
overrides the browser mode and defaults the session to cdp-default to
avoid conflicts.
- **New Features**
- Added --cdp-url to browser-use CLI and passed it through the server to
session creation.
- Session creation uses cdp_url when present, taking precedence over
chromium/real/remote.
- When --cdp-url is set and session is "default", use "cdp-default" to
avoid reusing an incompatible session.
- **Migration**
- Start a browser with remote debugging (e.g., Chrome
--remote-debugging-port=9222).
- Use: browser-use --cdp-url http://localhost:9222 <command>
<sup>Written for commit 7a32885644.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Add Installation section with `uvx`/`uv pip` commands and `browser-use
install`
- Add API Key Configuration section explaining resolution order (flag →
env var → config file)
- Document CLI aliases (`bu`, `browser`, `browseruse`)
- Add `browser-use install` to Setup commands and Troubleshooting
The SKILL.md was missing critical information for users who don't have
the CLI installed - they had no way to know how to install it or
configure API keys.
## Test plan
- [x] Verify SKILL.md renders correctly
- [ ] Confirm installation commands work as documented
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added installation steps and API key setup to SKILL.md so new users can
install the browser-use CLI and configure keys quickly. Documented
uvx/uv pip commands, the browser-use install command for Chromium
dependencies, API key resolution order (flag → env var → config file),
CLI aliases, and updates to Setup and Troubleshooting.
<sup>Written for commit 5682268a03.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Increased default `step_timeout` from 120s (2 min) to 180s (3 min)
## Motivation
Production data analysis (BU2, last 24h) revealed:
- **36.5% of consecutive failures** are `AsyncIO CancelledError` in
`get_browser_state_summary`
- Complex pages can take 30-60s for DOM extraction + 30-60s for LLM call
+ action execution
- The 120s default was too tight for complex pages or slow network
conditions
## Analysis
| Metric | Value |
|--------|-------|
| Tasks with browser state timeout | 81 (36.5% of failures) |
| Median timeout duration | 5.06 min |
| Time per step (timeout tasks) | 13.0s median |
| Time per step (success tasks) | 6.0s median |
The step timeout wraps the entire step: browser state retrieval + LLM
call + action execution. 180s provides ~50% more buffer while still
catching genuinely stuck steps.
## Test plan
- [ ] Verify step timeout behavior
- [ ] Monitor timeout rates in production
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Low Risk**
> Low risk: a single default parameter change that only affects how long
a step can run before timing out, potentially increasing worst-case step
latency but not changing core logic.
>
> **Overview**
> Raises the default `step_timeout` in `Agent` initialization from 120s
to 180s, giving each step more time for browser-state retrieval, LLM
calls, and action execution before a timeout is raised.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
3c927b4f9b. 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
Increased the default per-step timeout from 120s (2 min) to 180s (3 min)
to reduce CancelledError timeouts on complex pages and slow networks.
This gives more time for browser state retrieval, LLM calls, and action
execution while keeping the total task timeout unchanged.
<sup>Written for commit 3c927b4f9b.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Increased default LLM timeout from 45s to 75s for gemini models
(non-3-pro)
- Added explicit 75s timeout for browser-use models
## Motivation
Production data analysis (last 24h) revealed:
- **gemini-3-pro-preview**: 48% timeout rate with median 23s/step for
timeouts vs 19s/step for success (only 21% slower)
- **browser-use-2.0**: Timeout tasks have 74% slower time per step
(10.7s vs 6.0s median)
- Most timeouts occur on steps 11-20 where tasks are actively making
progress
The 45s default was too aggressive for these models. 75s provides ~3x
the median step time as buffer while still catching genuinely stuck
tasks.
## Test plan
- [ ] Verify timeout behavior with gemini models
- [ ] Verify timeout behavior with browser-use models
- [ ] Monitor timeout rates in production
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Low Risk**
> Low risk: only adjusts default per-step LLM call timeouts, which may
increase worst-case latency but doesn’t change core agent logic or
security-sensitive behavior.
>
> **Overview**
> Increases the auto-selected `llm_timeout` in `Agent` when not
explicitly provided: Gemini models (non `3-pro`) now use 75s instead of
45s, and the generic default fallback is raised from 60s to 75s
(affecting models not matched by the other heuristics, including
browser-use fine-tuned models).
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
40336731d5. 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
Increased LLM step timeout to 75s for Gemini (non‑3‑pro) and raised the
generic default timeout to 75s to reduce false timeouts during active
progress. Gemini 3‑pro stays at 90s; Groq remains 30s;
Claude/Sonnet/Deepseek remain 90s. This also applies to Browser‑Use and
other models using the default.
- **Bug Fixes**
- Set Gemini (non‑3‑pro) timeout from 45s to 75s.
- Raised generic default timeout from 60s to 75s (affects Browser‑Use
and other unmatched models).
- Rationale: production data showed high timeouts on active steps (e.g.,
Gemini median 23s/step; Browser‑Use timeouts 74% slower).
<sup>Written for commit 40336731d5.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
Production data analysis (24h) shows:
- 36.5% of consecutive failures are AsyncIO CancelledError in browser state retrieval
- Complex pages can take 30-60s for DOM extraction + 30-60s for LLM call
- 120s was too tight for complex pages with slow network
180s (3 min) gives ~50% more buffer while still catching stuck steps.
This is the per-step timeout, not the total task timeout.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Based on production data analysis showing:
- gemini-3-pro-preview has 48% timeout rate with median 23s/step
- browser-use-2.0 timeout tasks have 74% slower time per step (10.7s vs 6.0s)
- Most timeouts occur on steps 11-20 where tasks are making progress
The 45s default was too aggressive. 75s provides ~3x the median step time
as buffer while still catching genuinely stuck tasks.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The SKILL.md was missing critical information for users who don't have
the CLI installed. Added:
- Installation section with uvx/uv pip commands
- browser-use install command for Chromium dependencies
- API key configuration section (env var, config file, flag)
- CLI aliases (bu, browser, browseruse)
- install command in troubleshooting
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
<!-- This is an auto-generated description by cubic. -->
## Summary by cubic
Bumped browser-use version from 0.11.4 to 0.11.5 in pyproject.toml to
publish the latest patch.
<sup>Written for commit 93fd57258e.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
Continuation of
[#3801](https://github.com/browser-use/browser-use/pull/3801) by
@Mr-Neutr0n - removed test and resolved lint. Resolves
[#3726](https://github.com/browser-use/browser-use/issues/3726) and
[#3865](https://github.com/browser-use/browser-use/issues/3865).
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Stop sending screenshots to the judge LLM when use_vision=False to
prevent sensitive data leakage. Resolves#3726 and #3865.
- **Bug Fixes**
- Added use_vision param to construct_judge_messages() and respected it.
- Skipped screenshot selection/encoding when use_vision is False.
- Passed settings.use_vision from _judge_trace() to
construct_judge_messages(); True/'auto' still include images.
<sup>Written for commit b00ffd5380.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
Saurav Panda