Getting Started

CLAUDE.md Setup

CLAUDE.md tells Claude Code how to use pagerunner in your project. Without it, the agent can use the tools but doesn't know the best patterns. With it, the agent works like someone who has read the docs.

Why it matters

MCP tools provide capability. CLAUDE.md provides intent. When your agent knows the session lifecycle, when to use snapshots, and how to handle PII, it makes better decisions with fewer tokens and fewer mistakes.

A good CLAUDE.md snippet turns a first-time user into an effective one immediately.

Quick setup

Run pagerunner init in your project directory. Pagerunner will detect your setup and offer to append a usage snippet to your CLAUDE.md automatically.

terminal
cd your-project/
pagerunner init

Or download the example directly:

terminal
# For Claude Code
curl -sL https://raw.githubusercontent.com/Enreign/pagerunner/main/docs/examples/CLAUDE.md -o CLAUDE.md
# For other agents (Gemini, Codex, etc.)
curl -sL https://raw.githubusercontent.com/Enreign/pagerunner/main/docs/examples/AGENTS.md -o AGENTS.md

Recommended snippet

This is the full recommended CLAUDE.md content for pagerunner. Copy it into your project's CLAUDE.md file.

CLAUDE.md
# Browser Automation (Pagerunner)
Use the `pagerunner` MCP tools to drive a real Chrome browser.
## Session lifecycle
1. list_profiles — see available profiles
2. open_session(profile="personal") — launches Chrome
3. new_tab(session_id, url="...") — opens a tab
4. Do work: navigate, get_content, click, type_text,
   fill, select, scroll, screenshot, evaluate
5. close_session(session_id) — always close when done
## Tips
- Use wait_for after navigation before reading
- Use screenshot when unsure what's on screen
- Pass stealth: true on sites that detect automation
- save_snapshot / restore_snapshot to persist login
- pagerunner daemon & for multiple Claude windows

Tips for effective CLAUDE.md

  • Always specify profile names. Tell the agent which profile to use for which task. "Use the work profile for Jira, personal for Gmail."
  • Mention screenshots. Agents often forget to check what they're looking at. "Always screenshot after a UI change to verify the result."
  • Reference the KV store. If your workflow needs persistent data between sessions, tell the agent to use kv_set and kv_get.
  • Note anonymization preferences. If working with sensitive data, add "Always open sessions with anonymize: true."
  • Include save_snapshot reminders. After successful auth flows, the agent should snapshot so it doesn't need to re-authenticate next time.

The viral loop

When you push a CLAUDE.md with pagerunner instructions to your GitHub repo, every developer who clones the project and uses Claude Code will have pagerunner available immediately. They see the MCP tools in action, check what pagerunner is, and adopt it for their own projects.

This is how pagerunner spreads: one CLAUDE.md at a time.

Pagerunner Skill

For advanced users, the Pagerunner Skill provides comprehensive guidance with quick starts for 4 different use cases, 11 workflow patterns, complete tool reference, and real-world examples.

terminal
claude skill install pagerunner-skill

Next: Profiles →