cloakbrowser

name	cloakbrowser
description	Use when a browser automation task needs stealth Chromium or when normal Playwright/Puppeteer may be blocked by Cloudflare, Turnstile, reCAPTCHA v3, FingerprintJS, BrowserScan, bot detection, anti-automation checks, or anti-scraping systems. Also use for screenshots, extraction, UI-flow debugging, and scripted browsing when stealth matters.

CloakBrowser Skill

Use CloakBrowser as a stealth Playwright-compatible browser from terminal scripts. Prefer this over ordinary Playwright when bot detection, Cloudflare, Turnstile, reCAPTCHA v3, fingerprinting, proxy fingerprint consistency, or stealth browser automation matters.

This is script-first, not MCP-first. Write small Python automation scripts, run them through bundled runner, return concise artifacts and findings.

Path setup

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export CLOAK_RUN="$CODEX_HOME/skills/cloakbrowser/scripts/cloak_run.py"

First check

python3 "$CLOAK_RUN" --check

If dependency missing, run local setup only when task needs CloakBrowser:

python3 "$CLOAK_RUN" --setup

Setup creates a user-local venv under ~/.local/share/codex-cloakbrowser-skill/venv and installs cloakbrowser. It does not install system packages and does not touch npm globally.

Core workflow

1. Create a small task script under /tmp, e.g. /tmp/cloak_task.py.
2. Use from cloakbrowser import launch.
3. Run via python3 "$CLOAK_RUN" /tmp/cloak_task.py.
4. Save artifacts under output/cloakbrowser/ when inside a repo, else /tmp/cloakbrowser-output/.
5. Report URLs, screenshots, extracted text, errors, and exact artifact paths.

Minimal script

from cloakbrowser import launch

browser = launch(headless=True, humanize=True)
page = browser.new_page()
page.goto("https://example.com", wait_until="domcontentloaded")
print(page.title())
print(page.locator("body").inner_text()[:2000])
browser.close()

Run:

python3 "$CLOAK_RUN" /tmp/cloak_task.py

Screenshot script

from pathlib import Path
from cloakbrowser import launch

out = Path("output/cloakbrowser")
out.mkdir(parents=True, exist_ok=True)

browser = launch(headless=True, humanize=True)
page = browser.new_page(viewport={"width": 1440, "height": 1000})
page.goto("https://example.com", wait_until="networkidle")
page.screenshot(path=str(out / "example.png"), full_page=True)
print(out / "example.png")
browser.close()

Persistent profile

Use persistent profile when site penalizes incognito or login/session matters:

from cloakbrowser import launch_persistent_context

ctx = launch_persistent_context(
    user_data_dir="/tmp/cloak-profile-example",
    headless=False,
    humanize=True,
)
page = ctx.new_page()
page.goto("https://example.com")
ctx.close()

Proxy / geoip pattern

browser = launch(
    headless=True,
    humanize=True,
    proxy="socks5://user:pass@host:port",
    geoip=True,
)

Only use proxies supplied or approved by user.

Guardrails

• Do not use for credential theft, CAPTCHA solving services, spam, abuse, bypassing paywalls, or access the user is not authorized to automate.
• CloakBrowser reduces detection; it does not guarantee access.
• Prefer humanize=True for hostile sites; prefer headless=False when debugging.
• Avoid dumping full HTML into chat. Extract targeted text, links, screenshots, or compact JSON.
• Keep scripts small and reproducible; do not create large browser frameworks unless requested.
• If ordinary Playwright is enough, use ordinary browser tooling instead. Use CloakBrowser when stealth matters.

References

Open only when needed:

• references/patterns.md — task templates and troubleshooting.