Pagerunner

A Chrome browser automation MCP server. Connect Claude (or any MCP client) to a real Chrome session — using your existing profiles with their cookies, saved passwords, and history.

[!WARNING]
Pagerunner is early-stage software (v0.x). APIs and configuration formats may change between releases.

How it works
Setup
Using with your project
Tools
Site Intelligence
Session Checkpoints
macOS Menu Bar App
Anonymization (PII protection)
Stealth mode
Daemon (multiple Claude Code sessions / persistent state)
Snapshots
Example session
Legal & Responsible Use

How it works

Pagerunner launches Chrome with your existing user profile via CDP (Chrome DevTools Protocol) and exposes it as an MCP server over stdin/stdout. Claude can then navigate, click, type, screenshot, and run JavaScript in the live browser.

Setup

1. Install

# Option A — Homebrew (easiest on macOS/Linux):
brew tap enreign/pagerunner
brew install pagerunner

# Option B — Cargo (if you have Rust):
cargo install pagerunner
# Note: if you get "requires rustc 1.91+" despite having a newer Rust installed,
# Homebrew's Rust may be shadowing rustup's. Fix: export PATH="$HOME/.cargo/bin:$PATH"

# Option C — Pre-built binary (no dependencies):

# macOS arm64 (Apple Silicon):
curl -L https://github.com/Enreign/pagerunner/releases/latest/download/pagerunner-macos-arm64 \
  -o pagerunner && chmod +x pagerunner

# macOS x86_64 (Intel):
curl -L https://github.com/Enreign/pagerunner/releases/latest/download/pagerunner-macos-x86_64 \
  -o pagerunner && chmod +x pagerunner

# Linux x86_64:
curl -L https://github.com/Enreign/pagerunner/releases/latest/download/pagerunner-linux-x86_64 \
  -o pagerunner && chmod +x pagerunner

# macOS: if Gatekeeper blocks the binary on first run:
xattr -d com.apple.quarantine pagerunner

# Option B — install via cargo (requires Rust):
cargo install --git https://github.com/Enreign/pagerunner --locked

# Option C — build locally:
cargo build --release

2. Auto-detect Chrome profiles

pagerunner init

This reads Chrome's profile list and writes ~/.pagerunner/config.toml automatically.
Run pagerunner status to verify.

Alternatively, write ~/.pagerunner/config.toml by hand — see pagerunner example-config for the format.

3. Register as MCP server

# If installed (Options A or B — binary is in PATH):
claude mcp add pagerunner "$(which pagerunner)" mcp

# If built locally (Option C):
claude mcp add pagerunner "$(pwd)/target/release/pagerunner" mcp

For Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pagerunner": {
      "command": "/absolute/path/to/pagerunner",
      "args": ["mcp"]
    }
  }
}

Note: The mcp subcommand is required — registering just the binary path without mcp will not work.

Note: Chrome locks profile directories. Close any Chrome window using a profile before opening a Pagerunner session on it.

4. Set up in your project (optional)

In any project directory with a CLAUDE.md or AGENTS.md:

pagerunner init

Pagerunner prints a ready-to-use usage snippet and offers to append it to your project file automatically. For scripting: pagerunner init --json.

5. (Optional, --features ner builds only) Download the NER model

pagerunner download-model   # ~65MB, enables PERSON/ORG name detection

Using with your project

Copy the example agent instructions into your project root so Claude (or any agent) immediately knows how to use Pagerunner:

# Claude Code projects:
curl -sL https://raw.githubusercontent.com/Enreign/pagerunner/main/docs/examples/CLAUDE.md -o CLAUDE.md

# Other agents (Gemini, Codex, etc.):
curl -sL https://raw.githubusercontent.com/Enreign/pagerunner/main/docs/examples/AGENTS.md -o AGENTS.md

Or paste the content manually and extend it with project-specific instructions.

Using Pagerunner with Claude Code

For comprehensive guidance, workflows, and examples tailored to 4 different use cases, install the Pagerunner Skill:

# Install the skill (once available in skills.sh registry)
claude skill install pagerunner-skill

Or explore the skill repository directly: pagerunner-skill

The skill includes:

Quick starts for 4 ICPs: Solo Developer, Power User, Security-Conscious, Server-Side
11 workflow patterns: form filling, authentication, scrolling, multi-step interactions
Complete reference: all 38 tools with parameters and examples
Security guide: PII anonymization, audit logging, encryption
Real-world examples: end-to-end workflows with error handling
Troubleshooting: common issues and solutions

Start with the skill's SKILL.md to find your use case and quick start path.

Tools

Sessions & tabs

Tool	Description
`list_profiles`	List configured Chrome profiles
`open_session`	Launch Chrome for a profile, returns `session_id`
`attach_session`	Attach to an existing Chrome instance via `--remote-debugging-port`
`close_session`	Kill a Chrome session
`list_sessions`	List active sessions
`list_tabs`	List open tabs in a session
`new_tab`	Open a new tab, returns `target_id`
`close_tab`	Close a specific tab

Navigation & content

Tool	Description
`navigate`	Navigate a tab to a URL
`wait_for`	Wait for a CSS selector, URL pattern, or fixed delay
`get_content`	Get visible text content of a tab
`screenshot`	Capture a tab as PNG (saved to temp file or inline base64)
`evaluate`	Run JavaScript in a tab, returns the result

Interactions

Tool	Description
`click`	Click an element by CSS selector
`type_text`	Type text at the focused element or a given selector
`fill`	Set input value with React/Vue/Angular synthetic events
`select`	Choose a dropdown option by value
`scroll`	Scroll the page by pixels or scroll an element into view

Snapshots & tab state

Tool	Description
`save_snapshot`	Save current page cookies/localStorage to the encrypted DB
`restore_snapshot`	Restore a saved snapshot into the current tab
`list_snapshots`	List saved snapshots (optionally across all profiles)
`delete_snapshot`	Delete a saved snapshot
`save_tab_state`	Save all open tab URLs to the DB
`restore_tab_state`	Reopen the previously saved tabs

Key-value store

Tool	Description
`kv_set`	Store a value in a persistent namespace
`kv_get`	Retrieve a value by key
`kv_delete`	Delete a key
`kv_list`	List keys in a namespace (with optional prefix filter)
`kv_clear`	Delete all keys in a namespace

Network & console

Tool	Description
`get_network_log`	Inspect HTTP requests captured in a session
`get_console_log`	Capture JavaScript console output from a tab

Site intelligence

Tool	Description
`get_site_knowledge`	Inspect what Pagerunner has learned about a site (adapters, auth tokens, selector health)
`register_adapter`	Store a JS adapter for direct API calls against a site
`call_site_api`	Execute a stored adapter in the browser tab
`generate_adapter`	Auto-generate a JS adapter from network traffic using Claude (requires `ANTHROPIC_API_KEY`)

Session checkpoints

Tool	Description
`save_session_checkpoint`	Save full tab state (URLs + scroll positions) for all tabs in a session
`restore_session_checkpoint`	Reopen all saved tabs and navigate to stored URLs
`list_session_checkpoints`	List saved checkpoints for a profile
`delete_session_checkpoint`	Remove a checkpoint by ID

Site Intelligence

Pagerunner learns about sites as you use them and can call site APIs directly using your session credentials — no separate auth setup required.

Adapters are short JS functions stored in the encrypted DB and executed in the browser tab. Use them to call APIs that a site exposes (typically the same API the web UI uses):

register_adapter(origin="https://github.com", name="list-issues",
  description="List open issues for a repo",
  js_code="async ({owner, repo}) => { const r = await fetch(...); return r.json() }")

call_site_api(session_id, target_id, origin="https://github.com",
  name="list-issues", params={"owner": "Enreign", "repo": "pagerunner"})

Seed adapters for GitHub, Linear, Jira, Notion, and Gmail are built in.

Auth token detection — Bearer tokens, API keys, and session cookies discovered in network traffic are stored in the encrypted site vault. Adapters automatically have access to them via the credentials argument.

Selector stability — click, fill, and select track success/failure rates per selector. A fragility warning appears in the tool response when a selector fails >30% of the time over ≥5 uses.

Session Checkpoints

Save complete browser state (all open tabs with URLs and scroll positions) and restore it in any future session:

save_session_checkpoint(session_id, name="before-review")
  → checkpoint_id: cp_abc123

restore_session_checkpoint(session_id, checkpoint_id="cp_abc123")
  → reopens all saved tabs at their stored URLs

Checkpoints are stored in the encrypted DB and scoped to a profile.

macOS Menu Bar App

A native Swift companion app lives at apps/menubar/. It shows all Chrome profiles, active sessions, open tabs, and daemon status from the menu bar — no terminal required.

Features:

One-click open/close sessions and save checkpoints
Agent profiles shown with a distinct CPU icon in a separate section
Add Profile flow: discovers unconfigured Chrome profiles or creates new agent profiles
macOS native notifications: daemon stopped, session crashed, checkpoint saved
Global hotkey and auto-update via Sparkle 2.x

Build and run:

pagerunner daemon &
cd apps/menubar
bash scripts/package.sh   # builds + bundles into scripts/Pagerunner.app
open scripts/Pagerunner.app

Anonymization (PII protection)

Pass anonymize: true to open_session to strip PII from all get_content and evaluate
results before they reach Claude. Screenshots are blocked in anonymization mode.

{ "tool": "open_session", "profile": "personal", "anonymize": true }

Detected by default: EMAIL, PHONE, CREDIT_CARD, IBAN, SSN, IP
With --features ner build: also detects PERSON and ORG names via a local ONNX model

Modes

tokenize (default): replaces PII with tokens like [EMAIL:a3f9b2]. Pass tokens back to
fill/type_text — Pagerunner de-tokenizes before writing to the DOM.
redact: one-way replacement with [EMAIL] — no vault, no de-tokenization.

NER setup (PERSON and ORG name detection)

# 1. Build with NER support:
cargo build --release --features ner

# 2. Download the model (one-time, ~65MB):
pagerunner download-model

Disable globally in ~/.pagerunner/config.toml:

[ner]
enabled = false

Stealth mode

Pass stealth: true to open_session to enable anti-detection: hides automation signals, injects scripts to mask navigator.webdriver, and adds human-like delays between inputs.

{ "tool": "open_session", "profile": "personal", "stealth": true }

Example session

open_session(profile="personal")          → session_id: abc123
new_tab(session_id, url="https://...")    → target_id: TAB456
get_content(session_id, target_id)        → "page text..."
click(session_id, target_id, "#button")
type_text(session_id, target_id, "hello", selector="#input")
screenshot(session_id, target_id)         → "data:image/png;base64,..."
close_session(session_id)

Daemon (multiple Claude Code sessions / persistent state)

By default each pagerunner mcp process opens the database directly — only one can run at a time. If you open Pagerunner in a second Claude Code window you'll hit a DB lock error.

Start the daemon once to share state across any number of sessions:

pagerunner daemon &

Each pagerunner mcp instance automatically detects the daemon, connects to it over a Unix socket (~/.pagerunner/daemon.sock), and proxies all tool calls through it. All Claude Code windows share the same open browsers, KV store, and snapshots.

To stop:

pkill -f "pagerunner daemon"

Install as a background service (starts at login, restarts on crash):

./scripts/install-launchd.sh

The script detects your installed pagerunner binary automatically. Logs at ~/.pagerunner/daemon.log.

Note: After installing the daemon service, restart Claude Code. On the next launch,
the daemon starts first (via launchd) and the MCP server connects to it in proxy mode.
If Claude Code is already running when you install the daemon, you need two restarts:
one to let launchd start the daemon, and one for the MCP server to reconnect to it.

Snapshots

Save authenticated browser state to the encrypted local DB:

save_snapshot(session_id, target_id, origin="https://github.com")

Restore it in any future session:

restore_snapshot(session_id, target_id, origin="https://github.com")

Snapshots are encrypted with AES-256-GCM. The key is stored in macOS Keychain under pagerunner / db_key — never written to disk in plaintext.

Legal & Responsible Use

Pagerunner automates a browser you own, using your own credentials. You are responsible for
complying with the Terms of Service of any website you automate, applicable data protection
laws (GDPR, CCPA), and authorized-access requirements (CFAA and equivalents).

Using anonymize: true is recommended for any workflow that involves processing personal
data belonging to other people.

See DISCLAIMER.md for the full legal disclaimer, limitation of liability,
and responsible use obligations.

If this project helps you, star the repo — it helps others find it.

Pagerunner — The Browser Layer That Learns