chromux-work

chromux-work

Use this workflow for browser tasks that need more than a single page check: research, feed/search collection, logged-in site inspection, cross-page verification, or parallel browser work. For command syntax, use the chromux skill and chromux help.

This workflow applies to macOS, Linux, and native Windows. On Windows, prefer PowerShell examples when installing or smoke-testing the CLI; browser work still uses the same chromux command surface.

Contract

• Use chromux, not Playwright/Puppeteer, unless the user explicitly chooses a different tool.
• Start from a real chromux profile. Prefer an existing logged-in profile for user-owned sites.
• Same profile, different sessions: subagents share the selected profile and use unique session names. Concurrent cold starts are coordinated by chromux, but pre-launching the profile is still useful when you want faster first work.
• Recon first. Do not fan out before checking login state, page shape, blockers, site hints, and whether the task is parallel-safe.
• For crawling, use CHROMUX_MODE=crawl and a small worker-tab pool instead of one tab per URL. Default recommendation: 3 to 5 worker sessions per profile.
• For plain URL batches, prefer chromux batch --file urls.txt --workers N --retries N --host-backoff-ms MS instead of asking subagents to hand-roll open/run loops.
• Treat batch as a browser execution primitive, not a domain-specific extractor. Use it for URL load verification and simple page metadata; use checked-in per-site extractors when a task needs structured records.
• For UI work, do not treat open or an action response as proof. Use snapshot, wait-for-text, wait-for-selector, run, or screenshot to prove the resulting state. After an in-page action, snapshot --diff is the cheapest proof: it prints only what changed since your previous snapshot (action responses include it as the next command).
• Minimize round-trips: bundle a known multi-step sequence (navigate, click, fill, wait, read back) into a single chromux run call instead of issuing many separate click/fill/snapshot commands. Each separate command is a full agent round-trip; one run with page(...)/js(...) is far faster and is the main reason a single-call browser flow feels fast.
• Use chromux run --receipt PATH for important QA or mutation-adjacent flows so the final report has redacted timing, state, and failure-kind evidence.
• Observe with snapshot before reaching for screenshot. Use snapshot --interactive when you only need actionable elements (buttons, links, inputs) — it returns a much smaller payload. Reserve screenshot for visual verification a text snapshot cannot capture.
• For canvas, range sliders, drag/drop, and other visual-only surfaces, read chromux skill visual. Use measured screenshot coordinates with hover/click/drag; never assume screenshot pixels equal CSS units.
• Default cross-origin frame recon is origin-only geometry. Use open --oopif only when the task requires namespaced child refs or reliable child text actions, and refresh the snapshot after child navigation or detach.
• For parent-controlled shutdown, use chromux pause <profile> to reject new browser work, then chromux resume <profile> before the next wave.
• Keep work read-only unless the user explicitly asked to mutate state.
• Close every session you open. Do not suppress chromux close output unless the user explicitly asked for silence. chromux closes tabs idle for 30 minutes and shuts down an auto-launched browser 15 minutes after its last session ends, but that is a backstop for crashes and interruptions, not a reason to leave tabs open — everything you leave behind keeps a renderer alive until the timer fires.
• After close, review any knowledgeHint. Update ~/.chromux/skills/<host>/*.md when this run revealed durable public site behavior or stale/wrong notes.
• Treat a learnNext field on any open or close response as a required checkpoint, not a suggestion. It appears only when the host has no durable knowledge yet or one of its files has gone stale, and it names the oldest file plus the exact chromux note / chromux script save commands. Do not end the task with an unaddressed learnNext: either save what this run proved, or state why nothing durable was learned. This is the write half of the learning loop — skipping it is why a host stays expensive on every future visit.
• If a hint turned out to be wrong, edit that file and remove the wrong claim. note --add appends, so correcting with it leaves the wrong claim and its rebuttal side by side and the next agent believes whichever it reads first. Hint headers and learnNext both carry the real path; open it with your normal file tools. Writing a new note in a sibling file does not clear the stale one.
• When a derived flow (selectors, waits, extraction) worked and is likely to be repeated, save it as a replay script: chromux script save <host>/<name> --file flow.js. Future runs on that host see it in the open response and replay it with chromux run <session> --script <host>/<name> instead of re-deriving the flow. If a replay fails, fix the script against a fresh snapshot and save it again. For structured extraction, pair the script with --schema so results that drift from the expected shape fail loudly.