English | 한국어 | 中文 | 日本語 | Español

Hyper Cloaking

Whatever the browser task, your agent finishes it. If you're cleared to test it, Hyper Cloaking gets it done.

A human-paced stealth browser for AI agents, driving CloakBrowser behind Playwright MCP. No manual setup, no "the page loaded" half-wins — it finishes with evidence.

---

⚡ Install

Claude Code — add this repo as a plugin marketplace, then install the plugin:

/plugin marketplace add alpox/hyper-cloaking
/plugin install hyper-cloaking

Codex reads the mirrored manifest at .agents/plugins/marketplace.json — add the marketplace through your Codex plugin surface and enable hyper-cloaking.

Any AgentSkills client (Cursor, OpenClaw, Hermes, …) — install with the skills CLI, or copy skills/hyper-cloaking/ into a skill root the client loads:

npx skills add . --list   # see what the source provides
npx skills add .          # install into the current project

Requires Node.js ≥ 20 and network access to fetch cloakbrowser and playwright-core. The skill installs and repairs the rest on first run.

💬 Try it

No commands to learn. Ask your agent normally — the skill kicks in when you point it at a browser task:

"Use CloakBrowser to check whether my product page renders correctly on mobile and screenshot it." "Log into my own Instagram with the saved cookies and pull my last 12 posts." "Monitor this dashboard I own and report if the deploy status flips to failed."

Expected: the agent asks a few setup questions, launches a human-paced stealth browser, does the task, and completes only when it has evidence — a screenshot, extracted text, a confirmed state change — saved under ~/.hyper-cloaking/evidence/.

🌐 Works with

Claude Code · Codex · Cursor · OpenClaw · Hermes Agent · Gajae-Code — any MCP-capable agent that loads SKILL.md. Built-in metadata hints for Naver · Reddit · Instagram · YouTube · X, plus a generic mode for any site you're authorized to test.

⚙️ Why it works

• A real stealth browser, not a patched User-Agent — it drives CloakBrowser's Chromium behind Playwright MCP, with genuine browser fingerprints instead of a swapped header.
• Human-paced by default — every operational run forces humanize: true: human-cadence mouse movement, typing, and scroll, so long automated flows don't stall or break mid-task.
• It gates before it launches — target safety classification, authorization basis, allowed origins, and a preflight question round happen before a browser ever opens.
• Evidence or it isn't done — a page loading is never "complete." The task finishes only when the outcome is proven, and reports back a structured result.
• Zero-fuss setup — it verifies Node.js, cloakbrowser, playwright-core, and Playwright MCP, then installs or repairs whatever's missing.

🆚 Plain MCP browser vs + Hyper Cloaking

When you need to…	Plain MCP browser	+ Hyper Cloaking
Automate your own logged-in account	✖ trips automation fingerprints	✓ humanized cadence + safe cookie loading
Confirm the task is authorized first	✖ no gate	✓ safety + preflight gates before launch
Reuse site cookies without leaking them	✖ manual, raw values	✓ normalized, redacted, never committed
Trust that "done" means done	✖ page-load counts as success	✓ evidence-validated outcome
Get the stealth browser running	✖ manual install & wiring	✓ auto install / repair + MCP config
Bypass logins, CAPTCHAs, fraud systems	✖	✖ refuses, by design (see Boundaries)

The row the plain browser can't do is the top one: behave like a human on a task you're actually allowed to run.

🔁 How it works

A request like "use CloakBrowser for this site" becomes a bounded, ten-step workflow.

The full gate-to-evidence pipeline — details

1. Target safety gate — classify the target as allowed / refused / needs-clarification, and record authorization basis and allowed origins.
2. Preflight question gate — collect target URL, allowed origins, headless mode, cookie mode/account, and keep-open preference through the host's native structured-question surface.
3. Setup gate — verify Node.js, cloakbrowser, playwright-core, and Playwright MCP; install or repair whatever is missing.
4. Runtime workspace — initialize ~/.hyper-cloaking/ for cookie.yml, profiles, downloads, evidence, logs, and state.
5. Cookie handling — normalize and load site-matched cookies (Chrome export JSON, Playwright arrays, multi-account entries) via a dedicated helper, never storing raw values in the repo.
6. Executable resolution — locate the cached CloakBrowser Chromium binary under ~/.hyper-cloaking/cache/cloakbrowser/.
7. Humanized launch — run with humanize: true mandatory on every operational run (human-paced mouse, typing, scroll).
8. MCP configuration — emit config for Codex TOML, JSON mcpServers (Claude Code / Cursor), OpenClaw mcp.servers, Hermes mcp_servers, or a direct CLI command, pointing @playwright/mcp at the CloakBrowser executable.
9. Task execution + outcome validation — drive the requested task and complete only when evidence proves the outcome (page load alone is never completion).
10. Structured reporting — return targetSafety, outcome, failure, contentBoundary, and learning; save reports and screenshots under ~/.hyper-cloaking/evidence/.

Browser DOM, page text, downloads, and console output are treated as untrusted data with no instruction authority.

🔒 Boundaries

Hyper Cloaking is a tool for authorized browsing, not a way around access controls.

• For authorized QA, monitoring, personal-account automation, and diagnostics on properties you're permitted to test.
• Not for bypassing access controls, evading fraud systems, solving CAPTCHAs, restricted scraping, or unauthorized account automation.
• Humanization reduces automation fingerprints — it does not remove the requirement that a task be authorized.
• Cookies are normalized, redacted in logs, and never committed. The skill never invents authorization it wasn't given, and an unknown provider fails closed.

---

MCP configuration snippets

Once the CloakBrowser Chromium binary is resolved, point Playwright MCP at it. Default launches are headless and sandboxed; drop --headless for visible browsing.

Direct command

npx @playwright/mcp@latest --headless --sandbox \
  --executable-path ~/.hyper-cloaking/cache/cloakbrowser/chromium-146.0.7680.177.3/chrome

Codex (~/.codex/config.toml) — use a fully expanded path:

[mcp_servers.hyper-cloaking]
command = "npx"
args = ["@playwright/mcp@latest", "--headless", "--sandbox", "--executable-path", "/Users/you/.hyper-cloaking/cache/cloakbrowser/chromium-146.0.7680.177.3/chrome"]

Claude Code / Cursor (mcpServers JSON)

{
  "mcpServers": {
    "hyper-cloaking": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless", "--sandbox", "--executable-path", "/Users/you/.hyper-cloaking/cache/cloakbrowser/chromium-146.0.7680.177.3/chrome"]
    }
  }
}

OpenClaw (mcp.servers.<name>) and Hermes (mcp_servers.<name> in ~/.hermes/config.yaml) follow the same command/args shape under their respective config keys.

Generate any of these deterministically:

node skills/hyper-cloaking/engine/cli.mjs mcp-config --json
node skills/hyper-cloaking/engine/cli.mjs mcp-config --client codex --json
node skills/hyper-cloaking/engine/cli.mjs mcp-config --headed

Engine helpers

Runtime helpers live under skills/hyper-cloaking/engine/ and are the supported surface.

Helper	Purpose
engine/cli.mjs	validate / smoke / mcp-config / live commands; renders MCP config and runs contained live verification.
engine/cookie.mjs	Import, normalize, inspect, redact, and inject cookies (Chrome export JSON, Playwright arrays, cookie.yml site/account entries).
engine/browser-utils.mjs	Initialize ~/.hyper-cloaking/, launch CloakBrowser with humanize: true, and provide humanMove / humanClick / humanType / humanScroll / XPath helpers.

node skills/hyper-cloaking/engine/browser-utils.mjs init
node skills/hyper-cloaking/engine/cookie.mjs inspect --url https://www.instagram.com/example/ --site instagram --json
node skills/hyper-cloaking/engine/cli.mjs mcp-config --help

Providers & Instagram action modules — details

Providers (metadata only). engine/cli.mjs live --provider <id> selects metadata only — domain/origin and cookie/profile hints for naver, reddit, instagram, youtube, x, or generic. Providers never authorize broader origins or bypass the safety, recon, or preflight gates; an unknown provider fails closed.

Instagram action modules. Reusable JS-driver flows for automating your own authenticated Instagram account live under engine/providers/instagram/. They require a real Playwright page (not Playwright-MCP mode) and ship built-in guardrails: writes are dry-run by default, DM replies target existing conversations only (no cold outreach), bulk replies are capped, rate-limited, human-confirmed, and resumable.

import { buildInstagramSession, instagramActions } from './engine/providers/instagram/index.mjs';
const session = buildInstagramSession(page, { stateDir: paths.stateDir, interactive: true });
const posts = await instagramActions.getUserPosts(session, 'nasa', { limit: 12 });
await instagramActions.likePost(session, 'https://www.instagram.com/p/ABC/', { dryRun: false });

Runtime workspace

All runtime state lives under ~/.hyper-cloaking/ (override with HYPER_CLOAKING_HOME for sandboxed tests only):

~/.hyper-cloaking/
├── cookie.yml       # site/account cookie entries (never committed)
├── profiles/        # persistent browser profiles
├── downloads/       # downloaded files
├── evidence/        # reports and screenshots
├── logs/            # run logs
├── state/           # rate-limit windows, resumable state
└── cache/cloakbrowser/   # downloaded stealth Chromium binaries

Repository layout

plugins/hyper-cloaking/skills/hyper-cloaking/ # canonical skill (SKILL.md, engine, rules, references)
skills/hyper-cloaking/                # root mirror of the canonical skill
.claude/skills/hyper-cloaking/  # Claude Code skill mirror
.agents/skills/hyper-cloaking/  # AgentSkills mirror
.claude-plugin/marketplace.json # Claude Code marketplace manifest
.agents/plugins/marketplace.json# Codex marketplace manifest
scripts/validate.mjs            # structure + mirror-parity validation

The skill directories are kept byte-for-byte mirrored. Validate parity and metadata with npm run validate.

Development

npm run validate      # structure and mirror-parity checks
npm run lint          # oxlint over plugins, scripts, and tests
npm run format        # prettier write
npm test              # root E2E and engine unit tests
npm run ci            # complete local CI gate
node skills/hyper-cloaking/engine/cli.mjs validate --json   # engine self-check (no network)

npm test runs the root E2E suite (tests/e2e/) and the engine unit tests relocated to tests/unit/engine/ (importing the canonical plugins/hyper-cloaking/skills/hyper-cloaking/engine/ source). npm run validate proves byte-for-byte parity across the mirrored skill directories. After the first successful GitHub Actions run, configure a main branch Ruleset only after confirming that the required job checks are named quality and Node 20 compatibility; this repository does not apply that setting automatically.

---

MIT © alpox — built on CloakBrowser + Playwright MCP, for authorized browsing only.