Core Concepts

Site Knowledge

Pagerunner learns from every session. It tracks which selectors work, discovers API endpoints from network traffic, and stores reusable adapters for calling site APIs directly. This is what makes pagerunner compound — repeated tasks get faster and more reliable over time.

What pagerunner learns

Every time you interact with a site, pagerunner records knowledge about it:

  • Selector stability — tracks success/failure rates per CSS selector. A fragility warning appears when a selector fails more than 30% of the time over 5+ uses.
  • Auth tokens — Bearer tokens, API keys, and session cookies discovered in network traffic are stored in the encrypted site vault.
  • API endpoints — learns which API endpoints a site uses from captured network requests.
  • Adapters — reusable JS functions for calling site APIs directly, bypassing the DOM entirely.

Inspecting site knowledge

site knowledge
get_site_knowledge(origin="https://github.com")
→ adapters, auth tokens, selector health, API endpoints

Adapters

Adapters are short JS functions stored in the encrypted database and executed in the browser tab. Instead of clicking through a UI, an adapter calls the same API the web app uses — faster, more reliable, and less token-intensive.

register an adapter
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(`/api/repos/${owner}/${repo}/issues`);
    return r.json();
  }"
)
call an adapter
call_site_api(
  session_id, target_id,
  origin="https://github.com",
  name="list-issues",
  params={"owner": "Enreign", "repo": "pagerunner"}
)

Adapters automatically have access to auth tokens discovered in the session via the credentials argument.

Built-in adapters

Seed adapters for common services are built in:

  • GitHub
  • Linear
  • Jira
  • Notion
  • Gmail

These work out of the box once you have an authenticated session on the site.

Auto-generating adapters

Pagerunner can analyze network traffic from a session and auto-generate an adapter using Claude.

generate adapter
generate_adapter(origin="https://app.example.com")
→ analyzes network traffic, generates JS adapter code

Requires: ANTHROPIC_API_KEY environment variable. The adapter generation uses Claude to analyze network patterns and produce the JS code.

Selector tracking

Every time click, fill, or select runs, pagerunner records whether the selector succeeded or failed. Over time, it builds a reliability profile for each selector on each site.

When a selector's failure rate exceeds 30% over 5 or more uses, pagerunner includes a fragility warning in the tool response. This helps the agent (and you) know when selectors are becoming unreliable — usually a sign the site has updated its markup.

The compounding effect

This is the core differentiator. Every session teaches pagerunner something new about the sites you use. The first interaction with a site is the slowest. After that:

  • Auth tokens are cached — no re-authentication needed
  • Adapters bypass the DOM — faster, fewer tokens, more reliable
  • Selector health is tracked — fragile selectors get flagged before they break
  • API patterns are discovered — the agent can use APIs instead of scraping

Other tools reset after every session. Pagerunner remembers.

Next: KV Store →