Skip to content

For agents & LLMs

Clearcote is laid out so automated tooling can navigate, integrate and contribute as easily as a human.

Drop the whole project into your agent

One click copies the entire documentation — overview, architecture, every flag, install, verification, build and roadmap — as a single prompt-ready block. Paste it into Claude, Codex or Cursor for instant full context.

View /llms-full.txt ↗

Machine-readable summary

A concise, plaintext project summary lives at /llms.txt, and the complete documentation flattened into one prompt-ready file is at /llms-full.txt. The repository also ships an AGENTS.md describing layout and conventions for contributors.

json
{
  "name": "Clearcote",
  "kind": "open-source anti-detect Chromium browser",
  "base": "ungoogled-chromium 149",
  "identity_model": "engine-level, coherent, per-site (farbling-style)",
  "automation": "drop-in for Playwright & Puppeteer (executablePath)",
  "platforms": ["windows-x64"],
  "license": "BSD-3-Clause",
  "repo": "https://github.com/clearcotelabs/clearcote-browser",
  "verify": "GPG-signed + sha256, pinned key",
  "control_via": "chromium command-line switches (args)"
}

Minimal integration recipe

  1. Resolve the binary path (e.g. C:\clearcote\chrome.exe).
  2. Launch via your existing driver with executablePath.
  3. Pass a deterministic --fingerprint=<seed> derived from the identity you're acting as.
  4. Keep platform / timezone / locale coherent (see the flag reference).
python
from playwright.sync_api import sync_playwright

SEED = "agent:" + task_id          # stable, reproducible identity per task

with sync_playwright() as p:
    browser = p.chromium.launch(
        executable_path=r"C:\clearcote\chrome.exe",
        args=[f"--fingerprint={SEED}", "--fingerprint-platform=windows"],
    )
    page = browser.new_page()
    page.goto("https://example.com")

For higher-fidelity identity, agent code can import a real Chrome machine's profile instead of the synthetic seed-derived one — pass launch(fingerprint_profile="profile.json") (Node: fingerprintProfile). Capture a profile with the bundled collector, or convert one from the open 10k-record fingerprint dataset; present fields override the seed and absent fields fall back to it, so partial profiles stay coherent. See Playwright & Puppeteer for examples.

In-browser AI agent

Clearcote ships an optional, opt-in AI agent that drives a real page autonomously. It perceives the live page, asks a user-configured LLM what to do next, and acts through Chrome's Actor framework with real trusted input — so the interaction looks identical to a human using the browser. It is off by default (inactive unless you supply an agent key or the agent switches) and brings your own key: point it at any OpenAI-compatible / OpenRouter endpoint. Password fields are redacted before anything is sent to the model. The agent needs a regular, persistent profile — not incognito.

From the SDK, launch_agent (Node: launchAgent) returns a persistent BrowserContext, and run_agent_task(page, goal, max_steps=...) (Node: runAgentTask) drives it, returning { success, finalText, steps, stepsJson }.

python
from clearcote import launch_agent, run_agent_task

# Returns a persistent BrowserContext (needs a real profile, not incognito).
ctx = launch_agent(
    agent_llm_key="sk-or-...",                 # or $OPENROUTER_API_KEY / $CLEARCOTE_AGENT_KEY
    agent_model="openai/gpt-4o-mini",
    agent_tool_mode="tools",                   # or "json"
)
page = ctx.new_page()
page.goto("https://example.com")

result = run_agent_task(
    page,
    goal="Find the pricing page and read the cheapest plan",
    model="openai/gpt-4o-mini",                # optional per-task override
    max_steps=20,
)
print(result["success"], result["finalText"], result["steps"])

Agent launch options map directly to binary switches: agent_llm_url / agentLlmUrl (--agent-llm-url), agent_llm_key / agentLlmKey (--agent-llm-key), agent_model / agentModel (--agent-model), agent_tool_mode / agentToolMode (--agent-tool-mode), and agent_typing / agentTyping. Setting a key or LLM URL turns the agent on.

agent_typing / agentTyping tunes the agent's keystroke cadence: human (default) types with per-key keydown/keyup timing and keeps long text typing key-by-key, fast is the quick engine cadence, and instant is one-shot. The default avoids the two typing tells — uniform machine-perfect timing, and long text being instant-pasted (which emits zero keystroke events).

clearcote-agent CLI

The same agent is available as a CLI for quick, scriptable runs. Pass a one-shot goal, or drop into an interactive REPL. The model key comes from --key or the $OPENROUTER_API_KEY / $CLEARCOTE_AGENT_KEY environment variables.

bash
# One-shot: run a single goal against a URL, then exit
clearcote-agent --goal "Accept cookies and list the top 3 headlines" --url https://example.com

# Interactive REPL: keep the browser open and issue goals one at a time
clearcote-agent -i

# Use a custom endpoint/model, persistent profile, proxy and step cap
clearcote-agent --llm-url http://localhost:8000/v1 --model local/model \
  --profile ~/.clearcote/agent-profile --proxy http://user:pass@host:8080 \
  --max-steps 12 --goal "Open the dashboard" --url example.com

# Provide the key explicitly (otherwise read from the environment)
clearcote-agent --key sk-or-... --tool-mode json --json \
  --goal "Search for 'clearcote' and open the first result" --url https://example.com

CLI options include --llm-url, --tool-mode, --max-steps, --profile, --headless, --executable, --fingerprint, --proxy, --timezone, and --json. A bare host passed to --url is upgraded to HTTPS.

Where to look

Build deterministic identities: derive the seed from a stable id (tenant, account, task) so the same actor always gets the same browser fingerprint — reproducible and debuggable.