Browser automation MCP server with progressive disclosure design -- uses 3.2x fewer tokens than Playwright MCP across 6 tasks. Single execute_code tool runs Python with async browser functions, persisted login sessions, CLI daemon workflows, and compact description mode for token optimization.

version
0.1.56
GitHub stars
279

Install

/plugin install openbrowser@openbrowser-ai

Run it inside Claude Code after adding the marketplace with /plugin marketplace add billy-enrizky/openbrowser-ai.

Contents

Discovered from source

Skills 7

Accessibility Audit

Audit web pages for accessibility issues following WCAG 2.1 guidelines using Python code execution. Checks heading structure, form labels, image alt text, ARIA attributes, landmark regions, and keyboard navigation.

All code runs via openbrowser-ai -c. The daemon starts automatically and persists variables across calls. All browser functions are async -- use await.

The CLI daemon also persists cookies and login state in ~/.config/openbrowser/profiles/daemon/storage_state.json, so authenticated sessions can be reused across later runs.

Setup

Before running, verify openbrowser-ai is installed:

openbrowser-ai --help

If not found, install:

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.ps1 | iex

Workflow

Step 1 -- Navigate and initialize audit

openbrowser-ai -c - <<'EOF'
await navigate("https://example.com")
state = await browser.get_browser_state_summary()
print(f"Auditing: {state.title} ({state.url})")

# Store all findings
audit = {
    "url": state.url,
    "title": state.title,
    "issues": [],
    "checks": {}
}
EOF

Step 2 -- Check heading structure

openbrowser-ai -c - <<'EOF'
headings_result = await evaluate("""
(function(){
  const headings = Array.from(document.querySelectorAll("h1,h2,h3,h4,h5,h6"));
  const issues = [];
  let prevLevel = 0;
  const h1Count = headings.filter(h => h.tagName === "H1").length;

  if (h1Count === 0) issues.push("No h1 element found");
  if (h1Count > 1) issues.push("Multiple h1 elements: " + h1Count);

  headings.forEach(h => {
    const level = parseInt(h.tagName[1]);
    if (prevLevel > 0 && level > prevLevel + 1)
      issues.push("Skipped level: h" + prevLevel + " -> h" + level + " (\"" + h.textContent.trim().substring(0, 50) + "\")");
    if (!h.textContent.trim())
      issues.push("Empty heading: " + h.tagName);
    prevLevel = level;
  });

  return {
    total: headings.length,
    h1Count,
    hierarchy: headings.map(h => ({ tag: h.tagName, text: h.textContent.trim().substring(0, 80) })),
    issues
  };
})()
""")

audit["checks"]["headings"] = headings_result
for issue in headings_result.get("issues", []):
    audit["issues"].append({"check": "headings", "wcag": "1.3.1", "issue": issue})
    print(f"[HEADINGS] {issue}")

if not headings_result.get("issues"):
    print("[HEADINGS] PASS")
EOF

Step 3 -- Check images for alt text

openbrowser-ai -c - <<'EOF'
images_result = await evaluate("""
(function(){
  const images = Array.from(document.querySelectorAll("img"));
  const issues = [];
  let withAlt = 0, withEmptyAlt = 0, missingAlt = 0;

  images.forEach(img => {
    const alt = img.getAttribute("alt");
    const src = img.src?.substring(0, 100);
    if (alt === null) {
      missingAlt++;
      issues.push("Missing alt: " + src);
    } else if (alt === "") {
      withEmptyAlt++;
    } else {
      withAlt++;
    }
  });

  return { total: images.length, withAlt, withEmptyAlt, missingAlt, issues };
})()
""")

audit["checks"]["images"] = images_result
for issue in images_result.get("issues", []):
    audit["issues"].append({"check": "images", "wcag": "1.1.1", "issue": issue})
    print(f"[IMAGES] {issue}")

if not images_result.get("issues"):
    total = images_result["total"]
    with_alt = images_result["withAlt"]
    print(f"[IMAGES] PASS ({total} images, {with_alt} with alt)")
EOF

Step 4 -- Check form labels

openbrowser-ai -c - <<'EOF'
forms_result = await evaluate("""
(function(){
  const inputs = Array.from(document.querySelectorAll("input:not([type=\"hidden\"]),select,textarea"));
  const issues = [];

  inputs.forEach(input => {
    const id = input.id;
    const ariaLabel = input.getAttribute("aria-label");
    const ariaLabelledBy = input.getAttribute("aria-labelledby");
    const title = input.getAttribute("title");
    const label = id ? document.querySelector("label[for=\"" + id + "\"]") : null;
    const parentLabel = input.closest("label");
    const hasLabel = label || parentLabel || ariaLabel || ariaLabelledBy || title;

    if (!hasLabel) {
      issues.push({
        tag: input.tagName,
        type: input.type || "text",
        name: input.name || "(none)",
        placeholder: input.getAttribute("placeholder") || "(none)",
        issue: "No label or aria-label"
      });
    }
  });

  return { totalInputs: inputs.length, unlabeled: issues.length, issues };
})()
""")

audit["checks"]["forms"] = forms_result
for issue in forms_result.get("issues", []):
    tag = issue["tag"]
    name = issue["name"]
    itype = issue["type"]
    audit["issues"].append({"check": "forms", "wcag": "1.3.1", "issue": f"Unlabeled {tag} name={name}"})
    print(f"[FORMS] Unlabeled: <{tag}> type={itype} name={name}")

if not forms_result.get("issues"):
    total_inputs = forms_result["totalInputs"]
    print(f"[FORMS] PASS ({total_inputs} inputs, all labeled)")
EOF

Step 5 -- Check ARIA attributes

openbrowser-ai -c - <<'EOF'
aria_result = await evaluate("""
(function(){
  const issues = [];
  const ariaElements = document.querySelectorAll("[role],[aria-label],[aria-labelledby],[aria-describedby],[aria-hidden]");

  ariaElements.forEach(el => {
    const ariaLabelledBy = el.getAttribute("aria-labelledby");
    const ariaDescribedBy = el.getAttribute("aria-describedby");

    if (ariaLabelledBy) {
      ariaLabelledBy.split(/\s+/).forEach(id => {
        if (!document.getElementById(id))
          issues.push({ element: el.tagName, issue: "aria-labelledby references missing id: " + id });
      });
    }
    if (ariaDescribedBy) {
      ariaDescribedBy.split(/\s+/).forEach(id => {
        if (!document.getElementById(id))
          issues.push({ element: el.tagName, issue: "aria-describedby references missing id: " + id });
      });
    }
    if (el.getAttribute("role") === "button" && !el.getAttribute("aria-label") && !el.textContent.trim())
      issues.push({ element: el.tagName, issue: "Button role with no accessible name" });
    if (el.getAttribute("aria-hidden") === "true" && el.querySelector("a,button,input,select,textarea,[tabindex]"))
      issues.push({ element: el.tagName, issue: "aria-hidden on element with focusable children" });
  });

  return { totalAriaElements: ariaElements.length, issues };
})()
""")

audit["checks"]["aria"] = aria_result
for issue in aria_result.get("issues", []):
    msg = issue["issue"]
    audit["issues"].append({"check": "aria", "wcag": "4.1.2", "issue": msg})
    print(f"[ARIA] {msg}")

if not aria_result.get("issues"):
    total_aria = aria_result["totalAriaElements"]
    print(f"[ARIA] PASS ({total_aria} ARIA elements)")
EOF

Step 6 -- Check landmark regions

openbrowser-ai -c - <<'EOF'
landmarks_result = await evaluate("""
(function(){
  const landmarks = {
    banner: document.querySelectorAll("header,[role=\"banner\"]").length,
    navigation: document.querySelectorAll("nav,[role=\"navigation\"]").length,
    main: document.querySelectorAll("main,[role=\"main\"]").length,
    contentinfo: document.querySelectorAll("footer,[role=\"contentinfo\"]").length,
    complementary: document.querySelectorAll("aside,[role=\"complementary\"]").length,
    search: document.querySelectorAll("[role=\"search\"]").length
  };
  const issues = [];
  if (landmarks.main === 0) issues.push("No main landmark");
  if (landmarks.main > 1) issues.push("Multiple main landmarks: " + landmarks.main);
  if (landmarks.banner === 0) issues.push("No banner/header landmark");
  if (landmarks.navigation === 0) issues.push("No navigation landmark");
  if (landmarks.contentinfo === 0) issues.push("No footer/contentinfo landmark");
  return { landmarks, issues };
})()
""")

audit["checks"]["landmarks"] = landmarks_result
for issue in landmarks_result.get("issues", []):
    audit["issues"].append({"check": "landmarks", "wcag": "1.3.1", "issue": issue})
    print(f"[LANDMARKS] {issue}")

if not landmarks_result.get("issues"):
    print("[LANDMARKS] PASS")
EOF

Step 7 -- Check links and buttons

openbrowser-ai -c - <<'EOF'
links_result = await evaluate("""
(function(){
  const issues = [];
  document.querySelectorAll("a").forEach(a => {
    const name = a.textContent.trim() || a.getAttribute("aria-label") || a.getAttribute("title") || a.querySelector("img[alt]")?.alt;
    if (!name) issues.push({ tag: "a", href: a.href?.substring(0, 80), issue: "No accessible name" });
    else if (["click here", "here", "read more", "more", "link"].includes(name.toLowerCase()))
      issues.push({ tag: "a", text: name, issue: "Non-descriptive link text" });
  });
  document.querySelectorAll("button,[role=\"button\"]").forEach(btn => {
    const name = btn.textContent.trim() || btn.getAttribute("aria-label") || btn.getAttribute("title");
    if (!name) issues.push({ tag: btn.tagName, issue: "Button with no accessible name" });
  });
  return { issues };
})()
""")

audit["checks"]["links_buttons"] = links_result
for issue in links_result.get("issues", []):
    msg = issue["issue"]
    audit["issues"].append({"check": "links_buttons", "wcag": "2.4.4", "issue": msg})
    print(f"[LINKS/BUTTONS] {msg}")

if not links_result.get("issues"):
    print("[LINKS/BUTTONS] PASS")
EOF

Step 8 -- Check keyboard navigation

openbrowser-ai -c - <<'EOF'
keyboard_result = await evaluate("""
(function(){
  const focusable = Array.from(document.querySelectorAll("a[href],button,input:not([type=\"hidden\"]),select,textarea,[tabindex]"));
  const issues = [];
  const positiveTabindex = focusable.filter(el => parseInt(el.getAttribute("tabindex")) > 0);
  const negativeTabindex = focusable.filter(el => {
    const ti = parseInt(el.getAttribute("tabindex"));
    return ti < 0 && ["A","BUTTON","INPUT","SELECT","TEXTAREA"].includes(el.tagName);
  });

  if (positiveTabindex.length > 0)
    issues.push("Elements with positive tabindex (disrupts tab order): " + positiveTabindex.length);
  if (negativeTabindex.length > 0)
    issues.push("Interactive elements removed from tab order: " + negativeTabindex.length);

  return { totalFocusable: focusable.length, positiveTabindex: positiveTabindex.length, negativeTabindex: negativeTabindex.length, issues };
})()
""")

audit["checks"]["keyboard"] = keyboard_result
for issue in keyboard_result.get("issues", []):
    audit["issues"].append({"check": "keyboard", "wcag": "2.4.3", "issue": issue})
    print(f"[KEYBOARD] {issue}")

if not keyboard_result.get("issues"):
    total_focusable = keyboard_result["totalFocusable"]
    print(f"[KEYBOARD] PASS ({total_focusable} focusable elements)")
EOF

Step 9 -- Compile audit report

openbrowser-ai -c - <<'EOF'
import json

total_issues = len(audit["issues"])
checks_passed = sum(1 for c in audit["checks"].values() if not c.get("issues"))
checks_total = len(audit["checks"])

url = audit["url"]
title = audit["title"]
print(f"\n=== Accessibility Audit Report ===")
print(f"URL: {url}")
print(f"Title: {title}")
print(f"Checks: {checks_passed}/{checks_total} passed")
print(f"Total issues: {total_issues}")

if total_issues > 0:
    print(f"\nIssues by WCAG criterion:")
    by_wcag = {}
    for issue in audit["issues"]:
        by_wcag.setdefault(issue["wcag"], []).append(issue)
    for wcag, issues in sorted(by_wcag.items()):
        print(f"  {wcag}: {len(issues)} issues")
        for i in issues[:3]:
            msg = i["issue"]
            print(f"    - {msg}")
        if len(issues) > 3:
            print(f"    ... and {len(issues) - 3} more")
EOF

WCAG Quick Reference

CheckWCAG CriterionLevel
Images have alt text1.1.1 Non-text ContentA
Heading hierarchy is logical1.3.1 Info and RelationshipsA
Form inputs have labels1.3.1 Info and RelationshipsA
Link purpose is clear2.4.4 Link Purpose (In Context)A
Landmark regions present1.3.1 Info and RelationshipsA
Focus order is logical2.4.3 Focus OrderA
ARIA attributes valid4.1.2 Name, Role, ValueA

Tips

  • Code is piped via stdin using heredoc (-c - <<'EOF'), so all Python syntax works without shell escaping issues.
  • Store results in the audit dict -- variables persist between -c calls while the daemon is running.
  • Run audits on multiple pages, not just the homepage.
  • ARIA misuse is often worse than no ARIA at all.
  • The heading check catches the most common structural issues.
  • Missing form labels are the most common form accessibility failure.

Cleanup

This step is mandatory. Run it after the task finishes, whether the audit succeeded or failed. Without it, the daemon keeps Chrome running until its 10-minute idle timeout, leaving a stale browser process, a locked profile, and (on macOS/Linux desktop) a visible window.

Stop the daemon, then verify it is gone:

openbrowser-ai daemon stop
openbrowser-ai daemon status

daemon stop closes every tab, exits Chrome, flushes saved cookies/login state to the profile, and shuts down the daemon process. daemon status should report the daemon is not running. If it still reports running, run openbrowser-ai daemon doctor and then openbrowser-ai daemon reap. reap stops only verified OpenBrowser daemons and removes stale sockets and PID files.

If your skill invocation can fail mid-workflow (network error, assertion failure, CDP timeout), guarantee cleanup with a shell trap so the browser is never left orphaned:

trap 'openbrowser-ai daemon stop >/dev/null 2>&1 || true' EXIT
# ... openbrowser-ai -c calls here ...

Do not rely on the idle timeout. Do not call done() as a substitute, done() only marks the task complete inside the agent loop, it does not close the browser.

Deep Research

Drive openbrowser-ai to investigate a topic across multiple web sources and produce a cited markdown report plus structured JSON. Two modes:

  • flat synthesis (default) -- decompose query into 3-7 sub-questions, dispatch one parallel sub-agent per sub-question (each owns one tab), merge into one cited report.
  • drilldown (auto-detected from prompt phrasing: "deep dive", "exhaustive", "recursive", "drilldown", "thorough") -- same as flat, plus a second wave of parallel sub-agents on findings flagged needs_depth=true. Hard cap depth=2, max 3 follow-up sub-agents per parent.

Output paths (relative to current project root):

  • local_docs/research/YYYY-MM-DD-<slug>.md
  • local_docs/research/YYYY-MM-DD-<slug>.json

Architecture (mandatory): the orchestrating Claude session (the one running this skill) MUST dispatch parallel sub-agents via /dispatching-parallel-agents, one sub-agent per sub-question. Each sub-agent owns exactly ONE tab. Sub-agents do not open additional tabs. The orchestrator merges per-agent findings into one report.

Why one tab per sub-agent and not asyncio.gather over tabs in a single -c call: a single Python coroutine driving N tabs through one daemon serializes navigation events at the CDP layer, contends for the LLM-extraction worker, and cannot make independent decisions about pagination or follow-up clicks per tab. Dispatching real Claude sub-agents (each with its own context window and its own browser tab) gives true parallelism, independent reasoning per tab, and isolates failures so one bad page doesn't poison the rest.

Hard rules:

  • One sub-agent = one tab. Sub-agents must NOT call navigate(url, new_tab=True) to spawn additional tabs.
  • All sub-agents share the same daemon (and so the same Chrome process). Tabs are isolated; navigation in one tab does not affect another.
  • Each sub-agent writes its findings to its own JSON file under $DEEP_RESEARCH_PARTIAL_DIR/<slug>-NN.json. The orchestrator reads and merges these.
  • The orchestrator never drives tabs itself. It only plans, dispatches, merges, renders, verifies, cleans up.

If a first-wave sub-agent returns <2 findings, the orchestrator dispatches a Step 2b retry sub-agent with broader search strategy (alternative engines, query reformulation, lower thresholds). Still -c-only: the skill never calls openbrowser-ai -p.

Variables persist across -c calls in the daemon namespace.

Session reuse: Step 0 creates a dedicated socket and profile for this research run. If that exact daemon is already running from an earlier step, the skill reuses it and operates in NEW tabs. It never attaches to or restarts the user's default daemon. If no daemon exists for this socket, the skill auto-starts one on the first -c call.

Every factual claim in the report carries a footnote citation [N]. Verifier fails the run if uncited prose is found.

Setup

Verify install:

openbrowser-ai --help

Install if missing:

# macOS / Linux
curl -fsSL https://openbrowser.me/install.sh | sh

# Windows PowerShell
irm https://openbrowser.me/install.ps1 | iex

No LLM API key required. The skill drives the daemon via openbrowser-ai -c only, which executes raw CDP / JS through the daemon's Python namespace and never invokes a model. (The -p "prompt mode" of the CLI is a separate code path that loads get_llm() and requires an OpenAI / Anthropic / Google key per cli.py:434-490. This skill explicitly avoids -p.)

Set the headless env var so the daemon starts without a visible browser window (the default in daemon/server.py is already headless: True, but a user config file can override it; this env var wins over config):

export OPENBROWSER_HEADLESS=true

Prepare output dir at the project root (NOT user home):

mkdir -p local_docs/research

Workflow

Step 0 -- Session check

Use a dedicated socket and profile for the research run so the user's existing daemon, tabs, and namespace are never restarted or touched. If this research run already started its own daemon, reuse it. Otherwise the next -c call auto-starts one.

Each shell block starts a new process, so bare export values do not carry across blocks. Step 0 creates a per-invocation run directory, writes a shell-escaped environment file, and prints its absolute path as RUN_ENV_FILE=....

Every later shell block must begin by sourcing that exact path:

. "<RUN_ENV_FILE>"

Copy the printed path from Step 0. Do not substitute the project path or reuse another run's file.

RESEARCH_ROOT="$(pwd)"
RUN_STAMP="$(date +%Y%m%d-%H%M%S)-$$"
RUN_DIR="$RESEARCH_ROOT/local_docs/research/.runs/$RUN_STAMP"
ENV_FILE="$RUN_DIR/env.sh"
mkdir -p "$RUN_DIR/partial" || { echo "Cannot create $RUN_DIR"; exit 1; }
{
    printf 'export OPENBROWSER_HEADLESS=true\n'
    printf 'export OPENBROWSER_SOCKET=%q\n' "${TMPDIR:-/tmp}/openbrowser-deep-research-${RUN_STAMP}.sock"
    printf 'export OPENBROWSER_DAEMON_PROFILE_DIR=%q\n' "${TMPDIR:-/tmp}/openbrowser-deep-research-profile-${RUN_STAMP}"
    printf 'export OPENBROWSER_DAEMON_PROFILE_ISOLATION=true\n'
    printf 'export OPENBROWSER_USER_DATA_DIR=\n'
    printf 'export DEEP_RESEARCH_RUN_DIR=%q\n' "$RUN_DIR"
    printf 'export DEEP_RESEARCH_PARTIAL_DIR=%q\n' "$RUN_DIR/partial"
    printf 'export DEEP_RESEARCH_PROJECT_ROOT=%q\n' "$RESEARCH_ROOT"
    printf 'export DEEP_RESEARCH_ENV_FILE=%q\n' "$ENV_FILE"
} > "$ENV_FILE" || { echo "Cannot write $ENV_FILE"; exit 1; }
[ -s "$ENV_FILE" ] || { echo "Empty run environment: $ENV_FILE"; exit 1; }
. "$ENV_FILE" || { echo "Cannot source $ENV_FILE"; exit 1; }
: "${OPENBROWSER_SOCKET:?dedicated socket was not loaded}"
case "$OPENBROWSER_SOCKET" in
    *openbrowser-deep-research-*) ;;
    *) echo "Refusing to continue without a dedicated research socket"; exit 1 ;;
esac

ensure_output=$(openbrowser-ai daemon ensure 2>&1) || { echo "$ensure_output"; exit 1; }
if printf '%s' "$ensure_output" | grep -q 'already matches'; then
    echo "Reusing this research run's daemon"
    DEEP_RESEARCH_REUSED=1
    DEEP_RESEARCH_OWNED=0
else
    echo "Started this research run's isolated daemon"
    DEEP_RESEARCH_REUSED=0
    DEEP_RESEARCH_OWNED=1
fi
printf 'export DEEP_RESEARCH_REUSED=%s\nexport DEEP_RESEARCH_OWNED=%s\n' \
    "$DEEP_RESEARCH_REUSED" "$DEEP_RESEARCH_OWNED" >> "$ENV_FILE"
export DEEP_RESEARCH_REUSED DEEP_RESEARCH_OWNED
echo "RUN_ENV_FILE=$ENV_FILE"

OPENBROWSER_USER_DATA_DIR= clears an inherited explicit profile so it cannot override the dedicated research profile. daemon ensure reuses a daemon only when its effective headless and profile settings match; otherwise it restarts this run's daemon.

Snapshot existing tabs so cleanup leaves them untouched:

openbrowser-ai -c - <<'EOF'
state = await browser.get_browser_state_summary()
_preexisting_tab_ids = {t.target_id for t in state.tabs} if state.tabs else set()
print(f"Pre-existing tabs: {len(_preexisting_tab_ids)}")
EOF

Step 1 -- Plan

Decompose the user query into sub-questions and pick the mode. Daemon namespace persists _plan across later -c calls.

openbrowser-ai -c - <<'EOF'
import json, re, datetime, os

QUERY = """<USER_QUERY>"""  # paste exact user query here

# Daemon CWD often != shell CWD. Hard-code the absolute project root.
# Set this to the shell CWD at the start of the run; do NOT rely on os.getcwd().
PROJECT_ROOT = "<ABSOLUTE_PATH_TO_PROJECT_ROOT>"  # e.g. /Users/foo/myproject

# Auto-detect mode
DRILL_RE = re.compile(r"\b(deep ?dive|exhaustive|recursive|drill ?down|thorough)\b", re.I)
mode = "drilldown" if DRILL_RE.search(QUERY) else "flat"

# Slug = first 60 chars, lowercase, non-alnum -> '-', collapse repeats
def slugify(s):
    s = re.sub(r"[^a-z0-9]+", "-", s.lower())[:60]
    return s.strip("-") or "research"

today = datetime.date.today().isoformat()
slug = slugify(QUERY)
research_dir = os.path.join(PROJECT_ROOT, "local_docs", "research")
os.makedirs(research_dir, exist_ok=True)
base = os.path.join(research_dir, f"{today}-{slug}")
md_path, json_path = f"{base}.md", f"{base}.json"

# Bump suffix if collision
n = 2
while os.path.exists(md_path):
    md_path, json_path = f"{base}-{n}.md", f"{base}-{n}.json"
    n += 1

# Decompose: 3-7 sub-questions. Keep tight, non-overlapping, each answerable from web.
# This is a heuristic split; replace with your own decomposition for the actual query.
sub_questions = [
    # e.g.  "What is X?",
    #       "Who are the main actors / vendors / authors?",
    #       "What are recent (last 12 months) developments?",
    #       "What are the trade-offs / criticisms?",
    #       "What concrete numbers / benchmarks exist?",
]

assert 3 <= len(sub_questions) <= 7, "need 3-7 sub-questions"

_plan = {
    "query": QUERY,
    "mode": mode,
    "generated_at": datetime.datetime.now().astimezone().isoformat(),
    "sub_questions": sub_questions,
    "md_path": md_path,
    "json_path": json_path,
}
print(json.dumps(_plan, indent=2))
EOF

Edit the QUERY, PROJECT_ROOT, and sub_questions list before running. PROJECT_ROOT MUST be an absolute path: the daemon runs in its own working directory (usually wherever the daemon was first started), so relative paths land in the wrong place. Use the shell pwd output as the value. Verify output looks right before continuing.

Step 2a -- Dispatch parallel sub-agents (one tab per agent)

The orchestrator (the Claude session running this skill) MUST invoke /dispatching-parallel-agents and dispatch one sub-agent per sub-question. All sub-agents share the same openbrowser-ai daemon. Each sub-agent owns exactly one tab, the one it opens at the start of its run.

Give every sub-agent the exact absolute RUN_ENV_FILE path printed by Step 0 and require it to source that file before any openbrowser-ai command. Without those values a sub-agent would talk to the user's default daemon.

Hard rules for the orchestrator:

  • Send ONE message containing N parallel Agent tool calls, where N = len(_plan["sub_questions"]).
  • Each sub-agent gets the prompt template below, parameterized with: SUB_QUESTION, AGENT_INDEX (zero-padded 2 digits, used in output filename), PROJECT_ROOT (absolute path).
  • After dispatch, wait for all sub-agents to return. Do not begin Step 4 until every partial JSON file under $DEEP_RESEARCH_PARTIAL_DIR/ is on disk.
  • The orchestrator does NOT drive any tab in this step.

Sub-agent prompt template (copy into each Agent tool call's prompt argument):

You are a deep-research sub-agent. Your job: investigate ONE sub-question
in ONE Chrome tab and write findings to a JSON file.

Sub-question: <SUB_QUESTION>
Agent index: <AGENT_INDEX>
Project root: <PROJECT_ROOT>

Hard constraints:

- You own ONE tab. The tab is the one you open at the start of this task.
- NEVER pass new_tab=True to navigate(). Reuse your one tab for every page.
- Do not switch to other tabs.
- Do not call openbrowser-ai daemon stop. The orchestrator owns daemon lifecycle.
- Visit at least 3 result URLs from at least 3 different domains.
- For each URL, extract one finding with: claim (one sentence), exact url,
  supporting quote (verbatim, max 40 words), domain, confidence (low|medium|high),
  needs_depth (bool, true if a deeper follow-up would meaningfully sharpen the claim).
- Return at least 2 findings; 3 is ideal.
- Write the findings JSON array to:
  <DEEP_RESEARCH_PARTIAL_DIR>/agent-<AGENT_INDEX>.json

Workflow (run via openbrowser-ai -c - heredocs, all in this one bash session):

1. Open exactly one tab on Google search:
   openbrowser-ai -c - <<'EOF'
   await navigate("https://www.google.com/search?q=<URL_ENCODED_SUB_QUESTION>", new_tab=True)
   await wait(2)
   state = await browser.get_browser_state_summary()
   tab_id = state.tabs[-1].target_id
   _MY_TAB = tab_id[-4:]
   print(f"my tab: {_MY_TAB}")
   EOF

2. Scrape the SERP for top 5 result URLs.

3. For each of the top 3 results, navigate IN THE SAME TAB (no new_tab=True),
   wait 2s, capture body innerText, pick the sentence with the most word-overlap
   vs the sub-question (40-280 chars, >3-letter keyword overlap >= 1).

4. Write the findings JSON array to the partial file.

5. Print a one-line summary: "agent <AGENT_INDEX>: <N> findings written".

Return: a one-line confirmation that the partial JSON file was written, and
its absolute path. Do not include the findings in your text reply -- the
orchestrator will read them from disk.

The orchestrator's pre-step (run once before dispatching agents):

openbrowser-ai -c - <<'EOF'
import os
partial_dir = os.environ["DEEP_RESEARCH_PARTIAL_DIR"]
os.makedirs(partial_dir, exist_ok=True)
# Wipe stale partials from prior runs of the same query
for f in os.listdir(partial_dir):
    if f.startswith("agent-") and f.endswith(".json"):
        os.remove(os.path.join(partial_dir, f))
print(f"partial dir ready: {partial_dir}")
EOF

After all sub-agents return, the orchestrator collects findings:

openbrowser-ai -c - <<'EOF'
import os, json
global _findings
partial_dir = os.environ["DEEP_RESEARCH_PARTIAL_DIR"]

_findings = []
for fname in sorted(os.listdir(partial_dir)):
    if not (fname.startswith("agent-") and fname.endswith(".json")):
        continue
    path = os.path.join(partial_dir, fname)
    try:
        with open(path) as fh:
            arr = json.load(fh)
        if isinstance(arr, list):
            # normalize exact_url -> url (sub-agents may use either key)
            for item in arr:
                if "exact_url" in item and "url" not in item:
                    item["url"] = item.pop("exact_url")
            _findings.extend(arr)
    except Exception as e:
        print(f"skip {path}: {e}")

print(f"merged {len(_findings)} findings from {len(os.listdir(partial_dir))} partials")
EOF

If any sub-question's partial file is missing or has <2 findings, fall through to Step 2b for that one.

Step 2b -- Retry weak sub-questions with broader sub-agents

If a sub-question came back with <2 findings, do NOT use openbrowser-ai -p. The -p mode requires an LLM API key (OpenAI / Anthropic / Google) because it runs the full Browser Agent loop with LLM-driven navigation, see cli.py:434-490 get_llm(). This skill is -c-only by design: the daemon executes raw CDP / JS and needs no API key.

Identify weak sub-questions, then dispatch a fresh round of parallel sub-agents (same /dispatching-parallel-agents pattern as Step 2a) with a broader prompt. The retry sub-agents reuse the same single-tab discipline and write to agent-retry-NN.json partials.

openbrowser-ai -c - <<'EOF'
from collections import Counter
global _retry_subqs
counts = Counter(f.get("sub_question") for f in _findings)
_retry_subqs = [sq for sq in _plan["sub_questions"] if counts.get(sq, 0) < 2]
print(f"Retry targets: {len(_retry_subqs)}")
for sq in _retry_subqs:
    print(f"  - {sq}")
EOF

The orchestrator then dispatches one parallel sub-agent per weak sub-question with this retry prompt template (same single-tab rule, broader search strategy):

You are a deep-research RETRY sub-agent. Your job: investigate ONE sub-question
that the first-wave sub-agent could not satisfy. Use ONE Chrome tab and write
findings to a JSON file.

Sub-question: <SUB_QUESTION>
Agent index: <AGENT_INDEX> (filename agent-retry-<AGENT_INDEX>.json)
Project root: <PROJECT_ROOT>

Hard constraints:

- You own ONE tab. NEVER pass new_tab=True to navigate() after the first call.
- Use openbrowser-ai -c only. NEVER use openbrowser-ai -p (it requires an LLM
  API key and we explicitly avoid that path).
- The first-wave attempt failed: heuristic sentence picker returned <2 findings.
  This means the page text either had no high-overlap sentences for the question,
  or the SERP returned thin sources. Try one or more of:
  1. Reformulate the search query (try 2-3 alternative phrasings, pick the one
     with the best SERP).
  2. Search a different engine: try Bing or DuckDuckGo if Google was thin.
     URLs: https://www.bing.com/search?q=... or https://duckduckgo.com/?q=...
  3. Lower the sentence-length floor for the heuristic (e.g. 30 chars instead
     of 40), or accept partial-match sentences with overlap >= 1 word.
  4. For factual sub-questions ("when was X released"), check Wikipedia
     directly: https://en.wikipedia.org/wiki/Special:Search?search=...
- Same JSON shape as Step 2a sub-agents.
- Write to: <DEEP_RESEARCH_PARTIAL_DIR>/agent-retry-<AGENT_INDEX>.json
- Return at least 2 findings. If still <2 after the broader strategy, write
  whatever you got (even 0-1) and surface the limitation in your reply.

After all retry sub-agents return, merge their partials into _findings:

openbrowser-ai -c - <<'EOF'
import os, json
global _findings
partial_dir = os.environ["DEEP_RESEARCH_PARTIAL_DIR"]
extra = []
for fname in sorted(os.listdir(partial_dir)):
    if not (fname.startswith("agent-retry-") and fname.endswith(".json")):
        continue
    path = os.path.join(partial_dir, fname)
    try:
        with open(path) as fh:
            arr = json.load(fh)
        if isinstance(arr, list):
            for item in arr:
                if "exact_url" in item and "url" not in item:
                    item["url"] = item.pop("exact_url")
            extra.extend(arr)
    except Exception as e:
        print(f"skip {path}: {e}")
_findings.extend(extra)
print(f"Retry added {len(extra)} findings -> total {len(_findings)}")
EOF

_findings lives in the daemon namespace for the next steps.

Step 3 -- Drilldown (drilldown mode only): second wave of parallel sub-agents

Skip this step in flat mode. In drilldown mode, dispatch a second wave of /dispatching-parallel-agents -- one sub-agent per needs_depth=true finding, max 3 follow-ups per parent sub-question. Each follow-up sub-agent owns ONE tab, exactly like Step 2a.

The orchestrator first picks targets:

openbrowser-ai -c - <<'EOF'
global _drill_targets
if _plan["mode"] != "drilldown":
    print("flat mode, skipping drilldown")
    _drill_targets = []
else:
    by_sq = {}
    for f in _findings:
        if f.get("needs_depth"):
            by_sq.setdefault(f["sub_question"], []).append(f)
    _drill_targets = []
    for sq, fs in by_sq.items():
        _drill_targets.extend(fs[:3])
    print(f"Drilldown targets: {len(_drill_targets)}")
    for t in _drill_targets:
        print(f"  - {t['claim'][:80]}  ({t['url']})")
EOF

Then dispatch one parallel sub-agent per drilldown target. Use the same single-tab-per-agent rule and the same partial-file output convention, but with this drilldown prompt template:

You are a deep-research drilldown sub-agent. Your job: investigate ONE claim
in ONE Chrome tab and write supporting/contradicting evidence to a JSON file.

Parent claim: <CLAIM>
Original source URL: <URL>
Agent index: <AGENT_INDEX> (use prefix "drill-" -> filename agent-drill-<AGENT_INDEX>.json)
Project root: <PROJECT_ROOT>

Hard constraints:

- You own ONE tab. NEVER pass new_tab=True to navigate() after the first call.
- Find at least 2 additional sources from at least 2 different domains
  (different from the original source URL above).
- needs_depth must be false on every finding you return (depth cap reached).
- Same JSON shape as Step 2a sub-agents: claim, url, quote, domain, confidence,
  needs_depth, plus add sub_question = "<PARENT_SUB_QUESTION>".
- Write to: <DEEP_RESEARCH_PARTIAL_DIR>/agent-drill-<AGENT_INDEX>.json

After all drilldown sub-agents return, merge their partials into _findings:

openbrowser-ai -c - <<'EOF'
import os, json
global _findings
partial_dir = os.environ["DEEP_RESEARCH_PARTIAL_DIR"]
extra = []
for fname in sorted(os.listdir(partial_dir)):
    if not (fname.startswith("agent-drill-") and fname.endswith(".json")):
        continue
    path = os.path.join(partial_dir, fname)
    try:
        with open(path) as fh:
            arr = json.load(fh)
        if isinstance(arr, list):
            for f in arr:
                f["needs_depth"] = False  # cap reached
                if "exact_url" in f and "url" not in f:
                    f["url"] = f.pop("exact_url")
            extra.extend(arr)
    except Exception as e:
        print(f"skip {path}: {e}")
_findings.extend(extra)
print(f"Drilldown added {len(extra)} findings -> total {len(_findings)}")
EOF

Step 4 -- Aggregate and dedup

Merge findings, dedup by URL, build the source index that footnote numbers will point to.

openbrowser-ai -c - <<'EOF'
from urllib.parse import urlparse

# `global` so reassignment of daemon-namespace var doesn't shadow it
global _findings, _sources

# Normalize exact_url -> url (sub-agents may use either key)
for f in _findings:
    if "exact_url" in f and "url" not in f:
        f["url"] = f.pop("exact_url")

# Dedup by URL, keep first occurrence
seen_urls = {}
deduped = []
for f in _findings:
    u = (f.get("url") or "").strip()
    if not u:
        continue  # drop uncited findings entirely
    if u in seen_urls:
        continue
    seen_urls[u] = True
    deduped.append(f)

# Build sources index, 1-based ids
_sources = []
url_to_id = {}
for f in deduped:
    u = f["url"]
    if u not in url_to_id:
        sid = len(_sources) + 1
        url_to_id[u] = sid
        domain = f.get("domain") or urlparse(u).netloc
        _sources.append({"id": sid, "url": u, "domain": domain, "title": f.get("title", "")})
    f["source_id"] = url_to_id[u]

_findings = deduped
print(f"After dedup: {len(_findings)} findings, {len(_sources)} unique sources")
EOF

Step 5 -- Render report

Write paired markdown + JSON. Every claim line in markdown ends with [N] cite. Summary cites top 3-5 sources.

openbrowser-ai -c - <<'EOF'
import json, datetime
from collections import defaultdict

# Group findings by sub-question (preserve plan order)
groups = defaultdict(list)
for f in _findings:
    groups[f["sub_question"]].append(f)

lines = []
lines.append(f"# Research: {_plan['query']}")
lines.append("")
gen = datetime.datetime.fromisoformat(_plan["generated_at"]).strftime("%Y-%m-%d %H:%M %Z").strip()
lines.append(f"Generated: {gen}  *  Mode: {_plan['mode']}  *  Sources: {len(_sources)}")
lines.append("")

# Summary: pick first finding from each sub-question, max 5 sentences
lines.append("## Summary")
lines.append("")
summary_sents = []
for sq in _plan["sub_questions"]:
    fs = groups.get(sq, [])
    if fs:
        f = fs[0]
        claim = " ".join(f["claim"].split()).rstrip(".")
        summary_sents.append(f"{claim}[{f['source_id']}].")
    if len(summary_sents) >= 5:
        break
lines.append(" ".join(summary_sents) or "_No findings._")
lines.append("")

# Per sub-question section
for sq in _plan["sub_questions"]:
    lines.append(f"## {sq}")
    lines.append("")
    fs = groups.get(sq, [])
    if not fs:
        lines.append("_No findings for this sub-question._")
        lines.append("")
        continue
    for f in fs:
        claim = " ".join(f["claim"].split()).rstrip(".")  # collapse all whitespace incl newlines
        lines.append(f"- {claim}[{f['source_id']}].")
        q = " ".join((f.get("quote") or "").split()).strip()
        if q:
            lines.append(f"  > {q}")
    lines.append("")

# Sources
lines.append("## Sources")
lines.append("")
for s in _sources:
    title = s.get("title") or s["domain"]
    lines.append(f"{s['id']}. [{title}]({s['url']})")
lines.append("")

md = "\n".join(lines)

with open(_plan["md_path"], "w") as fh:
    fh.write(md)

payload = {
    "query": _plan["query"],
    "mode": _plan["mode"],
    "generated_at": _plan["generated_at"],
    "sub_questions": _plan["sub_questions"],
    "findings": _findings,
    "sources": _sources,
}
with open(_plan["json_path"], "w") as fh:
    json.dump(payload, fh, indent=2, ensure_ascii=False)

print(f"Wrote {_plan['md_path']}")
print(f"Wrote {_plan['json_path']}")
EOF

Step 6 -- Verify citations

Fail loud if any prose sentence outside headings, quotes, code, or source list lacks a [N] cite. Fix by adding the missing source then rerendering, never by deleting prose silently.

Do the verify in plain shell python3 (not the daemon). sys.exit inside the daemon namespace kills the daemon.

python3 - "$PROJECT_ROOT" <<'EOF'
import re, sys, os

project_root = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
research_dir = os.path.join(project_root, "local_docs", "research")

# Find latest report file -- use os.listdir + absolute path (glob fails on non-shell CWD)
files = sorted(
    [os.path.join(research_dir, f) for f in os.listdir(research_dir) if f.endswith(".md")],
    key=os.path.getmtime, reverse=True
)
if not files:
    print("No report found"); sys.exit(1)
md_path = files[0]

with open(md_path) as fh: md = fh.read()
md_no_code = re.sub(r"```.*?```", "", md, flags=re.S)

violations = []
in_sources = False
for i, line in enumerate(md_no_code.splitlines(), 1):
    s = line.strip()
    if not s: continue
    if s.startswith("## Sources"):
        in_sources = True
        continue
    if in_sources: continue
    if s.startswith("#"): continue
    if s.startswith(">"): continue
    if re.match(r"^\d+\.\s+\[", s): continue
    if s.startswith("Generated:"): continue
    if s in ("_No findings._", "_No findings for this sub-question._"): continue
    if not re.search(r"\[\d+\]", s):
        violations.append((i, s[:120]))

if violations:
    print("CITATION VIOLATIONS:")
    for ln, txt in violations:
        print(f"  L{ln}: {txt}")
    sys.exit(1)
print(f"OK: all prose cited in {md_path}")
EOF

Step 7 -- Cleanup

Two cases:

Case A: daemon was already running before the skill started (DEEP_RESEARCH_REUSED=1). Close ONLY the research tabs and leave the daemon + pre-existing tabs alone:

if [ "$DEEP_RESEARCH_REUSED" = "1" ]; then
openbrowser-ai -c - <<'EOF'
state = await browser.get_browser_state_summary()
to_close = [t.target_id for t in state.tabs if t.target_id not in _preexisting_tab_ids]
print(f"Closing {len(to_close)} research tabs, preserving {len(_preexisting_tab_ids)} pre-existing")
for tid in to_close:
    try:
        await close(tab_id=tid)
    except Exception as e:
        print(f"  skip {tid[-4:]}: {e}")
EOF
fi

Case B: daemon was started fresh by this skill (DEEP_RESEARCH_REUSED=0). Full daemon stop, freeing the Chrome process. See Cleanup section below.

Always: the final cleanup below removes this run's partial directory and run directory after the report is written. If an owned daemon cannot be shut down, it keeps the run directory intact so the partials and environment remain available for recovery.

Tips

  • Source the run environment first: every later Bash call must begin with . "<RUN_ENV_FILE>", using the exact absolute path printed by Step 0. Bare exports do not survive separate shell blocks.
  • Headless by default: OPENBROWSER_HEADLESS=true is set in Step 0 so the daemon always starts without a visible browser window. The daemon default in daemon/server.py is already headless: True, but a user config file can override it. The env var wins over config. If you need a visible window for debugging, unset or override: export OPENBROWSER_HEADLESS=false.
  • One tab per sub-agent: the orchestrator dispatches via /dispatching-parallel-agents and each sub-agent must own exactly one tab. Multiple-tab sub-agents serialize navigation at the CDP layer and lose the parallelism benefit. Enforce in the agent prompt: "NEVER pass new_tab=True to navigate() after the first call."
  • Single message, multiple Agent calls: to actually parallelize, the orchestrator must put all N Agent tool calls in ONE message. Sequential Agent invocations across messages run serially.
  • Heredoc quoting: always use <<'EOF' (single-quoted) so $, backticks, and ! inside Python don't expand in the shell.
  • Daemon namespace: _plan, _findings, _sources persist across orchestrator -c calls. Sub-agents share the same daemon and so see the same namespace, but each operates in its own tab. Don't restart the daemon mid-run.
  • Partial files as the contract: sub-agents write to $DEEP_RESEARCH_PARTIAL_DIR/agent-NN.json, the orchestrator reads them back. Sub-agents do NOT communicate findings via stdout. If a partial file is missing or empty, that sub-agent failed; rerun it or fall through to Step 2b.
  • exact_url normalization: sub-agents may write exact_url instead of url. All merge steps (Step 2a, 2b, 3) normalize this automatically. Step 4 has a final safety pass. Never rely on url being set before the merge step runs.
  • Daemon restart recovery: if the daemon restarts mid-session, _plan/_findings/_sources are lost from namespace. Partial JSON files under $DEEP_RESEARCH_PARTIAL_DIR survive. Source the same run environment and re-run the Step 2a merge block. Re-run Step 1 with the same QUERY and project root to restore _plan; the slug-collision bump avoids overwriting the existing output file.
  • No -p, ever: this skill never shells out to openbrowser-ai -p. The -p mode runs the full Browser Agent loop with LLM-driven navigation and requires an OpenAI / Anthropic / Google API key (cli.py:434-490 get_llm()). The -c daemon path needs no API key. If you see -p anywhere in skill code, that is a bug.
  • Source diversity: if dedup leaves <60% of findings (heavy domain repetition), rerun the affected sub-agent with explicit "prefer different domains than: " appended to its prompt.
  • Drilldown cost: drilldown dispatches up to len(sub_questions) * 3 extra parallel sub-agents. Reserve for genuinely deep topics.
  • Rerun semantics: rerunning Step 5 alone re-renders from current _findings, useful after manual edits.
  • Slug collisions: Step 1 auto-bumps -2, -3 if file exists, so rerunning the same query never overwrites.

Cleanup

Mandatory. Run after every workflow, success or failure.

If this skill started the daemon (DEEP_RESEARCH_REUSED=0), use daemon force-stop. It targets the current daemon endpoint (the configured Unix socket on macOS/Linux, the fixed loopback port on Windows) and verifies listener and owner absence before it reports success. Delete the profile and run directory only after that success:

. "$DEEP_RESEARCH_ENV_FILE"
DEEP_RESEARCH_CLEANUP_OK=0
if [ "$DEEP_RESEARCH_REUSED" = "0" ]; then
    if openbrowser-ai daemon force-stop; then
        rm -rf "$OPENBROWSER_DAEMON_PROFILE_DIR" 2>/dev/null || true
        rm -f "${OPENBROWSER_SOCKET%.sock}.log" "${OPENBROWSER_SOCKET%.sock}.pid" 2>/dev/null || true
        DEEP_RESEARCH_CLEANUP_OK=1
    else
        echo "Daemon shutdown could not be verified. Keeping $OPENBROWSER_DAEMON_PROFILE_DIR and $DEEP_RESEARCH_RUN_DIR for manual cleanup."
    fi
else
    DEEP_RESEARCH_CLEANUP_OK=1
fi
if [ "$DEEP_RESEARCH_CLEANUP_OK" = "1" ]; then
    rm -rf "$DEEP_RESEARCH_RUN_DIR" 2>/dev/null || true
fi

If daemon was reused (DEEP_RESEARCH_REUSED=1), Step 7 already closed only the research tabs. Do NOT call daemon stop or daemon force-stop, that kills the user's pre-existing browser session.

Install this trap only after Step 0 has sourced the dedicated environment and set DEEP_RESEARCH_OWNED. It never fires for an unset or default environment and never deletes the profile:

trap 'if [ "${DEEP_RESEARCH_OWNED:-0}" = "1" ] && [ -n "${OPENBROWSER_SOCKET:-}" ]; then openbrowser-ai daemon force-stop >/dev/null 2>&1 || true; fi' EXIT

Anti-patterns:

  • Do NOT daemon stop when reusing an existing session; that kills the user's open tabs.
  • Do NOT rely on the 600s idle timeout; that wastes a Chrome process for 10 minutes.
  • Do NOT use done() as a substitute; it only ends the agent loop, browser stays open.
  • Do NOT mix --mcp mode with the daemon in one workflow; they have separate persistent namespaces and browser profiles.

End-to-End Testing

Simulate real user interactions and verify web application behavior using Python code execution. Covers navigation, form interaction, content assertions, and multi-page flows.

All code runs via openbrowser-ai -c. The daemon starts automatically and persists variables across calls. All browser functions are async -- use await.

The CLI daemon also persists cookies and login state in ~/.config/openbrowser/profiles/daemon/storage_state.json, so authenticated sessions can be reused across later runs.

Setup

Before running, verify openbrowser-ai is installed:

openbrowser-ai --help

If not found, install:

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.ps1 | iex

Workflow

Step 1 -- Navigate and verify page load

openbrowser-ai -c - <<'EOF'
await navigate("https://staging.example.com")
state = await browser.get_browser_state_summary()

assert "example" in state.url.lower(), f"Unexpected URL: {state.url}"
assert state.title, "Page title is empty"
print(f"Page loaded: {state.title} ({state.url})")
EOF

Step 2 -- Content assertions

openbrowser-ai -c - <<'EOF'
# Check for expected text using JS
has_welcome = await evaluate("""
(function(){ return !!document.body.textContent.match(/Welcome to Example App/i) })()
""")
assert has_welcome, "Welcome message not found"

# Check specific element content
h1_text = await evaluate("document.querySelector('h1')?.textContent?.trim()")
assert h1_text == "Example App", f'Expected "Example App", got "{h1_text}"'

# Check no error messages
error_count = await evaluate("document.querySelectorAll('.error-message').length")
assert error_count == 0, f"Found {error_count} error messages on page"

print("All content assertions passed")
EOF

Step 3 -- Test user interactions (login flow)

openbrowser-ai -c - <<'EOF'
# Get form fields
state = await browser.get_browser_state_summary()
for idx, el in state.dom_state.selector_map.items():
    if el.attributes.get("type") in ("email", "text", "password") or el.tag_name == "button":
        etype = el.attributes.get("type", "")
        placeholder = el.attributes.get("placeholder", "")
        print(f"[{idx}] <{el.tag_name}> type={etype} placeholder=\"{placeholder}\"")

# Fill and submit
await input_text(index=3, text="test@example.com")
await input_text(index=4, text="test-password")
await click(index=5)  # Login button
await wait(2)

# Assert logged in
state = await browser.get_browser_state_summary()
assert "dashboard" in state.url.lower() or "welcome" in state.title.lower(), \
    f"Login may have failed. URL: {state.url}, Title: {state.title}"
print("Login test passed")
EOF

Step 4 -- Test navigation flows

openbrowser-ai -c - <<'EOF'
# Click settings link
state = await browser.get_browser_state_summary()
for idx, el in state.dom_state.selector_map.items():
    if "settings" in el.get_all_children_text(max_depth=1).lower():
        await click(index=idx)
        break

await wait(1)

# Assert URL changed
path = await evaluate("window.location.pathname")
assert "/settings" in path, f"Expected /settings path, got {path}"

# Test back button
await go_back()
await wait(1)
state = await browser.get_browser_state_summary()
print(f"After back: {state.url}")
EOF

Step 5 -- Test error handling

openbrowser-ai -c - <<'EOF'
# Submit form with invalid data
await input_text(index=3, text="not-an-email")
await click(index=5)
await wait(1)

# Assert validation errors appear
errors = await evaluate("""
(function(){
  const errs = document.querySelectorAll(".error, .invalid-feedback, [aria-invalid=\"true\"]");
  return Array.from(errs).map(e => e.textContent.trim());
})()
""")
assert len(errors) > 0, "Expected validation errors but found none"
print(f"Validation errors shown: {errors}")

# Assert page did not navigate
path = await evaluate("window.location.pathname")
print(f"Still on: {path}")
EOF

Step 6 -- Test responsive behavior

openbrowser-ai -c - <<'EOF'
viewport = await evaluate("""
(function(){
  return {
    width: window.innerWidth,
    height: window.innerHeight
  }
})()
""")
vw = viewport["width"]
vh = viewport["height"]
print(f"Viewport: {vw}x{vh}")

# Check mobile menu visibility
mobile_display = await evaluate("""
(function(){
  const el = document.querySelector(".mobile-menu");
  return el ? window.getComputedStyle(el).display : "not found";
})()
""")
print(f"Mobile menu display: {mobile_display}")
EOF

Step 7 -- Test multi-page flows

openbrowser-ai -c - <<'EOF'
test_results = []

# Cart page
await navigate("https://staging.example.com/cart")
await wait(1)
cart_title = await evaluate("document.querySelector('h1')?.textContent?.trim()")
test_results.append({"test": "cart_page_loads", "passed": cart_title is not None, "detail": cart_title})

# Checkout
cart_count = await evaluate("JSON.parse(localStorage.getItem('cart'))?.items?.length || 0")
test_results.append({"test": "cart_has_items", "passed": cart_count > 0, "detail": f"{cart_count} items"})

# Print results
import json
passed = sum(1 for t in test_results if t["passed"])
total = len(test_results)
print(f"\nResults: {passed}/{total} passed")
print(json.dumps(test_results, indent=2))
EOF

Tips

  • Code is piped via stdin using heredoc (-c - <<'EOF'), so all Python syntax works without shell escaping issues.
  • Use Python assert statements for test assertions -- they produce clear error messages on failure.
  • Always verify page state after each interaction before proceeding.
  • Test both happy paths and error paths for thorough coverage.
  • Use await wait(N) after interactions that trigger page loads or animations.
  • Variables persist between -c calls while the daemon is running, so you can accumulate test results across calls.
  • Use evaluate() for DOM state assertions and browser.get_browser_state_summary() for page metadata.

Cleanup

This step is mandatory. Run it after the test run finishes, whether assertions passed or failed. Without it, the daemon keeps Chrome running until its 10-minute idle timeout, leaving a stale browser process, a locked profile, and (on macOS/Linux desktop) a visible window.

Stop the daemon, then verify it is gone:

openbrowser-ai daemon stop
openbrowser-ai daemon status

daemon stop closes every tab, exits Chrome, flushes saved cookies/login state to the profile, and shuts down the daemon process. daemon status should report the daemon is not running. If it still reports running, run openbrowser-ai daemon force-stop. It targets the current daemon endpoint: the configured OPENBROWSER_SOCKET on macOS/Linux, or the fixed loopback port on Windows. It verifies listener and owner absence before success. daemon reap is broader: it scans the default socket plus custom sockets that have a matching PID file and attempts to stop verified daemons. Inspect its JSON before accepting global cleanup.

E2E runs fail often by design (that is what assertions are for). Guarantee cleanup with a shell trap so a failed assertion never leaks a browser:

trap 'openbrowser-ai daemon stop >/dev/null 2>&1 || true' EXIT
# ... openbrowser-ai -c calls here ...

Do not rely on the idle timeout. Do not call done() as a substitute, done() only marks the task complete inside the agent loop, it does not close the browser.

File Download

Download files from websites using the browser's authenticated session. Handles PDFs, CSVs, images, and any downloadable content. Preserves cookies and login sessions for authenticated downloads.

All code runs via openbrowser-ai -c. The daemon starts automatically and persists variables across calls. All browser functions are async -- use await.

The CLI daemon also persists cookies and login state in ~/.config/openbrowser/profiles/daemon/storage_state.json, so authenticated sessions can be reused across later runs.

Setup

Before running, verify openbrowser-ai is installed:

openbrowser-ai --help

If not found, install:

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.ps1 | iex

Workflow

Step 1 -- Navigate and find download links

openbrowser-ai -c - <<'EOF'
await navigate("https://example.com/reports")

# Get browser state to find clickable download links
state = await browser.get_browser_state_summary()
for idx, el in state.dom_state.selector_map.items():
    text = el.get_all_children_text(max_depth=1)
    if "download" in text.lower() or "pdf" in text.lower() or "export" in text.lower():
        print(f"[{idx}] {el.tag_name}: {text}")
EOF

Step 2 -- Download a file by URL

Use download_file() to download directly. This uses the browser's JavaScript fetch internally, preserving cookies and authentication:

openbrowser-ai -c - <<'EOF'
path = await download_file("https://example.com/reports/annual-report.pdf")
print(f"Saved to: {path}")
EOF

With a custom filename:

openbrowser-ai -c - <<'EOF'
path = await download_file(
    "https://example.com/api/export?format=csv",
    filename="sales-data.csv"
)
print(f"Saved to: {path}")
EOF

Step 3 -- Extract a download URL from the page

When the download URL is not directly visible, extract it from a link or button:

openbrowser-ai -c - <<'EOF'
# Extract href from a download link
download_url = await evaluate("""
(function(){
  const link = document.querySelector("a[href$=\".pdf\"]");
  return link ? link.href : null;
})()
""")

if download_url:
    path = await download_file(download_url)
    print(f"Downloaded: {path}")
else:
    print("No PDF link found")
EOF

Step 4 -- Read a downloaded PDF

After downloading, use pypdf to extract text (requires pip install openbrowser-ai[pdf]):

openbrowser-ai -c - <<'EOF'
from pypdf import PdfReader

reader = PdfReader(path)
print(f"Pages: {len(reader.pages)}")

# Extract text from all pages
for i, page in enumerate(reader.pages):
    text = page.extract_text()
    print(f"--- Page {i+1} ---")
    print(text[:500])
EOF

Step 5 -- Read other file types

openbrowser-ai -c - <<'EOF'
from pathlib import Path

file_path = Path(path)

# CSV
if file_path.suffix == ".csv":
    import pandas as pd
    df = pd.read_csv(file_path)
    print(df.to_string())

# JSON
if file_path.suffix == ".json":
    import json
    data = json.loads(file_path.read_text())
    print(json.dumps(data, indent=2))

# Plain text
if file_path.suffix in (".txt", ".md", ".log"):
    print(file_path.read_text())
EOF

Step 6 -- Download multiple files

openbrowser-ai -c - <<'EOF'
urls = [
    "https://example.com/report-q1.pdf",
    "https://example.com/report-q2.pdf",
    "https://example.com/report-q3.pdf",
]

paths = []
for url in urls:
    path = await download_file(url)
    paths.append(path)
    print(f"Downloaded: {path}")

print(f"Total files: {len(paths)}")
EOF

Step 7 -- List all downloads

openbrowser-ai -c - <<'EOF'
files = list_downloads()
for f in files:
    print(f)
print(f"Total: {len(files)} files")
EOF

Step 8 -- Download from authenticated pages

download_file() preserves the browser's login session. Log in first, then download:

openbrowser-ai -c - <<'EOF'
# Navigate and log in
await navigate("https://portal.example.com/login")
await input_text(username_index, "user@example.com")
await input_text(password_index, "password")
await click(login_button_index)
await wait(2)

# Now download an authenticated resource
path = await download_file("https://portal.example.com/api/reports/confidential.pdf")
print(f"Downloaded: {path}")
EOF

Tips

  • Code is piped via stdin using heredoc (-c - <<'EOF'), so all Python syntax works without shell escaping issues.
  • Use download_file(url) instead of navigate(url) for files. navigate() opens PDFs in the browser viewer but does not save them.
  • download_file() preserves cookies and authentication -- no need to re-authenticate.
  • Filename conflicts are handled automatically with (N) suffix (e.g., report (1).pdf).
  • If no filename is provided, it is derived from the URL path.
  • Use list_downloads() to see all files saved in the downloads directory.
  • For large files, download_file() has a 120-second timeout.
  • The fallback strategy uses Python requests if the browser fetch fails (e.g., CORS restrictions), but without browser cookies.

Cleanup

This step is mandatory. Run it after every download run, whether the file landed successfully or the request failed. Without it, the daemon keeps Chrome running until its 10-minute idle timeout, leaving a stale browser process, a locked profile, and (on macOS/Linux desktop) a visible window.

Stop the daemon, then verify it is gone:

openbrowser-ai daemon stop
openbrowser-ai daemon status

daemon stop closes every tab, exits Chrome, flushes saved cookies/login state to the profile, and shuts down the daemon process. daemon status should report the daemon is not running. If it still reports running, run openbrowser-ai daemon force-stop. It targets the current daemon endpoint: the configured OPENBROWSER_SOCKET on macOS/Linux, or the fixed loopback port on Windows. It verifies listener and owner absence before success. daemon reap is broader: it scans the default socket plus custom sockets that have a matching PID file and attempts to stop verified daemons. Inspect its JSON before accepting global cleanup.

If a download can fail mid-workflow (timeout, 4xx/5xx, CORS), guarantee cleanup with a shell trap so the browser is never left orphaned:

trap 'openbrowser-ai daemon stop >/dev/null 2>&1 || true' EXIT
# ... openbrowser-ai -c calls here ...

Downloaded files in ~/.config/openbrowser/downloads/ survive daemon stop, only the browser process is terminated. Do not rely on the idle timeout. Do not call done() as a substitute, done() only marks the task complete inside the agent loop, it does not close the browser.

Form Filling

Automate filling web forms including login, registration, checkout, and multi-step form wizards using Python code execution.

All code runs via openbrowser-ai -c. The daemon starts automatically and persists variables across calls. All browser functions are async -- use await.

The CLI daemon also persists cookies and login state in ~/.config/openbrowser/profiles/daemon/storage_state.json, so authenticated sessions can be reused across later runs.

Setup

Before running, verify openbrowser-ai is installed:

openbrowser-ai --help

If not found, install:

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.ps1 | iex

Workflow

Step 1 -- Navigate to the form page

openbrowser-ai -c - <<'EOF'
await navigate("https://example.com/login")
state = await browser.get_browser_state_summary()
print(f"Page: {state.title} ({state.url})")
print(f"Interactive elements: {len(state.dom_state.selector_map)}")
EOF

Step 2 -- Discover form fields

openbrowser-ai -c - <<'EOF'
# List all interactive elements with their indices
state = await browser.get_browser_state_summary()
for index, element in state.dom_state.selector_map.items():
    tag = element.tag_name
    text = element.get_all_children_text(max_depth=2)[:60]
    placeholder = element.attributes.get("placeholder", "")
    input_type = element.attributes.get("type", "")
    name = element.attributes.get("name", "")
    print(f"[{index}] <{tag}> type={input_type} name={name} placeholder=\"{placeholder}\" text=\"{text}\"")
EOF

Step 3 -- Fill text inputs

openbrowser-ai -c - <<'EOF'
# Fill fields using their indices from Step 2
await input_text(index=5, text="user@example.com")
await input_text(index=7, text="secure-password")
EOF

For fields that need clearing first:

openbrowser-ai -c - <<'EOF'
await click(index=5)
await evaluate("document.activeElement.select()")
await input_text(index=5, text="new-value")
EOF

Step 4 -- Handle dropdowns

Standard HTML select elements:

openbrowser-ai -c - <<'EOF'
await select_dropdown(index=12, text="United States")
EOF

To see available options first:

openbrowser-ai -c - <<'EOF'
options = await dropdown_options(index=12)
print(options)
EOF

Custom dropdown components:

openbrowser-ai -c - <<'EOF'
await evaluate("""
(function(){
  const select = document.querySelector("select#country");
  select.value = "US";
  select.dispatchEvent(new Event("change", { bubbles: true }));
})()
""")
EOF

Step 5 -- Handle checkboxes and radio buttons

openbrowser-ai -c - <<'EOF'
await click(index=15)  # Click checkbox/radio

# Verify state
checked = await evaluate("""document.querySelector("input[name=agree]").checked""")
print(f"Checkbox checked: {checked}")
EOF

Step 6 -- Submit the form

openbrowser-ai -c - <<'EOF'
await click(index=20)  # Click submit button
await wait(2)

# Verify submission
state = await browser.get_browser_state_summary()
print(f"After submit: {state.url}")
EOF

Or submit via JavaScript:

openbrowser-ai -c - <<'EOF'
await evaluate("document.querySelector(\"form\").submit()")
EOF

Step 7 -- Verify submission result

openbrowser-ai -c - <<'EOF'
# Check for success/error messages
result = await evaluate("""
(function(){
  const success = document.querySelector(".success, .alert-success, [role=\"alert\"]");
  const error = document.querySelector(".error, .alert-danger, .validation-error");
  return {
    success: success?.textContent?.trim(),
    error: error?.textContent?.trim(),
    url: window.location.href
  };
})()
""")
print(result)
EOF

Step 8 -- Handle multi-step forms

openbrowser-ai -c - <<'EOF'
for step in range(1, 5):
    # Discover fields for current step
    state = await browser.get_browser_state_summary()
    print(f"Step {step}: {len(state.dom_state.selector_map)} elements")

    # Fill fields (indices vary per step)
    # ... fill fields here ...

    # Click Next/Continue
    # Find the next button
    for idx, el in state.dom_state.selector_map.items():
        text = el.get_all_children_text(max_depth=1).lower()
        if "next" in text or "continue" in text:
            await click(index=idx)
            await wait(2)
            break
EOF

Tips

  • Code is piped via stdin using heredoc (-c - <<'EOF'), so all Python syntax works without shell escaping issues.
  • Always discover fields with browser.get_browser_state_summary() before typing -- do not guess element indices.
  • For sensitive data (passwords, tokens), confirm with the user before entering values.
  • Use evaluate() to bypass custom components that do not respond to standard click/type.
  • Variables persist between -c calls while the daemon is running, so you can store field indices in one call and use them in the next.
  • Check for CAPTCHA or bot detection; notify the user if manual intervention is needed.

Cleanup

This step is mandatory. Run it after the form submission finishes, whether the submit succeeded or the form rejected the input. Without it, the daemon keeps Chrome running until its 10-minute idle timeout, leaving a stale browser process, a locked profile, and (on macOS/Linux desktop) a visible window with the form still on screen.

Stop the daemon, then verify it is gone:

openbrowser-ai daemon stop
openbrowser-ai daemon status

daemon stop closes every tab, exits Chrome, flushes saved cookies/login state to the profile (so the next run reuses the login), and shuts down the daemon process. daemon status should report the daemon is not running. If it still reports running, run openbrowser-ai daemon doctor and then openbrowser-ai daemon reap. reap stops only verified OpenBrowser daemons and removes stale sockets and PID files.

Form runs can fail mid-workflow (validation error, CAPTCHA, network drop). Guarantee cleanup with a shell trap so a half-filled form never leaks a browser:

trap 'openbrowser-ai daemon stop >/dev/null 2>&1 || true' EXIT
# ... openbrowser-ai -c calls here ...

Do not rely on the idle timeout. Do not call done() as a substitute, done() only marks the task complete inside the agent loop, it does not close the browser.

Page Analysis

Analyze and understand web page content, structure, and interactive elements using Python code execution. Produces a comprehensive breakdown of what is on the page and how it is organized.

All code runs via openbrowser-ai -c. The daemon starts automatically and persists variables across calls. All browser functions are async -- use await.

The CLI daemon also persists cookies and login state in ~/.config/openbrowser/profiles/daemon/storage_state.json, so authenticated sessions can be reused across later runs.

Setup

Before running, verify openbrowser-ai is installed:

openbrowser-ai --help

If not found, install:

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.ps1 | iex

Workflow

Step 1 -- Navigate and get overview

openbrowser-ai -c - <<'EOF'
await navigate("https://example.com")
state = await browser.get_browser_state_summary()
print(f"Title: {state.title}")
print(f"URL: {state.url}")
print(f"Interactive elements: {len(state.dom_state.selector_map)}")
print(f"Tabs: {len(state.tabs)}")
EOF

Step 2 -- Extract page metadata

openbrowser-ai -c - <<'EOF'
meta = await evaluate("""
(function(){
  return {
    title: document.title,
    description: document.querySelector("meta[name='description']")?.content,
    canonical: document.querySelector("link[rel='canonical']")?.href,
    ogTitle: document.querySelector("meta[property='og:title']")?.content,
    ogImage: document.querySelector("meta[property='og:image']")?.content,
    lang: document.documentElement.lang,
    charset: document.characterSet
  };
})()
""")

import json
print(json.dumps(meta, indent=2))
EOF

Step 3 -- Detect frameworks and technologies

openbrowser-ai -c - <<'EOF'
tech = await evaluate("""
(function(){
  const t = [];
  if (window.__NEXT_DATA__) t.push("Next.js");
  if (window.__NUXT__) t.push("Nuxt.js");
  if (document.querySelector("[data-reactroot]") || document.querySelector("#__next")) t.push("React");
  if (document.querySelector("[ng-version]")) t.push("Angular");
  if (window.jQuery) t.push("jQuery");
  if (window.Vue) t.push("Vue.js");
  if (document.querySelector("[data-svelte]")) t.push("Svelte");
  return t;
})()
""")
print(f"Technologies detected: {tech}")
EOF

Step 4 -- Content summary and statistics

openbrowser-ai -c - <<'EOF'
stats = await evaluate("""
(function(){
  return {
    headings: document.querySelectorAll("h1,h2,h3,h4,h5,h6").length,
    paragraphs: document.querySelectorAll("p").length,
    images: document.querySelectorAll("img").length,
    links: document.querySelectorAll("a").length,
    forms: document.querySelectorAll("form").length,
    tables: document.querySelectorAll("table").length,
    lists: document.querySelectorAll("ul,ol").length,
    buttons: document.querySelectorAll("button,[role='button']").length,
    inputs: document.querySelectorAll("input,textarea,select").length,
    iframes: document.querySelectorAll("iframe").length,
    scripts: document.querySelectorAll("script").length,
    stylesheets: document.querySelectorAll("link[rel='stylesheet']").length
  };
})()
""")

import json
print("Content statistics:")
print(json.dumps(stats, indent=2))
EOF

Step 5 -- Analyze heading structure

openbrowser-ai -c - <<'EOF'
headings = await evaluate("""
(function(){
  return Array.from(document.querySelectorAll("h1,h2,h3,h4,h5,h6")).map(h => ({
    tag: h.tagName,
    text: h.textContent.trim().substring(0, 80)
  }));
})()
""")

for h in headings:
    htag = h["tag"]
    htext = h["text"]
    indent = "  " * (int(htag[1]) - 1)
    print(f"{indent}{htag}: {htext}")
EOF

Step 6 -- Analyze interactive elements

openbrowser-ai -c - <<'EOF'
state = await browser.get_browser_state_summary()
elements_by_tag = {}
for idx, el in state.dom_state.selector_map.items():
    tag = el.tag_name
    elements_by_tag.setdefault(tag, []).append({
        "index": idx,
        "text": el.get_all_children_text(max_depth=1)[:50],
        "type": el.attributes.get("type", ""),
        "href": el.attributes.get("href", "")[:50] if el.attributes.get("href") else "",
    })

for tag, elems in sorted(elements_by_tag.items()):
    print(f"\n{tag} ({len(elems)} elements):")
    for e in elems[:5]:
        eidx = e["index"]
        etxt = e["text"]
        etype = e["type"]
        ehref = e["href"]
        print(f"  [{eidx}] text=\"{etxt}\" type={etype} href={ehref}")
    if len(elems) > 5:
        print(f"  ... and {len(elems) - 5} more")
EOF

Step 7 -- Page dimensions and scroll analysis

openbrowser-ai -c - <<'EOF'
dims = await evaluate("""
(function(){
  return {
    viewportWidth: window.innerWidth,
    viewportHeight: window.innerHeight,
    scrollHeight: document.body.scrollHeight,
    scrollWidth: document.body.scrollWidth,
    scrollable: document.body.scrollHeight > window.innerHeight
  };
})()
""")

import json
print(json.dumps(dims, indent=2))
if dims["scrollable"]:
    pages = dims["scrollHeight"] / dims["viewportHeight"]
    print(f"Page is approximately {pages:.1f} viewport heights long")
EOF

Step 8 -- Search for specific content patterns

openbrowser-ai -c - <<'EOF'
import re

# Get page text for Python-side analysis
text_content = await evaluate("document.body.innerText")

# Find emails
emails = re.findall(r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}", text_content)
print(f"Emails found: {emails}")

# Find phone numbers
phones = re.findall(r"\+?\d[\d\s()-]{7,}", text_content)
print(f"Phone numbers found: {phones}")

# Find dates
dates = re.findall(r"\d{4}-\d{2}-\d{2}|\w+ \d{1,2},? \d{4}", text_content)
print(f"Dates found: {dates}")
EOF

Tips

  • Code is piped via stdin using heredoc (-c - <<'EOF'), so all Python syntax works without shell escaping issues.
  • Start with evaluate() for metadata and DOM statistics -- gives a fast structured overview.
  • Use browser.get_browser_state_summary() for interactive element analysis.
  • Use Python regex on extracted text for pattern matching (emails, phones, dates, prices).
  • For long pages, use await scroll(down=True) and re-extract to analyze below-fold content.
  • Variables persist between -c calls while the daemon is running, so you can build a comprehensive analysis incrementally.

Cleanup

This step is mandatory. Run it after the analysis finishes, whether extraction succeeded or the page failed to load. Without it, the daemon keeps Chrome running until its 10-minute idle timeout, leaving a stale browser process, a locked profile, and (on macOS/Linux desktop) a visible window.

Stop the daemon, then verify it is gone:

openbrowser-ai daemon stop
openbrowser-ai daemon status

daemon stop closes every tab, exits Chrome, flushes saved cookies/login state to the profile, and shuts down the daemon process. daemon status should report the daemon is not running. If it still reports running, run openbrowser-ai daemon doctor and then openbrowser-ai daemon reap. reap stops only verified OpenBrowser daemons and removes stale sockets and PID files.

If your invocation can fail mid-workflow (timeout, navigation error, malformed DOM), guarantee cleanup with a shell trap so the browser is never left orphaned:

trap 'openbrowser-ai daemon stop >/dev/null 2>&1 || true' EXIT
# ... openbrowser-ai -c calls here ...

Do not rely on the idle timeout. Do not call done() as a substitute, done() only marks the task complete inside the agent loop, it does not close the browser.

Web Scraping

Extract structured data from websites using Python code execution with browser automation functions. Handles JavaScript-rendered content, pagination, and multi-page scraping.

All code runs via openbrowser-ai -c. The daemon starts automatically and persists variables across calls. All browser functions are async -- use await.

The CLI daemon also persists cookies and login state in ~/.config/openbrowser/profiles/daemon/storage_state.json, so authenticated sessions can be reused across later runs.

Setup

Before running, verify openbrowser-ai is installed:

openbrowser-ai --help

If not found, install:

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.ps1 | iex

Workflow

Step 1 -- Navigate and get content overview

openbrowser-ai -c - <<'EOF'
await navigate("https://example.com/data")

# Get browser state to see page title, URL, element count
state = await browser.get_browser_state_summary()
print(f"Title: {state.title}")
print(f"URL: {state.url}")
print(f"Elements: {len(state.dom_state.selector_map)}")
EOF

Step 2 -- Extract data with JavaScript

Use evaluate() to run JS in the browser and return structured data directly as Python objects:

openbrowser-ai -c - <<'EOF'
data = await evaluate("""
(function(){
  return Array.from(document.querySelectorAll(".product-card")).map(el => ({
    name: el.querySelector(".title")?.textContent?.trim(),
    price: el.querySelector(".price")?.textContent?.trim(),
    url: el.querySelector("a")?.href
  }))
})()
""")

import json
print(json.dumps(data, indent=2))
EOF

Step 3 -- Process data with Python

Use pandas, regex, or other Python tools to clean and transform extracted data:

openbrowser-ai -c - <<'EOF'
import json

# Filter and transform
filtered = [item for item in data if item.get("price")]
for item in filtered:
    # Extract numeric price
    price_str = item["price"].replace("$", "").replace(",", "")
    item["price_float"] = float(price_str)

# Sort by price
filtered.sort(key=lambda x: x["price_float"])
print(json.dumps(filtered, indent=2))
EOF

Or with pandas if available:

openbrowser-ai -c - <<'EOF'
import pandas as pd
df = pd.DataFrame(data)
print(df.to_string())
EOF

Step 4 -- Handle pagination

openbrowser-ai -c - <<'EOF'
results = []
page = 1

while True:
    # Extract data from current page
    page_data = await evaluate("""
    (function(){
      return Array.from(document.querySelectorAll(".item")).map(el => ({
        name: el.textContent.trim()
      }))
    })()
    """)
    results.extend(page_data)
    print(f"Page {page}: {len(page_data)} items")

    # Check for next button
    has_next = await evaluate("""
    (function(){ return !!document.querySelector(".pagination .next:not(.disabled)") })()
    """)

    if not has_next:
        break

    # Replace with the actual index from browser.get_browser_state_summary()
    await click(next_button_index)
    await wait(2)
    page += 1

print(f"Total: {len(results)} items")
EOF

Step 5 -- Handle infinite scroll

openbrowser-ai -c - <<'EOF'
results = []
prev_count = 0

for _ in range(20):  # Max 20 scroll attempts
    # Get current items
    count = await evaluate("""
    (function(){ return document.querySelectorAll(".item").length })()
    """)

    if count == prev_count:
        break  # No new content loaded

    prev_count = count
    await scroll(down=True, pages=3)
    await wait(1)

# Now extract all loaded items
results = await evaluate("""
(function(){
  return Array.from(document.querySelectorAll(".item")).map(el => ({
    text: el.textContent.trim()
  }))
})()
""")
print(f"Extracted {len(results)} items")
EOF

Step 6 -- Multi-page scraping

openbrowser-ai -c - <<'EOF'
urls = [
    "https://example.com/page-1",
    "https://example.com/page-2",
    "https://example.com/page-3",
]

all_data = []
for url in urls:
    await navigate(url)
    await wait(1)

    page_data = await evaluate("""
    (function(){
      return document.querySelector("h1")?.textContent?.trim()
    })()
    """)
    all_data.append({"url": url, "title": page_data})
    print(f"{url}: {page_data}")

import json
print(json.dumps(all_data, indent=2))
EOF

Tips

  • Code is piped via stdin using heredoc (-c - <<'EOF'), so all Python syntax works without shell escaping issues.
  • Use evaluate() for structured DOM extraction -- it returns Python objects directly.
  • Use Python for post-processing: filtering, sorting, deduplication, format conversion.
  • For large datasets, process pages incrementally rather than loading everything into memory.
  • Check for rate limiting; add await wait(2) between page loads if needed.
  • Variables persist between -c calls while the daemon is running, so you can build up results across multiple calls.

Cleanup

This step is mandatory. Run it after the scrape finishes, whether you collected every page or hit a rate limit halfway through. Without it, the daemon keeps Chrome running until its 10-minute idle timeout, leaving a stale browser process, a locked profile, and (on macOS/Linux desktop) a visible window.

Stop the daemon, then verify it is gone:

openbrowser-ai daemon stop
openbrowser-ai daemon status

daemon stop closes every tab, exits Chrome, flushes saved cookies/login state to the profile, and shuts down the daemon process. daemon status should report the daemon is not running. If it still reports running, run openbrowser-ai daemon force-stop. It targets the current daemon endpoint: the configured OPENBROWSER_SOCKET on macOS/Linux, or the fixed loopback port on Windows. It verifies listener and owner absence before success. daemon reap is broader: it scans the default socket plus custom sockets that have a matching PID file and attempts to stop verified daemons. Inspect its JSON before accepting global cleanup.

Long scrapes fail often (rate limits, network drops, pagination dead-ends). Guarantee cleanup with a shell trap so a partial run never leaks a browser:

trap 'openbrowser-ai daemon stop >/dev/null 2>&1 || true' EXIT
# ... openbrowser-ai -c calls here ...

Persist scraped data to disk before calling daemon stop, in-memory variables die with the daemon. Do not rely on the idle timeout. Do not call done() as a substitute, done() only marks the task complete inside the agent loop, it does not close the browser.

MCP servers 1

Sponsors

Details

Marketplace
billy-enrizky/openbrowser-ai
Source
plugin
Category
Development
License
MIT