captcha-relay_skill

Overview

This skill performs human-in-the-loop CAPTCHA solving with two modes: screenshot (default) for zero-infrastructure solving and token relay for native widget solves when network access is available. It captures CAPTCHA state from a browser controlled via Chrome DevTools Protocol (CDP), relays the challenge to a human, and injects clicks or tokens back into the browser to continue automation. The design emphasizes reliability across CAPTCHA types and minimal setup for quick usage.

How this skill works

In screenshot mode the skill takes a full-page or focused CAPTCHA screenshot, overlays a numbered grid, and produces an annotated image plus a short prompt for a human operator. The operator replies with selected grid cells and the skill injects corresponding click events into the page via CDP. In token relay mode the skill detects CAPTCHA type and sitekey, hosts a relay page that renders the real widget for native solving, and either injects the returned token into the target page or returns it for the caller to use. Relay mode requires a reachable URL (tunnel or Tailscale).

When to use it

• Use screenshot mode when you have no external network access or want zero setup.
• Use token relay when you can host a reachable relay (Tailscale or tunnel) and need a native CAPTCHA token.
• Use screenshot mode for complex or non-standard CAPTCHAs (sliders, visual puzzles, text).
• Use relay mode for reCAPTCHA v2, hCaptcha, or Turnstile when a proper token is required.
• Use screenshot mode for fast manual intervention during development or intermittent automation.

Best practices

• Run Chrome/Chromium with a remote debugging port (default 18800) and keep session state stable during solves.
• Prefer relay mode when you need reliable, native tokens for bypassing server-side validation.
• Use short, explicit prompts with the annotated screenshot to reduce human error (e.g., "Click all squares containing traffic lights").
• Set a sensible timeout for human responses and handle timeouts gracefully in automation logic.
• When using relay mode, secure your relay endpoint (Tailscale or authenticated tunnel) to prevent unauthorized access.

Example use cases

• Headless scraping jobs that occasionally hit CAPTCHAs and need a fast human fallback.
• Automation that must obtain valid CAPTCHA tokens for login or form submission (use relay mode).
• Testing and QA workflows where developers manually verify CAPTCHA behavior across pages.
• Hybrid bots that prefer zero-infrastructure solves in the field and switch to relay mode in controlled environments.