Leapfrog

Multi-session browser MCP for AI agents.
34 tools. 15 parallel sessions. Stealth. HUD. Self-improvement. Up to 10x fewer tokens.

npm i leapfrog  |  Works with Claude Code, Cursor, Windsurf

---

The Problem

Playwright MCP sends ~14,000 tokens for a content-heavy page like Hacker News. Most of that is noise. Your context window fills up. Your agent gets confused. You pay for it.

Leapfrog sends ~1,400 tokens. Same page. Same information. Up to 10x less noise.

┌─────────────────────────────────────────────────────┐
│  Playwright MCP                                     │
│  ████████████████████████████████████████  ~14,000   │
│                                                     │
│  Leapfrog                                           │
│  █████                                    ~1,400    │
└─────────────────────────────────────────────────────┘
          tokens per page (Hacker News, real test)

Savings range from 2-10x depending on page complexity. Content-heavy pages see the biggest wins. Dense forms see the smallest. The median across real-world sites is ~4-5x.

Quick Start

npx leapfrog --doctor          # verify everything works
npx leapfrog --stealth-audit   # test all 19 stealth patches
npx leapfrog --config          # print MCP config to paste

Add to ~/.mcp.json (Claude Code) or your editor's MCP config:

{
  "leapfrog": {
    "command": "npx",
    "args": ["-y", "leapfrog"],
    "env": {
      "LEAP_MAX_SESSIONS": "15",
      "LEAP_TILE": "true",
      "LEAP_HUD": "true",
      "LEAP_SOUND": "true",
      "LEAP_AUTO_CONSENT": "true"
    }
  }
}

Leapfrog uses playwright-core (15MB) instead of playwright (1.6GB) and does not bundle a browser. Either:

• Set LEAP_CHANNEL=chrome to use your installed Chrome/Chromium
• Or run npx playwright-core install chromium to install the bundled Chromium binary

Feature Matrix

	Leapfrog	Playwright MCP	agent-browser
Tokens per page	~1,200-2,500	~3,800-15,000	~300
Parallel sessions	15	1	1
Session isolation	Yes	No	No
Multi-tab / popups	Yes	No	No
Network intercept	Yes	No	No
Console capture	Yes	Yes	No
Stealth / anti-bot	Yes	No	No
Smart wait (5 types)	Yes	Basic	No
Crash recovery	Yes	No	No
Batch actions (100/call)	Yes	No	No
Init script injection	Yes	Yes	No
Drag / upload / resize	Yes	Yes	No
Per-session proxy	Yes	No	No
Humanization (opt-in)	Yes	No	No
Auth profile reuse	Yes	No	No
Cookie persistence	Yes	No	No
Page classification (18)	Yes	No	No
Session memory	Yes	No	No
API intelligence	Yes	No	No
Adaptive wait + auto-retry	Yes	No	No
Record / replay	Yes	No	No
Pagination extraction	Yes	No	No
Incremental snapshots (diff)	Yes	No	No
Stealth self-test CLI	Yes	No	No
SSRF protection	Yes	No	No

Stealth

Leapfrog ships 19 anti-detection patches enabled by default (LEAP_STEALTH=true). These cover the vectors that fingerprint services like CreepJS and fingerprint-pro actually check:

• Client Hints brands (strips HeadlessChrome)
• navigator.webdriver forced to undefined
• WebGL vendor/renderer (replaces SwiftShader with real GPU strings)
• Connection RTT (non-zero)
• Alert dismiss timing (human-speed delay)
• Window outer/inner height offset
• MIME type array population
• Platform inference from user agent
• chrome.app emulation
• iframe contentWindow protection
• Media codec spoofing (canPlayType)
• document.hasFocus() override
• Source URL comment stripping
• Custom UA + stealth coexistence (custom user agents no longer disable stealth context)
• CDP Runtime.enable detection (Error.prepareStackTrace filter)
• Permissions API spoofing (20+ permission types)
• AudioContext fingerprint noise (getChannelData/getFloatFrequencyData)
• WebRTC IP leak prevention (ICE candidate filtering)
• Font enumeration fingerprint spoofing

Per-session stealth control: pass stealth: false in session_create to disable for a specific session.

Humanization (Experimental)

Set LEAP_HUMANIZE=true to enable human-like browser interaction. This is opt-in and adds latency in exchange for more realistic behavior. Six modules:

• Mouse — Bezier curve paths with Fitts's Law timing and micro-tremor jitter
• Typing — Log-normal inter-key delays (200ms median), key dwell time, bigram-aware speed, rollover typing
• Scroll — Inertial simulation with ramp-up and momentum decay (touchpad/mouse-wheel physics)
• Pause — Inter-action "think" delays that simulate cognitive gaps between actions
• Fingerprint — Coherent browser fingerprint generation (platform, device memory, GPU, timezone)
• Utils — Shared math primitives (Box-Muller gaussian, distributions)

Page Classification

Every navigate and snapshot call automatically classifies the page type using weighted signal scoring (no LLM required). 18 types:

login · search-results · product · product-list · checkout · article · dashboard · form · error · challenge · landing · documentation · profile · media · feed · qa · ecommerce · unknown

Classification drives smarter snapshot extraction — login pages surface form fields, articles surface content, dashboards surface interactive elements.

Harness Intelligence

The harness tracks every action in a session and classifies outcomes:

• Action outcome classification — SUCCESS, SILENT_CLICK, NAVIGATION, WRONG_ELEMENT, BLOCKED, ERROR, PENDING
• Bot redirect detection — detects when a site redirects to a challenge or block page after an action
• Loop detection — warns when the agent is stuck clicking the same element, ping-ponging between URLs, or repeating actions
• Session memory — session_memory tool recalls actions after context window compression

Cookie Persistence

Persistent browser profiles now use context.cookies() + addCookies() instead of storageState(), which returns empty on persistent contexts. Auth state survives across sessions.

Adaptive Wait + Stealth Escalation

Navigate automatically retries with fallback strategies when pages fail to load:

1. Try load (fastest) — if empty, retry with networkidle (10s cap)
2. If networkidle times out (Amazon, ad-heavy sites), fall back to domcontentloaded
3. If blocked/challenged, escalate stealth: random delays → wait for JS challenge → rotate session with fresh fingerprint
4. Profile sessions (auth'd) never have their session destroyed — hard-capped at Level 2

Opt-out with autoRetry: false on navigate. Control max escalation with maxRetryLevel (0-5, default 3).

Record / Replay

Export a session's action history as a replayable recording, then replay it in new sessions:

• session_export — creates parameterized JSON or Playwright script from session history. @eN refs resolved to stable CSS selectors. Auto-detects emails, passwords, URLs as {{placeholders}}.
• session_replay — replays a recording with parameter overrides. Supports onError: 'stop' or 'skip'.

Turn one-off agent workflows into reusable automations.

Pagination Extraction

Extract data across multiple pages in a single tool call:

• Click-next — auto-detects "Next" buttons, pagination links, "Load more" buttons
• Infinite scroll — scrolls and waits for new content via DOM hash comparison
• URL pattern — increments ?page={page} or custom patterns

Replaces 3-4 tool calls per page. Cap: 50 pages, 100K total chars. Stops on: no next button, empty page, duplicate content, or bot detection.

Incremental Snapshots

The diff tool returns only what changed since the last snapshot — additions, removals, changes. Massive token savings for monitoring and polling workflows.

HUD Overlays (LEAP_HUD=true)

When running headed, Leapfrog overlays visual feedback on every session:

• Click ripple — expanding green circle at click coordinates (agent actions only)
• Scroll-to-target — scrollIntoView before clicks so you can see what the agent is about to click

Minimal by design. No borders, no status bars, no cursor overlay — just the feedback that matters.

Human Intervention

Leapfrog auto-detects situations that need a human — CAPTCHAs, login forms, OAuth redirects, Cloudflare challenges — and pauses the agent until you handle it.

• Detects reCAPTCHA, hCaptcha, Turnstile, login forms, OAuth redirects, Cloudflare challenges
• Red persistent top bar (32px, #ef4444) with reason text + tab title changes to "NEEDS HUMAN" + chime
• Sound chime + macOS notification on detection
• wait_for_human tool — agent calls when stuck, blocks until you click Done

Cookie Consent Auto-Dismiss (LEAP_AUTO_CONSENT=true)

Automatically dismisses cookie consent banners across 10 frameworks (OneTrust, CookieBot, TrustArc, Quantcast, Didomi, Cookielaw, Osano, Usercentrics, + generic) plus text-matching fallback. Per-domain selector caching for instant replay on revisit.

Tracing (LEAP_TRACE=true)

Per-session Playwright tracing with screenshots + DOM snapshots. Export ZIP files viewable at trace.playwright.dev via the session_export_trace tool. Auto-saves on session destroy.

Self-Improvement

Leapfrog learns from experience. Per-domain knowledge stored at ~/.leapfrog/domains/:

• Wait strategy learning — records which wait method worked per domain + running average timing
• Stealth tier learning — auto-escalates after blocks, starts at the learned tier on revisit
• API endpoint caching — remembers discovered endpoints for faster API intelligence
• LRU eviction at 500 domains. Inspect with the domain_knowledge tool.

SSRF Hardening

URL validation blocks hex-encoded IPs (0x7f000001), octal notation (0177.0.0.1), CGNAT ranges (100.64.0.0/10), and redirect chains that resolve to internal addresses. Localhost and 127.0.0.0/8 are allowed by default for local dev workflows — set LEAP_BLOCK_LOCALHOST=true to block them.

The Ecosystem

Leapfrog uses pond metaphors to keep things memorable. Your agent is the frog.

Concept	Leapfrog term	What it means
Sessions	Ponds	Isolated browser contexts — cookies, storage, state
Tabs	Lily pads	Where the frog lands within a pond
Navigate	Leap	Jump to a URL, get a compact snapshot back
Snapshots	Surface	What you see on the surface — interactive @eN refs
Network traffic	Ripple	HTTP requests flowing under the surface
Console errors	Croak	Something went wrong in the browser
Stealth mode	Camouflage	Anti-bot evasion patches

All 34 Tools

Pond Management (9)

Tool	What it does
session_create	Open a new pond — isolated cookies, state, viewport, locale, timezone, stealth, proxy
session_destroy	Drain a pond and free the slot
session_list	See all active ponds with URLs and idle times
session_save_profile	Save auth state to disk for future ponds
session_list_profiles	List saved auth profiles
pool_status	Pool stats, memory, uptime
session_health	Is the pond healthy? Browser connected, page responsive?
profile_list	List saved persistent browser profiles
profile_delete	Delete a saved persistent browser profile and its data

Navigation & Snapshots (12)

Tool	What it does
navigate	Leap to a URL, return a compact @eN snapshot. Adaptive wait + stealth escalation built in.
snapshot	Re-read the surface (scope with CSS selector)
diff	Incremental snapshot — returns only what changed since last snapshot
act	Click, fill, type, check, select, press, scroll, hover, mousemove, drag, upload, resize, back, forward
batch_actions	Up to 100 sequential actions in one MCP call — eliminates round-trip overhead
paginate	Extract data across multiple pages in one call (click-next, scroll, URL pattern)
add_init_script	Inject JS that runs before every page load, persists across navigations
wait_for	Wait for element / text / network idle / navigation / JS expression
screenshot	Capture PNG (full page or element)
extract	Pull text, HTML, title, URL, or evaluate JS
session_memory	Recall actions performed in this session — recovers context after compression
session_export	Export session history as a replayable JSON recording or Playwright script

Tab Management (3)

Tool	What it does
tabs_list	List all pads in a pond
tab_switch	Hop to another pad (-1 for most recent popup)
tab_close	Close a pad (can't close the last one)

Agent Intelligence (3)

Tool	What it does
wait_for_human	Pause for human intervention — blocks until user clicks Done on the @..@ overlay
domain_knowledge	Inspect what Leapfrog has learned about a domain (wait strategies, stealth tiers, endpoints)
session_export_trace	Export a Playwright trace ZIP — viewable at trace.playwright.dev

Network & API Intelligence (7)

Tool	What it does
network_log	See HTTP traffic — filter by URL, method, status, content-type
console_log	Read browser console output, filtered by level
network_intercept	Block, mock, or log requests by URL pattern
api_discover	List JSON APIs the page has called, classified by category (data, tracking, auth, cdn, ads)
api_export	Generate an OpenAPI v3 spec from observed API traffic
execute	Run a Playwright script in a sandboxed environment — replaces 5-20 sequential MCP round trips
session_replay	Replay a recording in the current session with parameter overrides

Environment Variables

Variable	Default	Description
LEAP_MAX_SESSIONS	15	Max concurrent sessions
LEAP_IDLE_TIMEOUT	1800000	Session idle timeout in ms (30 min). Set 0 to disable.
LEAP_HEADLESS	true	Set false to watch the browser
LEAP_CHANNEL	(bundled chromium)	Set chrome to use your installed Chrome
LEAP_ALLOW_JS	true	Allow JS evaluation in extract and wait_for
LEAP_STEALTH	true	Stealth mode (anti-bot evasion) — 19 patches
LEAP_HUMANIZE	false	Experimental. Human-like mouse movement, typing cadence, and scroll behavior.
LEAP_ALLOW_EXECUTE	true	Allow the execute tool (sandboxed Playwright scripts)
LEAP_BLOCK_LOCALHOST	false	Block localhost/127.x.x.x (allowed by default for local dev)
LEAP_PROFILES_DIR	~/.leapfrog/chrome-profiles	Directory for persistent browser profiles
LEAP_TILE	false	Tile sessions in a grid and start sidecar HTTP server on :9222
LEAP_HUD	false	Click ripple on agent actions and scroll-to-target
LEAP_SOUND	false	Marimba chime on intervention detection (macOS)
LEAP_NOTIFY	false	macOS notification center alerts on intervention detection
LEAP_AUTO_CONSENT	true	Auto-dismiss cookie consent banners (10 frameworks + fallback)
LEAP_TRACE	false	Per-session Playwright tracing (screenshots + DOM snapshots)
LEAP_LOG_LEVEL	info	debug / info / warn / error

Tests

 778 passing across 31 suites

Session management, snapshot engine, network intelligence, tab management, security, SSRF protection, stealth patches (19), humanization (mouse, typing, scroll), page classification, harness intelligence, API intelligence, script executor, extended actions, HUD overlays, human intervention, cookie consent, domain knowledge, tracing, sidecar HTTP, bug regression, stress tests, benchmarks.

npm test

Requirements

• Node.js >= 20
• Chromium — use system Chrome (LEAP_CHANNEL=chrome) or install via npx playwright-core install chromium

License

MIT