pagerunner

# Pagerunner

<p align="center">
  <a href="https://github.com/Enreign/pagerunner/actions/workflows/ci.yml"><img src="https://github.com/Enreign/pagerunner/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/Enreign/pagerunner/releases/latest"><img src="https://img.shields.io/github/v/release/Enreign/pagerunner" alt="Release"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <img src="https://img.shields.io/badge/rust-1.91%2B-orange" alt="Rust 1.91+">
</p>

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](#how-it-works)
- [Setup](#setup)
- [Using with your project](#using-with-your-project)
- [Tools](#tools)
- [Site Intelligence](#site-intelligence)
- [Session Checkpoints](#session-checkpoints)
- [macOS Menu Bar App](#macos-menu-bar-app)
- [Anonymization (PII protection)](#anonymization-pii-protection)
- [Stealth mode](#stealth-mode)
- [Daemon (multiple Claude Code sessions / persistent state)](#daemon-multiple-claude-code-sessions--persistent-state)
- [Snapshots](#snapshots)
- [Example session](#example-session)
- [Legal & Responsible Use](#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**

```bash
# 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**

```bash
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**

```bash
# 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`:

```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`:

```bash
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**

```bash
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:

```bash
# 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**:

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

Or explore the skill repository directly: [pagerunner-skill](https://github.com/Enreign/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](https://github.com/Enreign/pagerunner-skill/blob/main/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 |

[truncated…]