reflex-browser

Reflex Browser Skill

Purpose

Use this skill when the task involves a website or browser: navigating pages, clicking elements, reading content, filling forms, scraping data, or automating a web flow.

This skill covers interactive browser work via reflex browser ... CLI commands. Each command is a single stateless action — run one, inspect the JSON response, then decide the next step.

When the end goal is a reusable Lua or Python browser automation script, still start here first: use reflex browser ... to inspect the site, verify the flow, and stabilize selectors before writing script code. Then switch to the reflex-scripting skill for the script itself.

When To Use This Skill

• User asks to interact with a website (navigate, click, fill, read, scrape)
• User asks to inspect or explore a page
• User asks for browser-based data collection
• User asks for a browser automation script (start here for discovery, then reflex-scripting for the script)

When NOT To Use This Skill

• One-off file manipulation (xlsx, csv, json) without a browser → use reflex-scripting
• REST API calls → use reflex-scripting
• Data transforms or batch processing without a browser → use reflex-scripting
• Writing a script after browser discovery is done → use reflex-scripting

Quick Start

1. Install globally from Gitea npm:
2. npm config set @reflexautomation:registry "https://git.bqa-solutions.nl/api/packages/reflex/npm/" --location=user
3. npm config set "//git.bqa-solutions.nl/api/packages/reflex/npm/:_authToken" "YOUR_DEPLOY_TOKEN" --location=user
4. npm install -g @reflexautomation/reflex-cli
5. Start or reuse a session:
6. reflex browser start
7. Default to auto-session mode for normal agent runs:
8. do not pass --session on follow-up commands
9. example: reflex browser open https://example.com
10. Use explicit --session only for deterministic override:
11. example: reflex browser open https://example.com --session <sessionId>
12. End with reflex browser session-kill in auto-session mode.
13. if you used an explicit session id, use reflex browser session-kill --session <sessionId> (or reflex browser session-kill <sessionId>)

Use the CLI itself as the command/protocol source of truth:

• reflex browser --help
• reflex browser help --json

Agent Defaults

• Do not pass --session by habit after start; normal flows should stay in scoped auto-session mode.
• Start on the target page, not on broad capability audits; do not inventory libraries or call repeated help commands unless a concrete next step needs exact syntax.
• Prefer summary first and fine-tune it (-i -c, then -s, -C, -d) for selector discovery and recovery before trying eval or html; treat html as last-resort evidence, not normal recovery. Start with count 20; increase only when the page has many repeated items.
• Use reflex browser help --json for exact command/response/schema details instead of duplicating those rules here.

Discovery Before Capability Audits (Required)

1. For normal tasks, start with the target page: start -> open -> summary.
2. Do not begin with broad audits such as reflex lua libs, repeated help calls, external doc hunts, or speculative output-format work.
3. Check exact command/library help only when you have a concrete next step that requires it.
4. Once a browser command succeeds, continue the task instead of re-checking availability.

Agent Availability And Recovery (Required)

1. Before assuming browser commands are broken, verify the local agent is available.
2. If a browser command fails with a transport/connect error, use this recovery order:
3. reflex agent status
4. if not running, reflex agent start
5. if the agent jar is missing, reflex agent download
6. if Java is missing or incompatible, reflex agent runtime install
7. retry the original browser command after recovery
8. Prefer the CLI's own guidance text when it suggests reflex agent start or reflex agent download.
9. For local development tasks, the AI agent may run reflex agent ... commands directly instead of only telling the human what to do.
10. If the environment is clearly non-local, remote, or permission-sensitive, explain the exact reflex agent ... command the human should run.
11. Do not start multiple background agents on different ports unless the task explicitly requires it.

Recommended recovery flow:

reflex agent status
reflex agent start
reflex agent download
reflex agent runtime install

Command Lifecycle (Required)

1. Send actions as separate CLI invocations.
2. Do not chain browser commands with &&, long shell pipelines, or opaque wrappers.
3. Keep one logical session context for the task (auto-session by default).
4. Default rule: omit --session on commands unless explicit override is required.
5. Execute sequentially: run one command, inspect response, then run the next.
6. On transport failure, recover the local agent first, then rerun the command as a new invocation.
7. Cleanup with reflex browser session-kill when done unless the user explicitly asks to keep the session open.

Response Handling (Required)

1. Always capture the full JSON response first, then parse fields from that captured payload.
2. Do not pipe command output directly into filtering (jq | head) as the only observable output; this hides critical context.
3. Prefer in-memory capture over temp files; if temp files are needed, use ephemeral files and clean them up.
4. Treat envelope fields (ok, action, session) as source-of-truth; mirrored duplicates may be compacted out of response.
5. For exact field names such as summary.targets[], use reflex browser help --json as the contract reference.

Parser-First Summary Contract (Required)

1. For selector discovery that feeds agent logic, use summary first.
2. Parse response.data.summary.targets[] as the primary selector feed:
3. selector
4. selectorType
5. confidence
6. reason
7. optional steering:
8. status
9. hint
10. fallback
11. ref — short-lived element ref (@r1, @r2, …); prefer over selector when present
12. Treat summary.version + summary.targets[] as the stable parser contract; avoid parsing deep fields from full summary output by default.
13. Do not parse elements/actions/candidates-style fields from summary output.
14. Keep extraction flow deterministic:
15. summary for candidate selection
16. targeted action (click/text/attribute/etc.)
17. re-run summary only after DOM-changing actions when needed

Summary Count And Flags (Required)

The positional count argument controls how many targets (ranked actionable elements) and snapshot lines are returned. It does not control how much of the DOM is scanned — the agent always scans up to 2000 nodes regardless.

• Default: 20. Hard max: 100.
• Start with summary 20 -i -c. This is enough for most pages.
• If you need more coverage, refine with flags first (-s, -C, -d), not by increasing the count.
• Only increase the count when the page has many similar actionable items (e.g., a product listing with 50+ links) and you need targets for more of them.
• Do not use high counts like summary 80 as a general "show me everything" — it adds low-confidence targets and more snapshot noise without improving discovery quality.

Summary Refinement Ladder (Required)

When the first summary pass is weak, noisy, or incomplete, stay in summary mode and refine it before escalating:

1. Start with summary 20 -i -c for normal interactive discovery.
2. If the results are too broad, add -s "<container>" to scope discovery to the relevant region.
3. If the page relies on non-semantic clickable UI, add -C.
4. If the output is still noisy, tune depth (-d <n>) and scope (-s) instead of increasing count or switching tools.
5. Only increase count beyond 20 when you