Menú
Browser automation CLI for the Cheatcode coding agent. Use when the user needs to interact with websites, take screenshots, fill forms, click elements, navigate pages, or automate any browser task.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
| name | browser-use |
| description | Browser automation CLI for the Cheatcode coding agent. Use when the user needs to interact with websites, take screenshots, fill forms, click elements, navigate pages, or automate any browser task. |
| category | Builder & Apps |
| tags | browser, automation, screenshots, qa |
| compatibility | Requires the preinstalled cheatcode-browser CLI and headed Chromium runtime. |
| allowed-tools | shell_exec browser_open browser_act browser_observe browser_extract browser_screenshot |
Use cheatcode-browser for all browser automation — navigating pages, interacting with elements, taking screenshots, extracting data, and testing web apps.
The --cloud flag spins up a remote cloud browser instance, so there is no need to install or run a browser locally in the sandbox.
cheatcode-browser --cloud <action> [args...] [flags]
Run every cheatcode-browser command with shell_exec and pass the command as an argv array.
Do not use shell_terminal for browser commands: it is reserved for persistent project work and
attaches a project workspace. Browser-only work must remain projectless.
For example, this documented shell command:
cheatcode-browser --cloud open https://example.com
must be sent to shell_exec as:
{"command":["cheatcode-browser","--cloud","open","https://example.com"]}
Issue sequential shell_exec calls when commands depend on earlier output. Do not turn &&
examples in this document into shell_terminal calls. If cheatcode-browser is unavailable,
fall back directly to the native browser_open, browser_observe, browser_act,
browser_extract, and browser_screenshot tools without creating a project.
CRITICAL: Before issuing any browser commands, stop and reason about the task. Do not jump straight into commands. Browser automation fails when you act mechanically without understanding the website.
What is the user actually trying to accomplish? If they say "find the cheapest flight from SF to NYC," the goal isn't "click a search box" — it's navigating an airline/travel site's full search flow: entering origin, destination, dates, hitting search, reading results, and comparing prices. Plan the full sequence before starting.
Think about what kind of website you're working with and how it's likely organized:
Knowing the pattern tells you what to expect after each action.
Every action changes the page. Before you click or submit, ask yourself:
Always re-snapshot after a state change to confirm you're where you expect.
Real websites have friction. Before interacting with main content, check for and dismiss:
request_user_control for these)If you see these in a snapshot, handle them first.
After each major step, confirm the page state before continuing. Don't chain 5 actions blindly — one failed click silently breaks everything after it. The pattern is: act → verify (snapshot) → act → verify.
For standard web pages, use the snapshot → use refs → re-snapshot loop:
cheatcode-browser --cloud open https://example.com/form
cheatcode-browser --cloud snapshot -i
# Output: interactive element refs like @e1 [input "Email"], @e2 [input "Password"], @e3 [button "Submit"]
cheatcode-browser --cloud fill @e1 "user@example.com"
cheatcode-browser --cloud fill @e2 "password123"
cheatcode-browser --cloud click @e3
cheatcode-browser --cloud snapshot -i
CRITICAL: When you have refs from a snapshot, ALWAYS use them. Do NOT use find, CSS selectors, or any other locator strategy when you already have @e refs — refs are the fastest and most reliable way to target elements. Only use find when you need to locate elements without a prior snapshot.
After any navigation or DOM change (clicking a link, submitting a form, opening a modal), always re-snapshot to get fresh refs.
For tasks that are not DOM-based or where the DOM is hard to work with — canvas elements, maps, games, complex visual UIs, iframes, visual verification — use the screenshot -> observe -> coordinate loop:
cheatcode-browser --cloud screenshot --annotate
# Observe the screenshot to identify target coordinates
cheatcode-browser --cloud mouse click 150 300
cheatcode-browser --cloud screenshot
# Verify the result
Available coordinate actions:
cheatcode-browser --cloud mouse click <x> <y> # Click at coordinates
cheatcode-browser --cloud mouse move <x> <y> # Move cursor
cheatcode-browser --cloud mouse dblclick <x> <y> # Double-click
cheatcode-browser --cloud mouse scroll <x> <y> <scroll_y> # Scroll at position
cheatcode-browser --cloud mouse down left # Press mouse button
cheatcode-browser --cloud mouse up left # Release mouse button
cheatcode-browser --cloud mouse wheel 100 # Scroll wheel
cheatcode-browser --cloud keyboard type "some text" # Type at current focus
cheatcode-browser --cloud press Enter # Press a key
When to use coordinates vs DOM:
click, fill, snapshot) first — they are more reliable.<canvas>, WebGL, or complex SVG that snapshots can't expresscheatcode-browser --cloud open <url> # Navigate to URL (aliases: goto, navigate)
cheatcode-browser --cloud close # Close browser (aliases: quit, exit)
cheatcode-browser --cloud tab # List tabs
cheatcode-browser --cloud tab new [url] # New tab (optionally with URL)
cheatcode-browser --cloud tab <n> # Switch to tab n
cheatcode-browser --cloud tab close [n] # Close tab (current if n omitted)
Multi-tab workflows: Always run cheatcode-browser --cloud tab first to list tabs and check which tab is currently active before switching or interacting. Tab indices can change after opening or closing tabs, so never assume a tab index — always list tabs to confirm.
cheatcode-browser --cloud snapshot # Full accessibility tree
cheatcode-browser --cloud snapshot -i # Interactive elements only (recommended)
cheatcode-browser --cloud snapshot -c # Compact output
cheatcode-browser --cloud snapshot -d 3 # Limit depth to 3
cheatcode-browser --cloud snapshot -s "#main" # Scope to CSS selector
cheatcode-browser --cloud screenshot # Capture viewport
cheatcode-browser --cloud screenshot --full # Full page screenshot
cheatcode-browser --cloud screenshot --annotate # Screenshot with numbered element labels
Screenshot path: Do NOT save screenshots to /tmp. By default, screenshots are saved to the working directory (/home/user/computer). Only specify a path if the user explicitly asks to save to a specific location.
cheatcode-browser --cloud click <selector> # Click element
cheatcode-browser --cloud click <selector> --new-tab # Click and open in new tab
cheatcode-browser --cloud dblclick <selector> # Double-click
cheatcode-browser --cloud fill <selector> <text> # Clear and type
cheatcode-browser --cloud type <selector> <text> # Type without clearing
cheatcode-browser --cloud select <selector> <value> # Select dropdown option
cheatcode-browser --cloud check <selector> # Check checkbox
cheatcode-browser --cloud uncheck <selector> # Uncheck checkbox
cheatcode-browser --cloud hover <selector> # Hover element
cheatcode-browser --cloud focus <selector> # Focus element
cheatcode-browser --cloud scroll down 500 # Scroll page
cheatcode-browser --cloud scroll down 500 --selector ".container" # Scroll within element
cheatcode-browser --cloud scrollintoview <selector> # Scroll element into view
cheatcode-browser --cloud drag <selector> <targetSelector> # Drag and drop
cheatcode-browser --cloud upload <selector> <path> # Upload file
cheatcode-browser --cloud download <selector> [path] # Click element to trigger download
cheatcode-browser --cloud press Enter # Press key
cheatcode-browser --cloud press Tab # Press Tab key
cheatcode-browser --cloud press Control+a # Key combination (Ctrl+A)
cheatcode-browser --cloud press Control+c # Copy
cheatcode-browser --cloud press Control+v # Paste
cheatcode-browser --cloud press Escape # Escape
cheatcode-browser --cloud keyboard type "some text" # Type at current focus
cheatcode-browser --cloud keyboard inserttext "text" # Insert without key events
Note: Meta/Command/Cmd keys are automatically mapped to Control inside the sandbox (Linux environment). Use Control+ for key combinations.
cheatcode-browser --cloud get text @e1 # Get element text
cheatcode-browser --cloud get html @e1 # Get innerHTML
cheatcode-browser --cloud get value @e1 # Get input value
cheatcode-browser --cloud get attr @e1 href # Get attribute
cheatcode-browser --cloud get title # Get page title
cheatcode-browser --cloud get url # Get current URL
cheatcode-browser --cloud get cdp-url # Get CDP WebSocket URL
cheatcode-browser --cloud get count ".item" # Count matching elements
cheatcode-browser --cloud get box @e1 # Get bounding box
cheatcode-browser --cloud get styles @e1 # Get computed styles
cheatcode-browser --cloud wait @e1 # Wait for element
cheatcode-browser --cloud wait 2000 # Wait milliseconds
cheatcode-browser --cloud wait --text "Success" # Wait for text (or -t)
cheatcode-browser --cloud wait --url "**/dashboard" # Wait for URL pattern (or -u)
cheatcode-browser --cloud wait --load networkidle # Wait for network idle (or -l)
cheatcode-browser --cloud wait --fn "window.ready" # Wait for JS condition (or -f)
cheatcode-browser --cloud wait --download [path] # Wait for any download to complete
Use find only when you haven't taken a snapshot or need to locate elements without refs. If you have @e refs from a snapshot, always use those instead.
cheatcode-browser --cloud find role button click --name "Submit"
cheatcode-browser --cloud find text "Sign In" click
cheatcode-browser --cloud find text "Sign In" click --exact # Exact match only
cheatcode-browser --cloud find label "Email" fill "user@test.com"
cheatcode-browser --cloud find placeholder "Search Amazon" type "query"
cheatcode-browser --cloud find alt "Logo" click
cheatcode-browser --cloud find title "Close" click
cheatcode-browser --cloud find testid "submit-btn" click
cheatcode-browser --cloud find first ".item" click
cheatcode-browser --cloud find last ".item" click
cheatcode-browser --cloud find nth 2 "a" hover
IMPORTANT: eval runs code as a top-level expression. Do NOT use return — it causes SyntaxError: Illegal return statement. Just write the expression directly.
cheatcode-browser --cloud eval 'document.title'
cheatcode-browser --cloud eval 'document.querySelectorAll("img").length'
cheatcode-browser --cloud eval 'JSON.stringify([...document.querySelectorAll("a")].map(a => a.href))'
cheatcode-browser --cloud get_live_preview_link # Get interactive live preview URL
cheatcode-browser --cloud request_user_control --title "Title" --description "Instructions" # Hand control to user
cheatcode-browser --cloud pdf /tmp/page.pdf # Save as PDF
cheatcode-browser --cloud help # Show CLI help (also: --help, -h)
Every Bash call is expensive. Minimize round-trips aggressively. This is the #1 factor in browser automation speed.
Use snapshot -i → interact → re-snapshot. This is the fastest, most reliable approach. Only fall back to screenshots when the DOM can't express what you need.
&&If you don't need intermediate output, chain multiple commands in a single Bash call:
cheatcode-browser --cloud open https://example.com && cheatcode-browser --cloud snapshot -i
cheatcode-browser --cloud fill @e1 "user@example.com" && cheatcode-browser --cloud fill @e2 "password" && cheatcode-browser --cloud click @e3 && cheatcode-browser --cloud snapshot -i
eval for bulk operationsA single eval replaces many individual calls. Use it for scraping, form filling, bulk interactions, and data extraction. Never use return — just write the expression.
cheatcode-browser --cloud eval 'JSON.stringify(Array.from(document.querySelectorAll("tr")).map(r => r.innerText))'
cheatcode-browser --cloud eval 'document.querySelectorAll("input[type=checkbox]").forEach(cb => { if (!cb.checked) cb.click() }); "done"'
cheatcode-browser --cloud eval 'JSON.stringify({ title: document.title, links: Array.from(document.querySelectorAll("a")).map(a => ({ text: a.innerText, href: a.href })) })'
snapshot -i over snapshot — interactive-only is smaller and faster.snapshot over screenshot — text is fast, images are slow. Only use screenshots when you need visual information the DOM can't provide.When a task requires human interaction — typically logging in, solving a CAPTCHA, or confirming a sensitive action — hand control to the user:
cheatcode-browser --cloud request_user_control --title "Log in to GitHub" --description "Please sign in with your credentials. Click 'Return control' when done."
This halts the current agent run and shows the user a prompt with your title and description. The user interacts with the browser directly, then clicks Return control when finished. You may continue working after the user resumes.
When to use:
Get an interactive browser preview URL that you can share with the user so they can see and interact with the current browser session directly:
cheatcode-browser --cloud get_live_preview_link
Returns a JSON object with livePreviewUrl — a URL the user can open to view and interact with the live browser session.
When to use:
Always send the link via sendMessage so the user can tap it directly.
--annotate on screenshots to get numbered labels on interactive elements — useful for finding coordinates or verifying which element is which.Create or update project-local Cheatcode skills for direct backend routes, local workflows, or non-Composio external APIs. This is the default skill authoring path.
Inspect and manage globally enabled Cheatcode tools and integrations.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.
Uses the user's connected Gmail, GitHub, Notion, Google Workspace, Slack, and other supported accounts for explicit on-demand actions. Use when the user asks Cheatcode to read, search, create, or update something in a connected service.
Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.
Use this skill when you need to read a file whose content is NOT already in your context — you only know its path. This skill is a router: it tells you which tool to use for each file type (pdf, docx, xlsx, csv, json, images, archives, ebooks) so you read the right amount the right way instead of blindly running cat on a binary. Do NOT use this skill if the file content is already visible in your context — you already have it.