Unstuck Docs GitHub

Unstuck Browser

Wrap your agent's page once. From then on, when a navigation or a click lands on a CAPTCHA or a "verify you are human" check (Cloudflare, Turnstile, reCAPTCHA, hCaptcha), Unstuck brings a person in through a link, and the agent's own call returns once they're past it. Nothing else in your agent changes.

How it works

unstuck.wrap(page) returns the same page. Its navigations (goto, reload, back and forward) and its actions (click, fill, press, and the same on locators) are checked before and after they run. When a check appears:

  1. Unstuck tells a real check from a page that only mentions one (an article about CAPTCHAs is not a check).
  2. It sends a person the takeover link, like a takeover does. They solve the check on the live page and tap Done.
  3. It waits for the page to settle (Cloudflare reloads by itself) and checks again. Past it: your call returns. Still blocked: your call fails with UnstuckRescueError.

page.unstuck.lastRescue says what happened last. page.unstuck.askHuman(reason) brings a person in for something only they can do, such as a login or a 2FA code.

Your first rescue

The quickest way to see it is the MCP server in Claude Code. It needs nothing else on your computer except Node.js and Chrome or Chromium.

  1. Add the server, then restart Claude Code:

    claude mcp add unstuck -- npx -y @velmlabs/unstuck-engine --mcp --browser --open
  2. Ask: "Use fetch_page to read https://www.google.com/recaptcha/api2/demo and tell me what it says."

  3. Unstuck starts a headless Chrome and opens the page. It finds the reCAPTCHA and opens the takeover link in your browser (that's --open).

  4. Tap Start, solve the CAPTCHA, and tap Done.

  5. The tool call returns the page's content with rescued: true, and the agent answers. If you took longer than about 40 seconds, the agent shows you the link and finishes the call with resume_after_human.

Without --open, the agent shows you the link instead. With UNSTUCK_API_KEY set, it also reaches your paired phone (Phone alerts).

Playwright (TypeScript)

npm init -y && npm pkg set type=module
npm install @velmlabs/unstuck playwright
npx playwright install chromium
const unstuck = new Unstuck({
  onLink: ({ url, reason }) => console.log(`\n${reason}. Open this link:\n${url}\n`),
});
const page = unstuck.wrap(await browser.newPage(), { remember: true });

try {
  // A check on this page brings a person in; goto returns once they're past it.
  await page.goto(process.argv[2] ?? 'https://www.google.com/recaptcha/api2/demo');
  console.log(`Takeover ${page.unstuck.lastRescue?.status ?? 'not needed'}: now on "${await page.title()}"`);
  // ...carry on with the agent's work here.
} catch (e) {
  if (!(e instanceof UnstuckRescueError)) throw e;
  console.log(`Takeover ${e.status}: ${e.message}`);
}

Playwright (Python)

pip install unstuck playwright
python -m playwright install chromium
def on_link(link):
    print(f"\n{link.reason}. Open this link:\n{link.url}\n", flush=True)

async with Unstuck(on_link=on_link) as unstuck:
    page = unstuck.wrap(await browser.new_page(), remember=True)
    try:
        # A check on this page brings a person in; goto returns once they're past it.
        await page.goto(url)
        status = page.unstuck.last_rescue.status if page.unstuck.last_rescue else "not needed"
        print(f'Takeover {status}: now on "{await page.title()}"', flush=True)
        # ...carry on with the agent's work here.
    except UnstuckRescueError as e:
        print(f"Takeover {e.status}: {e}", flush=True)

The Python wrap works with async Playwright (playwright.async_api). Options use snake case: remember, profile, max_rescues_per_hour, on_rescue_fail.

Puppeteer

npm init -y && npm pkg set type=module
npm install @velmlabs/unstuck puppeteer
const unstuck = new Unstuck({
  onLink: ({ url, reason }) => console.log(`\n${reason}. Open this link:\n${url}\n`),
});
const page = unstuck.wrap(await browser.newPage(), { remember: true });

try {
  await page.goto(process.argv[2] ?? 'https://www.google.com/recaptcha/api2/demo');
  console.log(`Takeover ${page.unstuck.lastRescue?.status ?? 'not needed'}: now on "${await page.title()}"`);
} catch (e) {
  if (!(e instanceof UnstuckRescueError)) throw e;
  console.log(`Takeover ${e.status}: ${e.message}`);
}

browser-use

browser-use has no hook after each step, so UnstuckTools gives the model two tools, check_page and ask_human, and UNSTUCK_SYSTEM_MESSAGE tells it to call check_page after each navigation or submit and never to solve a check itself.

pip install 'unstuck[browser-use]'
unstuck = Unstuck(on_link=on_link)
tools = UnstuckTools(CDP_URL, unstuck=unstuck, remember=True)
if os.environ.get("ANTHROPIC_API_KEY"):
    from browser_use import Agent, Browser

    agent = Agent(
        task=f"Open {START_URL} and tell me the page's main heading.",
        llm="anthropic:claude-sonnet-5-5",
        browser=Browser(cdp_url=CDP_URL),
        tools=tools,
        extend_system_message=UNSTUCK_SYSTEM_MESSAGE,
    )
    await agent.run()

MCP with its own browser

It all runs on your computer, with no account: without Unstuck Cloud the takeover link is served by the engine on http://127.0.0.1 and opens on this machine (--open opens it for you). Add UNSTUCK_API_KEY to open it on any phone and get alerts.

--mcp --browser runs the MCP server with a headless Chrome of its own, started on the first browsing call. It needs Chrome or Chromium on the machine (npx playwright install chromium is enough; CHROME_PATH picks a binary).

claude mcp add unstuck -- npx -y @velmlabs/unstuck-engine --mcp --browser
{
  "mcpServers": {
    "unstuck": {
      "command": "npx",
      "args": [
        "-y",
        "@velmlabs/unstuck-engine",
        "--mcp",
        "--browser"
      ]
    }
  }
}

The agent gets fetch_page (a page's readable content as markdown, text or html, its final URL and HTTP status), the page tools open, snapshot, click, type, select, scroll, wait_for and screenshot, and ask_human. A quick check is solved inside the call, and the result says rescued: true. When the person needs longer than about 40 seconds (UNSTUCK_IN_TOOL_WAIT_S), the call returns status: "human_needed" with the link for the agent to show you. With no other way to reach you (no --open, no Unstuck Cloud alerts), it returns the link at once. Then resume_after_human finishes the original call without opening the page again. Meanwhile other browsing calls return human_takeover_active. --tools browser gives the same tools on the Chrome at UNSTUCK_CDP_URL instead.

Pages can try to steer an agent, so the browsing tools guard against it:

Session memory

With remember: true (Python: remember=True; on by default in the MCP server), the cookies a person's rescue earned are kept and loaded before the next visit, so the next run goes straight through, even after a restart. On a computer they live in ~/.unstuck/profiles/<profile>/sites.json, readable only by you (profile picks the file; the MCP server uses mcp). In a Worker, pass a store that lives in a Durable Object: see Cloudflare Workers.

page.unstuck.forgetSite(domain) (Python: forget_site, MCP: forget_site) removes a site. forgetAll() removes every one.

Rate limit

At most 10 person-checks per hour on a profile (maxRescuesPerHour, --max-rescues-per-hour). Past that, a check ends at once with rescue_limited and nobody is bothered. askHuman counts too.

When a rescue fails

A rescue that doesn't end past the check throws UnstuckRescueError (Python: UnstuckRescueError too), with status, detail and check (what was detected, and on which site):

status Meaning
still_blocked The person tapped Done, but the check is still there
timed_out Nobody finished it in time
cancelled The person tapped Can't solve, or the takeover was cancelled
rescue_limited The hourly limit is used up
alert_failed alerts: 'required' and no paired phone got the link
browser_cannot_render_captcha This browser can't draw CAPTCHA widgets (see Obscura below)
failed Anything else, with a detail

onRescueFail: 'return' (Python: on_rescue_fail="return") returns normally instead: read page.unstuck.lastRescue.

Obscura

Obscura works through CDP, so the wraps and the MCP server's --browser=obscura apply, with limited support. Obscura doesn't draw cross-origin iframes, and every reCAPTCHA, hCaptcha and Turnstile widget lives in one. Before it brings anyone in for a challenge, Unstuck checks whether the browser can draw them; on Obscura the rescue ends at once with browser_cannot_render_captcha and the detail "this browser can't show CAPTCHAs; use Chrome for this site". Logins, 2FA and other pages of the site itself work.

Hand the session to curl

page.unstuck.getSession(domain), include_session: true on fetch_page, or get_session hands over a site's cookies (such as Cloudflare's cf_clearance), its Cookie header and the browser's user agent, for curl or an HTTP client. Over MCP they're given only for the site the tab is on, once a person got past its check there (or it's remembered on the profile), so a page can't talk the agent into handing out another site's cookies. Treat them like a password. It's best effort: many sites tie a clearance to the browser that earned it, so fetching through the browser (fetch_page, or the wrapped page) is the reliable path.

What it can and can't get past

Unstuck gets your agent past anything a person can clear by looking at the live page and tapping or typing. It can't get past a block on the browser itself, or a step that needs the person's own device.

It handles How
CAPTCHAs and "verify you are human" checks Detected and handed to a person automatically: Cloudflare (both the full-page check and the Turnstile widget), reCAPTCHA, hCaptcha and generic checks
Logins and 2FA or SMS codes The person types them in the live page. The agent calls ask_human; in code, add rescue: ['challenge', 'login', '2fa'] to detect them automatically
"Check your phone" or "tap Yes" prompts The agent calls ask_human. The person approves on their phone, then taps Done
Anything else on the page only a person should do Consent walls, an unusual form, confirming a payment: the agent calls ask_human
It can't handle Why, and what to do instead
Sites that refuse automated browsers outright, such as Google's "Couldn't sign you in. This browser or app may not be secure" The person uses the same browser, so the site refuses them too. Unstuck doesn't disguise automation. Use the site's official API (Gmail has one), or sign in yourself in your own Chrome and run --tools browser on it
A passkey or a hardware security key The key is on the person's device, while the browser runs on the agent's computer
An HTTP 403, an IP ban, a rate limit, a geo-block or a payment wall There is nothing on the page for a person to do
Obscura and other browsers that can't draw CAPTCHA widgets A challenge there ends at once with browser_cannot_render_captcha: use Chrome for that site
A check type the detection doesn't know yet Nothing is detected, so nobody is brought in. The agent can still call ask_human

A person solves

Unstuck never solves a check itself and uses no CAPTCHA-solving service: a person does, on the real page. A person solves every check; the site's terms still apply.