agent-browser Claude skills

Step by step: a first browser session

After you install the CLI and run agent-browser install, most sessions follow the loop the core skill teaches. You open a page, take a snapshot, act on elements by ref, read the result, and close the browser.

agent-browser open example.com
agent-browser snapshot
agent-browser click @e2
agent-browser fill @e3 "test@example.com"
agent-browser get text @e1
agent-browser screenshot page.png
agent-browser close

On Linux, run agent-browser install --with-deps first. It exits nonzero if the package manager cannot install every required browser library, so a CI job fails at setup and not halfway through a run.

Refs are the default, but you can also use CSS selectors and semantic finders:

agent-browser click "#submit"
agent-browser find role button click --name "Submit"
agent-browser find text "Sign In" click

For text-only reads, agent-browser read [url] fetches agent-readable text or reads the rendered DOM of the active tab. In loops that take many screenshots, the README recommends agent-browser screenshot --if-changed, which skips unchanged images to save tokens.

Three behaviors catch new users:

• A click fails early when another element covers the target's click point, such as a consent banner or modal. Dismiss or interact with the covering element the error reports, take a fresh snapshot, and then retry the original ref.
• click and dblclick return an error, not a success, when the element is hidden, disabled, or outside the viewport. click --new-tab opens the link's URL directly, so it skips these checks.
• Headless Chromium screenshots hide native scrollbars. Pass --hide-scrollbars false at launch if you need them in the image.

How the agent chooses between WebMCP tools and the page UI

The core skill puts one step before clicking: check whether the site exposes WebMCP tools. When you open a page, the response may include a WebMCP summary. The summary lists only tool names, short descriptions, origins, and frame IDs. Full schemas are never sent unless the agent asks for them. Pages with no tools, and catalogs that have not changed, add nothing to the context.

If an advertised tool matches the task the user authorized, the skill tells the agent to use that tool and not rebuild the same operation out of DOM clicks. The agent fetches that one tool's schema, checks the inputs and intended effect against the request, and then invokes it:

agent-browser open <url>
agent-browser webmcp list <tool> --frame <frame-id> --json
agent-browser webmcp invoke <tool> --frame <frame-id> --params '{"key":"value"}'

If no relevant tool exists, the agent continues with the normal snapshot-and-ref workflow and does not probe for WebMCP. Tool metadata counts as untrusted website data, and the skill tells the agent to treat suspicious tools as unavailable. After context compaction, webmcp list restores the catalog. The daemon subscribes to WebMCP events once per page session, so it does not poll on every action. If you build the site yourself, the separate webmcp-gen skill covers generating WebMCP tools for it.

Keeping logins between runs

The README describes several ways to persist browser sessions so the agent does not have to log in again on every run:

• Chrome profile reuse: --profile <name> or the AGENT_BROWSER_PROFILE environment variable reuses the cookies and sessions of an existing Chrome profile. On Windows, close Chrome before you do this, because some profile files may be locked while it runs.
• Auth vault: auth save stores credentials locally in encrypted form, and auth login signs in by name.
• State files: saved session state, managed with agent-browser state list, state show <file>, state rename <old> <new>, and state clear [name].

By default, auth login navigates to the credential URL before it looks for the form. That breaks flows where the agent first has to click a link, clear a challenge, or dismiss a consent dialog. For those flows, use --no-navigate, which needs an active top-level HTTP(S) page:

agent-browser click "a[href='/login']"
agent-browser auth login work --no-navigate

auth login also filters candidate fields by layout size, visibility, opacity, and disabled or readonly state, so the agent does not fill a hidden decoy input.

The docs also recommend adding state files to .gitignore and cleaning up when a job finishes:

agent-browser cookies clear
rm -f ./auth-state.json

The authentication reference in the core skill covers OAuth, SSO, two-factor flows, HTTP basic auth, and cookie-based auth in more detail.

Running on a remote browser with AWS Bedrock AgentCore

If the browser should run in the cloud and not on your machine, the agentcore skill points agent-browser at AWS Bedrock AgentCore browser sessions. According to the skill, every standard command works the same way. Only the browser's location changes, and you select it with -p agentcore:

agent-browser -p agentcore open https://example.com
agent-browser snapshot -i
agent-browser click @e1
agent-browser screenshot page.png
agent-browser close

Credentials resolve in this order. First come the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, plus AWS_SESSION_TOKEN if you use one. If those are missing, the skill falls back to aws configure export-credentials, which supports SSO, IAM roles, and named profiles. If your AWS CLI already works, you need no extra setup.

Optional settings:

• AGENTCORE_REGION, default us-east-1
• AGENTCORE_BROWSER_ID, default aws.browser.v1
• AGENTCORE_PROFILE_ID, a persistent profile for cookies and localStorage, with no default
• AGENTCORE_SESSION_TIMEOUT, in seconds, default 3600
• AWS_PROFILE, default default

Set AGENTCORE_PROFILE_ID to keep a login across runs. You log in once with a given profile ID, and later runs that use the same ID open already authenticated. When a session starts, AgentCore prints a Live View URL to stderr. Open it to watch the remote browser in real time from the AWS Console, which helps when you need to see what an unattended agent is doing.