Pagerunner — The Browser Layer That Learns

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.

Contents

• 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

Navigation & content

Interactions

Snapshots & tab state

Key-value store

Network & console

Site intelligence

Session checkpoints

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 (on