Core Concepts

Sessions & Tabs

A session is a running Chrome instance tied to a profile. Within a session, you open tabs, navigate, interact with pages, and save state. Every pagerunner workflow starts with a session.

Session lifecycle

typical session
// 1. Open a session
open_session(profile="personal")
→ session_id: abc123
// 2. Open a tab
new_tab(session_id, url="https://github.com")
→ target_id: TAB456
// 3. Do work
get_content(session_id, target_id)
click(session_id, target_id, "#button")
type_text(session_id, target_id, "hello")
screenshot(session_id, target_id)
// 4. Close when done
close_session(session_id)

Session tools

Tool	Description
open_session	Launch Chrome for a profile. Returns `session_id`. Options: `stealth`, `anonymize`.
attach_session	Attach to an already-running Chrome instance via `--remote-debugging-port`.
close_session	Kill a Chrome session. Always close when done.
list_sessions	List all active sessions.

Tab tools

Tool	Description
list_tabs	List open tabs in a session.
new_tab	Open a new tab, optionally navigate to a URL. Returns `target_id`.
close_tab	Close a specific tab (fails if it's the last 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 and return 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.

Tip: Use fill instead of type_text for form inputs in React, Vue, and Angular apps. It triggers the right synthetic events so the framework's state updates correctly.

Snapshots

Save authenticated browser state (cookies + localStorage) for an origin and restore it in any future session.

snapshots
// Save login state
save_snapshot(session_id, target_id, origin="https://github.com")
// Restore in a future session
restore_snapshot(session_id, target_id, origin="https://github.com")

Snapshots are encrypted with AES-256-GCM and scoped to a profile. Use list_snapshots and delete_snapshot to manage them.

Session checkpoints

Checkpoints save the complete session state — all open tabs with their URLs and scroll positions.

checkpoints
// Save before a risky operation
save_session_checkpoint(session_id, name="before-deploy")
→ checkpoint_id: cp_abc123
// Restore if something goes wrong
restore_session_checkpoint(session_id, checkpoint_id="cp_abc123")
→ reopens all saved tabs at their stored URLs

Tab state

A lighter alternative to checkpoints — save just the open tab URLs and restore them later.

Tool	Description
save_tab_state	Save all open tab URLs to the database.
restore_tab_state	Reopen tabs from the most recently saved tab state.

Network & console

Tool	Description
get_network_log	Query HTTP requests captured during a session. Useful for debugging and adapter generation.
get_console_log	Query captured browser console messages and JS exceptions for a tab.

Next: Site Knowledge →