Actionbook

When to Use This Skill

Activate when the user:

• Needs to do anything on a website ("Send a LinkedIn message", "Book an Airbnb", "Search Google for...")
• Asks how to interact with a site ("How do I post a tweet?", "How to apply on LinkedIn?")
• Wants to fill out forms, click buttons, navigate, search, filter, or browse on a specific site
• Wants to take a screenshot of a web page or monitor changes
• Builds browser-based AI agents, web scrapers, or E2E tests for external websites
• Automates repetitive web tasks (data entry, form submission, content posting)
• Needs to operate multiple websites or tabs concurrently

How It Works

Actionbook provides up-to-date action manuals for the modern web. Action manuals tell agents exactly what to do on a page — no parsing, no guessing.

Why this matters:

• 10x faster — action manuals provide selectors and page structure upfront. No snapshot-per-step loop needed.
• Accurate — handles SPAs, streaming components, dropdowns, date pickers, and dynamic content reliably.
• Concurrent — stateless architecture with explicit --session/--tab. Operate dozens of tabs in parallel.

The workflow:

1. Start a browser session
2. Navigate to the target page
3. Snapshot to get the page structure with element refs
4. Automate using refs from the snapshot

Run actionbook <command> --help for full usage and examples of any command.

Browser Automation

Every browser command is stateless — pass --session and --tab explicitly. No "current tab" — you can run commands on any session/tab in parallel.

Start a session

actionbook browser start --set-session-id s1

Both --session and --set-session-id are get-or-create: they reuse a Running session with the given ID, or create one if not found. If --profile is passed and does not match the session's bound profile, the command fails with SESSION_PROFILE_MISMATCH.

Core workflow: snapshot, act, wait

actionbook browser goto <url> --session s1 --tab t1
actionbook browser snapshot --session s1 --tab t1          # Get page structure with refs
actionbook browser fill @e3 "text" --session s1 --tab t1   # Use refs from snapshot
actionbook browser click @e7 --session s1 --tab t1
actionbook browser wait navigation --session s1 --tab t1   # Wait for page load

Snapshot refs

snapshot labels every element with a ref (e.g. @e3, @e7). Use these refs as selectors in any command — they are the recommended way to target elements.

Refs are stable across snapshots — if the element stays the same, the ref stays the same. This lets you chain multiple commands without re-snapshotting after every step.

Command categories

All commands support --help for full usage and examples.

Full command reference: command-reference.md

Cloud providers

Use -p / --provider with browser start to run sessions on a remote browser instead of launching local Chrome. Supported providers: driver, hyperbrowser, browseruse. Each reads its own <PROVIDER>_API_KEY from the shell env.

export HYPERBROWSER_API_KEY="your-key"
actionbook browser start -p hyperbrowser --session s1
actionbook browser goto "https://example.com" --session s1 --tab t1
actionbook browser snapshot --session s1 --tab t1

All browser commands work the same way regardless of mode. browser restart --session <id> mints a fresh remote session while preserving the session_id.

Example: End-to-End

User request: "Find a room next week in SF on Airbnb"

actionbook browser start --set-session-id s1
actionbook browser goto "https://airbnb.com" --session s1 --tab t1
actionbook browser snapshot --session s1 --tab t1
actionbook browser fill @e3 "San Francisco" --session s1 --tab t1
actionbook browser click @e7 --session s1 --tab t1
actionbook browser wait navigation --session s1 --tab t1

Eval Input Sources

browser eval accepts the expression from three mutually-exclusive sources:

• Positional: actionbook browser eval "expr" ...
• --file: actionbook browser eval --file script.js ...
• Stdin: echo 'expr' | actionbook browser eval - ...

Eval Error Handling

browser eval returns structured error codes on failure — branch on error.code instead of parsing the message:

• EVAL_RUNTIME_ERROR — JS exception. Inspect the expression before retrying.
• EVAL_CROSS_ORIGIN — cross-origin fetch or CSP block. Proxy the request server-side.
• EVAL_RESPONSE_NOT_JSON / EVAL_RESPONSE_NOT_OK — read error.details.body_head (first ≤256 chars of the response body) to distinguish 403 / challenge pages / CORS errors. Do not blindly retry.
• EVAL_TIMEOUT — expression exceeded --timeout. Reduce work or raise the timeout.
• EVAL_ARGS_CONFLICT — multiple input sources or none. Provide exactly one.
• EVAL_FILE_NOT_FOUND — --file path unreadable. Verify the path.
• EVAL_STDIN_TTY — - but stdin is a terminal. Pipe the expression.
• EVAL_STDIN_EMPTY — stdin produced empty input. Verify the upstream pipeline.