English · العربية · Deutsch · Ελληνικά · Español · فارسی · Français · Bahasa Indonesia · Italiano · 日本語 · 한국어 · Polski · Português (Brasil) · Русский · ไทย · Türkçe · Українська · Tiếng Việt · 简体中文 · 繁體中文

rea-captcha

Local-first verification challenge intelligence for browser agents.

Install · Live demo · Agentic matrix · How it works · MCP catalog · Cases · Architecture

rea-captcha detects browser verification challenges and lets an agent complete supported interactions inside the browser session it already owns. Authorized provider-test and owned-origin flows stay in the same Playwright/CDP page, require fresh server-validated evidence, and resume the same task. It ships a TypeScript SDK, local stdio MCP server, browser-use plugin, Vercel-compatible Agent Skill, and optional authorized-origin local OCR.

Official source: install from masakaai/rea-captcha and npm package rea-captcha. The project has no hosted solver, telemetry, stealth claim, or dependency on Jet Browser. It reuses the agent's existing browser; the provider examples use documented non-production credentials only.

Run the four live verification cases

Agentic verification matrix

Google reCAPTCHA v2	Cloudflare Turnstile
hCaptcha	Owned image/text

These are complete agent-driven protected-action flows, not DOM-only fixtures. Each run detects a challenge, performs the authorized browser interaction in the same page, submits to the real validation boundary, observes fresh passed evidence, verifies the session cookie, and resumes the same controller. Google reCAPTCHA v2, Cloudflare Turnstile, and hCaptcha use their documented test modes plus vendor Siteverify endpoints; the owned image/text case uses an explicitly authorized local path and local server validation.

The first three cases load vendor-hosted JavaScript and accept the protected action only after the server receives success: true from the vendor verification endpoint. They use the vendors' documented non-production credentials: Google test keys, Cloudflare dummy keys, and hCaptcha test keys.

npm run demo:web       # interactive local demo
npm run test:web-demo  # all four live validation paths

Install

Paste one sentence into Codex, Claude Code, Cursor, or another coding agent:

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

How it works

MCP and coding agents

The official Registry entry is io.github.masakaai/rea-captcha and launches the zero-configuration stdio server through npm:

npx -y rea-captcha mcp --stateless

It exposes six tools: captcha_analyze, captcha_inspect, captcha_complete, captcha_handoff, captcha_wait, and captcha_resume. captcha_complete performs only a policy-authorized action in the configured existing browser and waits for fresh validation evidence. See the tool catalog for inputs and lifecycle semantics.

For a stateful local session, run setup and print a host configuration:

npx rea-captcha agent-config --agent codex
npx rea-captcha agent-config --agent mcp-json

rea-captcha adds verification intelligence and bounded completion actions; it does not replace an agent's navigation tools. Both integrations must refer to the same browser session.

TypeScript SDK

import { ChallengeController, ChallengePolicy } from 'rea-captcha';
import { PlaywrightChallengeAdapter } from 'rea-captcha/playwright';

const authorizedOrigin = 'https://fixture.example';
const controller = new ChallengeController({
  browser: new PlaywrightChallengeAdapter({
    id: 'checkout',
    page,
    agentActions: {
      authorizedOrigins: [authorizedOrigin],
      allowProviderTestAutomation: true,
      submitSelector: 'button[type="submit"]'
    }
  }),
  policy: new ChallengePolicy({
    authorizedOrigins: [authorizedOrigin],
    allowProviderTestAutomation: true
  })
});

const inspection = await controller.inspect();
if (inspection.policy.decision === 'agent-action' || inspection.policy.decision === 'local-processing') {
  await controller.complete({ timeoutMs: 30_000 });
  await controller.resume();
}

The controller borrows page; it does not create or close the browser.

Browser providers

The recommended cross-agent provider is a browser already exposing CDP:

{
  "version": 1,
  "sessions": {
    "local-chrome": {
      "adapter": "playwright-cdp",
      "endpoint": "http://127.0.0.1:9222",
      "allowProviderTestAutomation": true,
      "submitSelector": "button[type=submit]",
      "authorizedOrigins": ["https://fixture.example"]
    }
  }
}

Generic Playwright Page, Playwright-over-CDP, browser-use, and optional Jet Browser managed/standalone adapters are implemented. Jet Browser must be selected explicitly and is neither installed nor started by the default path. Configuration examples and provider boundaries are documented in architecture and cases.

browser-use and local OCR

For agent-driven completion, point rea-captcha's Playwright/CDP session at the same existing browser used by browser-use. The MCP lifecycle detects the block, performs an authorized action, verifies the result, and returns control without replacing the browser or task context.

The Python plugin remains a lightweight detection and manual-recovery fallback for browser-use integrations that do not expose a compatible CDP action surface:

from browser_use import Agent
from rea_captcha import ChallengePlugin

agent = Agent(task="Complete the authorized workflow", llm=llm)
challenge = ChallengePlugin(mode="local", human_handoff=True)
await challenge.attach(agent)

Local ddddocr is an optional primitive only for simple image/text challenges on an exact authorized origin. It is disabled unless both allowLocalImageText and authorizedOrigins are configured. No model weights are redistributed, and an OCR prediction remains untrusted evidence.

What is implemented

• Evidence detection for reCAPTCHA, hCaptcha, Turnstile, GeeTest, DataDome, PerimeterX, AWS WAF, image/text inputs, and generic verification pages.
• Deterministic states with bounded timeout, cancellation, and fresh-evidence resume checks.
• Six stdio MCP tools, CLI/MCP parity, TypeScript SDK, browser-use hooks, and a Vercel-compatible Agent Skill.
• Borrowed Playwright/CDP sessions plus optional Jet Browser adapters.
• Local JSONL events with explicit ownership and no telemetry.
• npm Trusted Publishing/provenance workflow and GitHub OIDC publication to the official MCP Registry.

Documentation

• Architecture and trust boundaries
• Case matrix and fixture rationale
• MCP tool catalog
• Validation evidence
• Release and Trusted Publisher procedure
• Ecosystem and awesome-list intake
• Security policy
• Contributing

Community

Join the MASAKA Discord, then use the dedicated #rea-captcha channel for integration discussion and same-session agent examples. Use GitHub Issues for reproducible bugs and follow the private security policy for vulnerabilities. Never post browser profiles, cookies, challenge tokens, API keys, or private page evidence.

Scope and disclaimer

rea-captcha is for owned or explicitly authorized workflows. Provider automation is accepted only when the adapter confirms the vendor's documented non-production test key. It does not bypass production interactive protection. Commercial solver APIs, credential transfer, stealth claims, and automatic completion of third-party production challenges are outside scope.

Inspired by morluto/rea.

License

Core code and integrations are MIT licensed. Optional dependencies and model artifacts keep their own terms; see Third-party notices and model licenses.