/browser-tools

name: browser-tools
license: MIT
compatibility: "Claude Code 2.1.220+. Requires network access."
description: Security wrapper over the upstream agent-browser skill, adding URL blocklisting, rate limiting, robots.txt enforcement, and scraping guardrails. Use when automating browser workflows that need safety limits.
tags: [browser, automation, security, rate-limiting, scraping-ethics]
context: fork
agent: web-research-analyst
version: 5.0.0
author: OrchestKit
user-invocable: false
complexity: medium
persuasion-type: discipline
metadata:
  category: mcp-enhancement
  upstream-skill: agent-browser
  upstream-version-tested: "0.33.1"
allowed-tools:
  - Read
  - Glob
  - Grep
  - WebFetch
  - WebSearch

Browser Tools — Security Wrapper

OrchestKit security wrapper for `agent-browser`. **For command reference and usage patterns, use the upstream `agent-browser` skill directly.** This skill adds safety guardrails only.

> **Command docs**: Refer to the upstream `agent-browser` skill for the full command reference (50+ commands: interaction, wait, capture, extraction, storage, semantic locators, tabs, debug, mobile, network, cookies, state, vault).

Upstream coverage (do not restate)

These topics belong to the vendor. Read them at the source; do not copy them back into this skill.

| Topic | First-party source | |-------|--------------------| | CLI command reference, snapshot and ref loop, waits, auth options, eval, config file | `agent-browser` skill · https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md | | Electron and desktop-app automation over CDP (`connect`, `--cdp`, webviews, tabs) | https://github.com/vercel-labs/agent-browser/blob/main/skill-data/electron/SKILL.md | | Slack workspace navigation and extraction recipes | https://github.com/vercel-labs/agent-browser/blob/main/skill-data/slack/SKILL.md | | Running headless in a Vercel Sandbox microVM (deps, snapshots, cron) | `vercel:vercel-sandbox` skill · https://github.com/vercel-labs/agent-browser/blob/main/skill-data/vercel-sandbox/SKILL.md | | Exploratory QA sweep with repro evidence (issue taxonomy, report template) | `dogfood` skill · https://github.com/vercel-labs/agent-browser/blob/main/skill-data/dogfood/SKILL.md | | Named `.localhost` dev URLs | `ork:portless` skill · https://github.com/vercel-labs/portless |

**Our delta over all of the above**: `references/ork-delta.md`, covering where the safety hook does and does not apply, the shared rate-limit budget, and the local-URL policy.

Decision Tree

# Fallback decision tree for web content
# 1. Try WebFetch first (fast, no browser overhead)
# 2. If empty/partial -> Try Tavily extract/crawl
# 3. If SPA or interactive -> use agent-browser
# 4. If login required -> authentication flow + state save
# 5. If dynamic -> wait @element or wait --text

Local Dev URLs

Use **Portless** (`npm i -g portless`) for stable local dev URLs instead of guessing ports. When Portless is running, navigate to `myapp.localhost` instead of `localhost:3000`. Our safety hook already allows `*.localhost` subdomains via `ORCHESTKIT_AGENT_BROWSER_ALLOW_LOCALHOST`.

# With Portless: stable, named URLs
agent-browser open "https://myapp.localhost"

# Without: fragile port guessing
agent-browser open "http://localhost:3000"  # which app is this?

New in 2026-04 to 2026-07 (agent-browser 0.23 to 0.33.1)

**Accessibility audits (0.33.0):**

• **`agent-browser a11y [url]`** — axe-core accessibility audit as a CLI command and a matching MCP tool. Filter by WCAG tag, scope to a selector, and get iframe-aware text or JSON results. The audit engine is embedded, so it runs offline and is CSP-safe (no third-party script injection into the page under test).
• Pairs with the `accessibility-specialist` agent and the `testing-e2e` axe-core guidance: use this for a fast pre-commit sweep, and Playwright + axe for assertions inside a suite.

**Session restore + read (0.30 → 0.31.1):**

• **`agent-browser read [url]` (0.30.0)** — agent-readable text extraction as a CLI command and MCP tool. URL reads prefer Markdown (try `.md` and nearby `llms.txt`), support outlines, filters, raw and JSON output, headers, and domain/output safeguards; omit the URL to read the rendered active-tab DOM with current browser state.
• **Restore workflow (0.31.0)** — `--restore` / `--restore-save`, restore-validation flags, worktree-scoped `session id` / `session info`, and `--namespace` give agent runs stable, isolated, auto-restored browser state without hand-managing state files. Session lifecycle hardened with daemon/browser compatibility checks and safer auto-save that won't overwrite good state after a failed restore.
• **`wait --url` glob patterns (0.30.1)** — `wait --url` / `waitforurl` honor globs like `**/dashboard` against the full active URL.
• **React renderer fix (0.31.1)** — the `react` commands now pick the react-dom renderer instead of hardcoding renderer id 1, fixing an empty tree read on Next.js 16.3 Turbopack.

**Sandbox helpers (0.29):**

• **`@agent-browser/sandbox`** — companion helper package for running agent-browser headless inside a Vercel Sandbox / eve ephemeral env (provisions Chrome + the native daemon for you, no host browser needed). Hook's URL/rate/robots checks still apply to whatever the sandboxed session navigates to.

**Built-in MCP server (0.28):**

• **`agent-browser --mcp`** — runs agent-browser as a Model Context Protocol server over stdio, exposing typed tools (open/snapshot/find/click/extract/...) with paginated capability discovery. Lets you wire browser automation MCP-native — directly into an MCP client — without going through the CLI Bash wrapper. Note: MCP-native sessions bypass the `agent-browser-safety` PreToolUse Bash hook (the hook only intercepts `agent-browser` Bash commands), so apply URL/rate/robots policy at the MCP-client layer when using this path.

**React introspection + perf observability (0.27):**

• **`react tree` /