Browser-use kept stopping at CAPTCHA, so I built a same-session handoff

[IRONICBo]

One failure mode I kept running into with browser-use was a task getting most of the way through, hitting a CAPTCHA or verification step, and then just sitting there. Retrying the click was not enough — the agent still did not know whether the protected action had actually passed.

I built rea-captcha around that gap. It stays with the Playwright/CDP browser the agent already owns, instead of opening a clean session and losing the task context:

detect → authorized action → fresh validation → resume

The distinction between “the widget was clicked” and “the server accepted the result” turned out to be the important part. The controller only lets the task continue after fresh passed evidence. If the challenge is unknown or outside the configured scope, it stops for a bounded handoff instead of looping.

Google reCAPTCHA	Cloudflare Turnstile
hCaptcha	Owned image / text

The four controlled cases are live here: https://rea-captcha.vercel.app/

The quickest way to inspect it is to give a coding agent this line:

Install rea-captcha and connect it to the browser session this agent already uses.

For a direct Browser Use install, the v0.3.0 workflow-verified wheel is attached to the release:

python -m pip install 'rea-captcha[browser-use] @ https://github.com/masakaai/rea-captcha/releases/download/v0.3.0/rea_captcha-0.3.0-py3-none-any.whl'

The ChallengePlugin borrows the current BrowserSession; the handoff guide covers hook timing, bounded waits, and the stronger task/tab/generation-bound controller.
Or start the local stdio MCP server with:

npx rea-captcha@0.3.0 mcp --stateless

Review the pinned version and approve npm's install prompt before running it. That stateless command is for local evidence analysis and needs no browser connection. For inspect, complete, handoff, wait, and resume, launch rea-captcha with an explicit config pointing at the browser session the agent already owns; it never silently launches or takes over a browser.

One scope note: the recorded provider cases use their official non-production test keys, and the image/text case is on an owned origin. This is meant for authorized workflows and reliable handoff/resume behavior, not generic third-party production CAPTCHA bypass.

REA was the original inspiration for the project. I would be especially interested in hearing from people running longer browser-use tasks: when verification interrupts a run today, do you keep the same session, hand it to a person, or restart the task?