agentcloak

Highlights

• Pages as structured text -- every page becomes an accessibility tree with [N] indexed elements; agents act on refs or a unique CSS selector for known controls
• CLI + Skill on-demand loading -- agents call cloak via Bash; the Skill lazy-loads at ~300 tokens (vs ~6,000 for MCP tool definitions)
• CloakBrowser built-in stealth -- 57 C++ patches on Chromium for realistic browser fingerprinting; agents browse without being misidentified as bots
• Session reuse -- save/restore login profiles (cookies + localStorage auto-persisted across launches, so SPAs that stash auth tokens client-side stay logged in) + RemoteBridge to operate your real Chrome browser
• Network config -- proxy (SOCKS5/HTTP), DNS-over-HTTPS control, and custom Chromium args via cloak config set
• Workspace-aware sessions -- one daemon serves every Git worktree or plain directory with its own pages, queue and refs; login stays shared by default, with opt-in per-workspace storage
• Evidence you can trust -- screenshots report URL, title, viewport, DPR and pixel size; --expect-url / --expect-path reject silent redirects; --annotate labels [N] refs on the image; record captures WebM or frame archives
• Realistic input and emulation -- timed drag with per-step samples, coordinate hover, key aliases, live viewport/DPR changes, color-scheme and reduced-motion emulation (touch/pointer needs a headed browser)
• Recoverable by design -- bounded per-session queues, session close --force for frozen pages, request hold/release, pending-request observation, and one locked daemon per state directory
• Spells + API capture -- wrap common site operations as one-liners; capture traffic, analyze patterns, generate spells automatically
• Web reverse engineering -- CDP-native debugger, network route interception, WebSocket/SSE capture, init-script hooks, and source-map decode -- one tool covers 90%+ of browser RE
• MCP server with 43 tools -- full compatibility with MCP-native clients (Claude Code, Codex, Cursor, etc.)

Installation

Requires Python 3.12+

[!TIP] Agent-assisted install -- copy this to your AI coding agent:

Install and configure agentcloak following this guide:
https://github.com/shayuc137/agentcloak/blob/main/docs/en/getting-started/installation.md

# Recommended -- isolated environment, no PEP 668 hassle
uv tool install agentcloak     # or: pipx install agentcloak

cloak skill install            # installs the Skill bundle to your agent platform
cloak doctor --fix             # verify environment + download CloakBrowser

python -m venv .venv && source .venv/bin/activate
pip install agentcloak

sudo apt-get install -y xvfb

Quick Start

The daemon starts automatically on the first command.

# Navigate and get the page snapshot in one call
cloak navigate "https://example.com" --snap

stdout is the answer itself — text-first, no JSON parsing required:

https://example.com/ | Example Domain

# Example Domain | https://example.com/ | 8 nodes (1 interactive) | seq=1
  heading "Example Domain" level=1
  [1] link "Learn more" href="https://iana.org/domains/example"

# Interact using [N] refs (positional or --index N) -- --snap returns a fresh snapshot
cloak fill 3 "search query" --snap
cloak press Enter

# Take a screenshot (stdout = file path)
cloak screenshot

Errors go to stderr with a recovery hint and a non-zero exit code:

Error [element_not_found]: Element [99] not in selector_map (1 entries)
  -> run 'snapshot' to refresh the selector_map, or re-snapshot if the page changed

Need the legacy JSON envelope for scripts? Pass --json (or set AGENTCLOAK_OUTPUT=json):

cloak --json snapshot | jq -r '.data.tree_text'

The --snap flag on navigate and action commands keeps the observe-act loop tight -- no separate snapshot call needed between steps.

See the full Quick Start tutorial for login persistence, profile management, and API capture.

Usage Modes

Skill + CLI -- three commands. The cloak skill install subcommand copies the bundle from the wheel and symlinks every detected agent platform to a single canonical source under ~/.agentcloak/skills/agentcloak/:

# 1. Install agentcloak (CLI + daemon + stealth browser)
uv tool install agentcloak    # or: pipx install agentcloak (or pip install inside a venv)

# 2. Verify the environment (downloads CloakBrowser binary on first run)
cloak doctor --fix

# 3. Install the Skill bundle (interactive menu picks your agent platform)
cloak skill install

Non-interactive variants for scripted setup:

cloak skill install --platform claude         # ~/.claude/skills/
cloak skill install --platform codex          # ~/.codex/skills/
cloak skill install --platform all            # every detected platform
cloak skill install --path /custom/skills/dir # arbitrary location

Run cloak skill update after upgrading agentcloak to refresh the bundle (symlinked installs pick up changes automatically — copy-installs need a re-run). cloak skill uninstall removes every link the installer created.

See the Skill installation guide for the offline curl+tar alternative and Windows notes.

MCP Server -- one-command setup for Claude Code:

claude mcp add agentcloak -- agentcloak-mcp

{
  "mcpServers": {
    "agentcloak": {
      "command": "agentcloak-mcp"
    }
  }
}

{
  "mcpServers": {
    "agentcloak": {
      "command": "uvx",
      "args": ["agentcloak[mcp]"]
    }
  }
}

See the full MCP setup guide for details.

Browser Backends

See the backends guide for configuration details and trade-offs.

Configuration

Set AGENTCLOAK_HOME to isolate the full state directory (config, profiles and runtime records). Each directory has one daemon owner; use a distinct AGENTCLOAK_PORT for a parallel instance. See the configuration reference.

cloak config list                                       # all settings with sources
cloak config set browser.proxy "socks5://host:1080"     # set a value
cloak config get browser.proxy                          # read a value
cloak config add browser.extra_args "--lang=ja-JP"      # append to a list
cloak config unset browser.proxy                        # reset to default

Key network settings:

# ~/.agentcloak/config.toml
[browser]
proxy = "socks5://user:pass@host:1080"   # upstream proxy (SOCKS5/HTTP)
dns_over_https = false                    # default: disabled, respects system DNS
extra_args = ["--disable-background-networking"]

All settings also accept environment variables (AGENTCLOAK_PROXY, AGENTCLOAK_DNS_OVER_HTTPS, AGENTCLOAK_EXTRA_ARGS). Per-profile overrides can live at ~/.agentcloak/profiles/<name>/config.toml (same schema, only the fields you set — loaded when that profile is launched). See the config reference for the full list.

Architecture

graph TD
    subgraph Surface["Surface Layer"]
        Skill["Skill + CLI<br/>~300 tokens"]
        MCP["MCP Server<br/>43 tools"]
    end

    subgraph Engine["Engine"]
        Daemon["Daemon<br/>FastAPI + uvicorn + seq counter"]
    end

    subgraph Backends["Browser Backends"]
        Cloak["CloakBrowser<br/>stealth default"]
        PW["Playwright<br/>fallback"]
        Bridge["RemoteBridge<br/>real Chrome"]
    end

    Skill --> Daemon
    MCP --> Daemon
    Daemon --> Cloak
    Daemon --> PW
    Daemon --> Bridge

All backends extend a unified BrowserContextBase ABC. The base owns ~900 lines of shared behaviour (action dispatch, batch, dialog, self-healing); subclasses only implement 45 atomic operations. Layer isolation is enforced: CLI cannot import browser internals, daemon cannot import CLI, backends import neither.

See the architecture docs for a deeper walkthrough.

Documentation

Security

For vulnerability reports, see SECURITY.md.

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup, code style, and PR guidelines.

Acknowledgments

Built on CloakBrowser (stealth Chromium) and httpcloak (TLS fingerprint proxy).

Design informed by bb-browser, browser-use, OpenCLI, GenericAgent, pinchtab, open-codex-computer-use, and Scrapling.

License

MIT