Tools Reference — Pagerunner Docs

Session Management

list_profiles
list_profiles()
// List all configured profiles
 
No parameters.

open_session
open_session({
  profile: string,               // required
  stealth: bool,                // default: false
  allowed_domains: string[],     // optional
  max_navigations: number,       // optional
  sanitize_content: bool,        // default: false
  scan_injections: bool,         // default: false
  allowed_tools: string[],       // optional
  blocked_tools: string[],       // optional
  anonymize: bool,             // default: false
  anonymization_profile: string, // optional
  anonymization_entities: string[], // optional
  anonymization_mode: string,   // optional
})
 
// Open a new browser session with the specified profile
// Example: open_session({ profile: "work" })

attach_session
attach_session({
  debug_port: number,  // optional
  debug_url: string,  // optional
  profile: string,    // optional
})
 
// Attach to an already-running Chrome instance
// Example: attach_session({ debug_port: 9222 })

close_session
close_session({
  session_id: string  // required
})
 
// Close a session and its Chrome instance

list_sessions
list_sessions()
// List all active sessions

list_tabs
list_tabs({
  session_id: string  // required
})
 
// List tabs in a session

new_tab
new_tab({
  session_id: string,  // required
  url: string,        // optional
})
 
// Open a new tab
// Example: new_tab({ session_id: "s1", url: "https://example.com" })

close_tab
close_tab({
  session_id: string,  // required
  target_id: string,   // required
})
 
// Close a specific tab

Navigation & Interaction

navigate
navigate({
  session_id: string,  // required
  target_id: string,   // required
  url: string,        // required
})
 
// Navigate a tab to a URL

get_content
get_content({
  session_id: string,  // required
  target_id: string,   // required
})
 
// Get page content (text, links, forms)

screenshot
screenshot({
  session_id: string,  // required
  target_id: string,   // required
})
 
// Take a screenshot of the current page

evaluate
evaluate({
  session_id: string,        // required
  target_id: string,         // required
  expression: string,       // required
  store_as_secret: string,  // optional — save result as a named secret
})
 
// Execute JavaScript in the page
// Example: evaluate({ ..., expression: "document.title" })

click
click({
  session_id: string,  // required
  target_id: string,   // required
  selector: string,    // required
})
 
// Click an element
// Example: click({ ..., selector: "#submit-btn" })

type_text
type_text({
  session_id: string,  // required
  target_id: string,   // required
  text: string,        // required
  selector: string,    // optional — focus element first
})
 
// Type text (keyboard events)

fill
fill({
  session_id: string,  // required
  target_id: string,   // required
  selector: string,    // required
  value: string,       // required
})
 
// Fill a form field with a value
// Example: fill({ ..., selector: "#email", value: "user@example.com" })

select
select({
  session_id: string,  // required
  target_id: string,   // required
  selector: string,    // required
  value: string,       // required
})
 
// Select an option from a dropdown

scroll
scroll({
  session_id: string,  // required
  target_id: string,   // required
  x: number,          // optional
  y: number,          // optional
  selector: string,    // optional — scroll within element
})
 
// Scroll the page or an element

wait_for
wait_for({
  session_id: string,  // required
  target_id: string,   // required
  selector: string,    // optional — wait for element
  url: string,        // optional — wait for navigation
  ms: number,         // optional — wait N milliseconds
  timeout_ms: number,  // optional — max wait time
})
 
// Wait for a condition
// Example: wait_for({ ..., selector: ".loaded" })

State Management

save_snapshot
save_snapshot({
  session_id: string,  // required
  target_id: string,   // required
  origin: string,      // optional — defaults to current page origin
})
 
// Save cookies + localStorage for an origin

restore_snapshot
restore_snapshot({
  session_id: string,    // required
  target_id: string,     // required
  origin: string,        // required
  from_profile: string,  // optional — restore from a different profile
})
 
// Restore a saved snapshot

list_snapshots
list_snapshots({
  latest_only: bool,   // optional
  profile: string,     // optional
})
 
// List all saved snapshots

delete_snapshot
delete_snapshot({
  profile: string,    // required
  origin: string,     // required
  saved_at: string,   // optional — delete specific version
})
 
// Delete a snapshot

save_tab_state / restore_tab_state
save_tab_state({
  session_id: string  // required
})
 
restore_tab_state({
  session_id: string  // required
})
 
// Save / restore all tab URLs and order

save_session_checkpoint
save_session_checkpoint({
  session_id: string,  // required
  name: string,        // optional
})
 
// Save full session state (cookies, localStorage, tabs)

restore_session_checkpoint
restore_session_checkpoint({
  session_id: string,     // required
  checkpoint_id: string,  // required
})
 
// Restore from a checkpoint

list_session_checkpoints / delete_session_checkpoint
list_session_checkpoints({
  profile: string  // required
})
 
delete_session_checkpoint({
  profile: string,        // required
  checkpoint_id: string,  // required
})

KV Store

kv_set
kv_set({
  namespace: string,  // required
  key: string,        // required
  value: string,      // required
})
 
// Store a value
// Example: kv_set({ namespace: "brief", key: "revenue", value: "$1.2M" })

kv_get
kv_get({
  namespace: string,  // required
  key: string,        // required
})
 
// Retrieve a value

kv_delete
kv_delete({
  namespace: string,  // required
  key: string,        // required
})
 
// Delete a key

kv_list
kv_list({
  namespace: string,        // required
  prefix: string,           // optional
  include_values: bool,     // default: false
})
 
// List keys in a namespace

kv_clear
kv_clear({
  namespace: string  // required
})
 
// Clear all keys in a namespace

Secrets

extract_secret
extract_secret({
  session_id: string,  // required
  target_id: string,   // required
  expression: string,  // required — JS expression
  name: string,        // required — secret name
})
 
// Extract a value from a page and store as secret

use_secret
use_secret({
  name: string,      // required — secret name
  command: string[],  // required — CLI command args
})
 
// Inject a secret into a CLI command via stdin
// Example: use_secret({ name: "api-key", command: ["curl", "-H", "Authorization: Bearer $SECRET"] })

list_secrets / delete_secret
list_secrets()
// List secret names (values never shown)
 
delete_secret({
  name: string  // required
})

Network & Console

get_network_log
get_network_log({
  session_id: string,         // required
  target_id: string,          // optional
  url_pattern: string,        // optional
  method: string,             // optional — GET, POST, etc.
  status_min: number,         // optional
  status_max: number,         // optional
  lookback_ms: number,        // optional
  limit: number,              // optional
  include_request_body: bool,  // default: false
  full_response: bool,        // default: false
  all_tabs: bool,             // default: false
})
 
// Query captured network requests
// Example: get_network_log({ ..., url_pattern: "/api/", method: "POST" })

get_console_log
get_console_log({
  session_id: string,  // required
  target_id: string,   // required
  limit: number,       // optional
})
 
// Get browser console messages

Site Knowledge

get_site_knowledge
get_site_knowledge({
  origin: string  // required — e.g. "https://github.com"
})
 
// Get learned knowledge about a site

register_adapter
register_adapter({
  origin: string,          // required
  name: string,            // required — adapter name
  description: string,     // required
  js_code: string,         // required — JavaScript to execute
  params_schema: object,    // optional — JSON Schema for params
})
 
// Register a site adapter (reusable JS function for a site)

call_site_api
call_site_api({
  session_id: string,  // required
  target_id: string,   // required
  origin: string,      // required
  name: string,        // required — adapter name
  params: object,      // optional
})
 
// Call a registered adapter

generate_adapter
generate_adapter({
  origin: string,      // required
  name: string,        // required
  description: string,  // optional
})
 
// Auto-generate an adapter (requires ANTHROPIC_API_KEY)

Recordings

start_recording
start_recording({
  session_id: string,  // required
  target_id: string,   // required
  name: string,        // optional
  tags: string[],      // optional
  flow: string,        // optional
})
 
// Start recording a session

stop_recording
stop_recording({
  session_id: string  // required
})
 
// Stop recording

add_marker
add_marker({
  session_id: string,    // required
  label: string,         // required
  description: string,   // optional
})
 
// Add a timestamped marker to the recording

list_recordings
list_recordings({
  profile: string,  // optional
  flow: string,     // optional
  tag: string,      // optional
})
 
// List recordings

get_recording / delete_recording
get_recording({
  recording_id: string  // required
})
 
delete_recording({
  recording_id: string  // required
})

render_recording
render_recording({
  recording_id: string,  // required
  format: string,        // optional — "mp4", "gif", "webm"
  with_overlays: bool,    // default: false
  position: string,       // optional
  font: string,           // optional
  font_size: number,      // optional
  text_color: string,     // optional
  bg_color: string,       // optional
  bar_height: number,     // optional
})
 
// Render recording to video
// Example: render_recording({ recording_id: "r1", format: "mp4", with_overlays: true })

Notifications

notify
notify({
  title: string,       // required
  body: string,        // optional
  level: string,       // optional — "info", "warning", "error"
  session_id: string,  // optional
})
 
// Send a macOS notification
// Example: notify({ title: "Done", body: "Report ready", level: "info" })

Autonomous Agent

agent_run
agent_run({
  goal: string,       // required — what the agent should accomplish
  profile: string,    // optional
  model: string,      // optional
  max_steps: number,  // optional
})
 
// Run an autonomous browsing agent
// Example: agent_run({ goal: "Find the pricing for Acme Corp", profile: "research" })

Next: Examples →