browser

name	browser
description	Drive a browser via CDP — navigate, click, type, screenshot. Profiles persist login state across sessions, so agents log in once and stay authenticated. Triggers on: 'automate a website', 'browser automation', 'click', 'screenshot', 'scrape', 'log in', 'fill form'.
argument-hint	[profiles|start|refs|click|type|screenshot|done]
allowed-tools	Bash(agents browser*), Bash(browser*)
user-invocable	true

Browser

Control a real browser via CDP. Profiles persist login state, so agents log in once and stay authenticated. Screenshots auto-resize to save tokens.

browser is shorthand for agents browser — use the short form.

Task binding

Every action command targets a task. Bind the task once per shell, then drop the flag:

export AGENTS_BROWSER_TASK=$(browser start --profile work)
browser refs
browser click 42
browser screenshot

start writes the resolved task name (e.g. swift-crab-falcon-a3f92b1c) to stdout; human commentary goes to stderr — $(...) capture stays clean.

For per-call overrides, pass --task <name>. Env vars are per-process, so parallel agents in different shells never collide.

"I need to automate a site that blocks bots"

Use your real browser. Same fingerprint, same IP, nothing to detect:

browser profiles create work --browser chrome
export AGENTS_BROWSER_TASK=$(browser start --profile work --url https://linkedin.com)
browser refs
browser click 5

"I don't want to log in every time"

Log in once to a profile — the session persists. Every future task is already authenticated:

browser profiles create social --browser chrome
export AGENTS_BROWSER_TASK=$(browser start --profile social)
# Log in manually or via automation
browser done

# Next time — already logged in
export AGENTS_BROWSER_TASK=$(browser start --profile social --url https://twitter.com)

"I have multiple accounts and want to keep them separate"

Profiles are identities. Create one per account group:

browser profiles create social --browser chrome    # Twitter, LinkedIn
browser profiles create email --browser chrome     # Gmail, work email
browser profiles create finance --browser chrome   # Banking, trading

An agent using social can't see your finance cookies.

"I'm running multiple agents and they keep stepping on each other"

Each agent gets its own task. Tasks share the window but own separate tabs:

# Agent 1 — research
export AGENTS_BROWSER_TASK=$(browser start --profile work --url https://arxiv.org)
browser tabs

# Agent 2 (different shell) — monitoring
export AGENTS_BROWSER_TASK=$(browser start --profile work --url https://dashboards.example.com)
browser tabs   # only sees its own tabs

# Completing one doesn't affect the other
browser done   # closes only this agent's tabs

"I need to give an agent login credentials safely"

Cookie persistence comes first. A profile keeps its login cookies across sessions, so the goal is: log in once (by hand or agent-driven), and the profile stays authenticated — no credential handling on the hot path. Check state before assuming a re-login is needed:

browser profiles logins          # per profile: SERVICE | ACCOUNT | CREDS

ACCOUNT is the signed-in identity (from saved logins, read plaintext — no decryption); CREDS shows whether the profile's secrets bundle holds login creds for that service.

When a session lapses, drive the login with the credential resolved inside the browser layer so the plaintext never crosses stdout or your transcript. Store creds in the profile's bundle under the <SERVICE>_USERNAME / <SERVICE>_PASSWORD convention:

browser profiles create acme --browser comet --secrets acme-login
agents secrets add acme-login GITHUB_USERNAME
agents secrets add acme-login GITHUB_PASSWORD

# Log in — the agent drives the form and handles 2FA/selectors adaptively:
export AGENTS_BROWSER_TASK=$(browser start --profile acme --url https://github.com/login)
browser refs                                              # find the field refs
browser type <user-ref> --secret acme-login/GITHUB_USERNAME   # value never printed
browser type <pass-ref> --secret acme-login/GITHUB_PASSWORD
browser click <submit-ref>
browser screenshot                                        # inspect: 2FA? captcha? done?

If a 2FA/OTP or "unusual activity" checkpoint appears, the agent screenshots it and asks the human (or reads the OTP from a connected mailbox) — the CLI never auto-solves it. For scripts that genuinely need the raw value, agents secrets get <bundle> <KEY> prints one value (audited) — but prefer type --secret so nothing lands in the transcript.

Note: --secrets also injects the bundle as env vars into the browser process at launch (useful for extensions/CDP tooling that read env) — that is separate from web login, which needs the form-fill flow above.

"I want to use a cloud browser instead of local"

Connect to BrowserBase, Steel, or any CDP service:

browser profiles create cloud --browser chrome \
  --endpoint "wss://connect.browserbase.com?apiKey=..."

"I need to automate an Electron app"

Three flags work together for Electron desktop apps:

browser profiles create canva --browser custom \
  --binary "/Applications/Canva.app/Contents/MacOS/Canva" \
  --electron \
  --target-filter "url:https://www.canva.com/"

• --browser custom plus --binary tells the launcher how to start the app with --remote-debugging-port.
• --electron switches the runtime into single-window mode: tabs are never created with Target.createTarget (most production Electron apps reject it); navigation reuses the existing window.
• --target-filter picks the visible WebContents. Electron apps frequently expose several type: page CDP targets — background services, OAuth windows, and file:// shells — and the first one CDP returns is almost never the UI. Use url:<substring> or title:<substring>.

Without --target-filter, a skip-invisible heuristic excludes about:blank, file://, and URLs matching _desktop-background-service / _internal / _background. That covers most apps; use the filter for the ones it doesn't.

Common workflows

Navigate and interact

export AGENTS_BROWSER_TASK=$(browser start --profile work --url https://example.com)
browser refs                              # Get clickable elements
browser click 3                           # Click element ref 3
browser type 5 --text "search query"      # Type into element ref 5
browser press Enter                       # Press Enter key
browser screenshot                        # Take screenshot (auto-saved)
browser done                              # Close task's tabs

Manage tabs

browser tab add --url https://github.com  # Open new tab (becomes current)
browser tab focus github                  # Switch by URL substring
browser tabs                              # List all tabs
browser tab close                         # Close all tabs

Check status

browser status                            # Show all profiles and tasks
browser tasks                             # List just tasks

Quick reference

All action commands read the task from $AGENTS_BROWSER_TASK unless --task <name> is passed.

Task	Command
Create profile	browser profiles create <name> --browser chrome
Start task	browser start --profile <name> [--url <url>]
Navigate	browser navigate --url <url>
Get elements	browser refs
Click	browser click <ref>
Type	browser type <ref> --text "text"
Press key	browser press Enter
Hover	browser hover <ref>
Scroll	browser scroll --dx 0 --dy 1000 (negatives scroll up/left)
Screenshot	browser screenshot
Evaluate JS	browser evaluate --expression "document.title" (or --file ./script.js)
New tab	browser tab add --url <url>
Switch tab	browser tab focus <hint>
Complete task	browser done
Status	browser status