* docs: fix 6 documentation issues (#303, #245, #186, #134, #61, #73)
Addresses six open documentation issues in a single pass:
- **#303** -- Add `npx agent-browser` usage across README, SKILL.md, docs site, and `--help` output for zero-install experience. Global install is recommended as the fastest path (native Rust CLI vs Node.js indirection with npx).
- **#245** -- Document Claude Code skill installation with `npx skills add vercel-labs/agent-browser`
- **#186** -- Split installation instructions into Global (recommended), Quick Start (npx), and Project (local dependency) sections with clear guidance on when to use each
- **#134** -- Add "Why agent-browser over playwright-mcp?" comparison table to README covering output format, element selection, protocol, sessions, performance, mobile, cloud, and streaming
- **#61** -- Add "Timeouts and Slow Pages" section to SKILL.md documenting the 60s default timeout, all `wait` variants, and guidance for slow websites
- **#73** -- Replace stale `cp node_modules/...` advice with `npx skills add`, add warning against copying SKILL.md manually, add "Session Management and Cleanup" section to SKILL.md
* remove section
* fix doc
Three fixes to eliminate duplicate entries:
1. Skip elements that only inherit cursor:pointer from a parent
(the parent element is captured instead)
2. Broaden dedup by extracting all quoted text from the ARIA tree,
not just ref names
3. Add accepted cursor elements to the dedup set to prevent
multiple DOM elements with the same text from duplicating
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Rebased and fixed implementation of PR #184 features on current main:
Session persistence:
- --session-name flag and AGENT_BROWSER_SESSION_NAME env var auto-save/restore
cookies and localStorage across browser restarts
- State files stored in ~/.agent-browser/sessions/ with owner-only permissions
- AES-256-GCM encryption via AGENT_BROWSER_ENCRYPTION_KEY env var
- Auto-expiration of old state files (AGENT_BROWSER_STATE_EXPIRE_DAYS, default 30)
State management commands:
- state list: list saved state files with metadata
- state show <file>: display state summary (cookies, origins, domains)
- state rename <old> <new>: rename state files
- state clear [name] [--all]: clear saved states
- state clean --older-than <days>: delete expired states
New --new-tab flag for click command:
- Opens link href in a new tab instead of navigating the current tab
Security hardening:
- Session name validation prevents path traversal (CLI + daemon)
- safeHeaderMerge prevents prototype pollution in header merging
- WebSocket stream server binds to 127.0.0.1 only
- State files written with 0o600 permissions
Fixes applied over the original PR:
- Use color.rs module instead of hardcoded ANSI escape codes
- Align CLI output field names with daemon response format
- Add CLI-level --session-name validation (not just daemon-side)
- Avoid adding "DOM" to tsconfig.json lib (use proper typing in evaluate)
- Keep version at 0.9.3 (matches current main)
- Centralize session name validation in daemon.ts helper
- Update all documentation (README, SKILL.md, docs site, --help output)
Co-authored-by: Chris Tate <chris@ctate.dev>
* cargo fmt
* fix: remove redundant `use libc` import (clippy::single_component_path_imports)
* fix: use `.first()` instead of `.get(0)` (clippy::get_first)
* fix: use `.copied()` instead of `.map(|s| *s)` (clippy::map_clone)
* fix: allow too_many_arguments on ensure_daemon (clippy::too_many_arguments)
* fix: use `then_some` instead of `then` with closure (clippy::unnecessary_lazy_evaluations)
* fix: use pattern match instead of redundant guard (clippy::redundant_guards)
* fix: use pattern match instead of redundant guard in commands.rs (clippy::redundant_guards)
* fix: use `contains()` instead of `iter().any()` for simple equality (clippy::manual_contains)
* Add changeset
The `-C`/`--cursor` flag was added to the CLI parser and snapshot
implementation in #374, but the Zod schema in protocol.ts was not
updated. This caused the `cursor` field to be silently stripped
during command validation, so cursor-interactive element detection
never ran.
Fixes#434
- Moves `skills/skill-creator/` to `.agents/skills/skill-creator/` so that only the project-specific `agent-browser` skill remains in `skills/`
- Non-agent-browser skills like `skill-creator` are generic tooling and don't belong alongside the product skill, which was confusing to users
Implemented Vercel Web Analytics for Next.js (App Router)
## Summary
Successfully installed and configured @vercel/analytics package for the Next.js documentation site.
## Changes Made
### 1. Installed Dependencies
- Installed `@vercel/analytics` package using pnpm
- Command executed: `pnpm install @vercel/analytics`
### 2. Modified Files
- **docs/src/app/layout.tsx**
- Added import: `import { Analytics } from "@vercel/analytics/next";`
- Added `<Analytics />` component inside the `<body>` tag, right after `<SpeedInsights />`
- Placement follows best practices for App Router projects
### 3. Updated Lock Files
- **docs/package.json** - Added @vercel/analytics to dependencies
- **docs/pnpm-lock.yaml** - Updated with new dependency tree
## Implementation Details
- This is an App Router project (uses `app/` directory structure)
- The Analytics component was added to the root layout file at `docs/src/app/layout.tsx`
- Followed the same pattern as the existing SpeedInsights component
- Preserved all existing code structure and formatting
## Verification
✅ Build completed successfully with no errors
✅ TypeScript compilation passed
✅ Modified file passes ESLint checks
✅ All 15 static pages generated correctly
## Notes
- The project already had @vercel/speed-insights installed, so the pattern for adding Analytics was consistent
- Pre-existing lint errors in mobile-nav-context.tsx and theme-toggle.tsx are unrelated to this change
- Lock files are properly updated and staged as per dependency changes
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
Successfully implemented Vercel Speed Insights for Next.js
## Changes Made
### 1. Installed @vercel/speed-insights package
- Used pnpm (the project's package manager) to install @vercel/speed-insights@1.3.1
- Updated package.json with the new dependency
- Updated pnpm-lock.yaml with the complete dependency tree
### 2. Integrated SpeedInsights component into root layout
- Modified: docs/src/app/layout.tsx
- Added import: `import { SpeedInsights } from "@vercel/speed-insights/next"`
- Added `<SpeedInsights />` component inside the `<body>` tag, placed after all other content
- This follows the recommended pattern for Next.js 13.5+ with App Router
## Implementation Details
The project uses:
- Next.js 16.1.1 with App Router
- TypeScript
- pnpm as the package manager
The SpeedInsights component was added to the root layout (app/layout.tsx) which is the correct approach for Next.js 13.5+ projects using the App Router. The component is placed at the end of the body tag to ensure it loads after the main content.
## Verification
✅ Build completed successfully - no compilation errors
✅ All changes staged with git including the lockfile
✅ Package installed and integrated correctly
Note: Pre-existing linter warnings in mobile-nav-context.tsx and theme-toggle.tsx were not introduced by these changes and remain unchanged.
## Files Modified
1. docs/package.json - Added @vercel/speed-insights dependency
2. docs/pnpm-lock.yaml - Updated with new package dependencies
3. docs/src/app/layout.tsx - Added SpeedInsights import and component
The implementation follows Vercel's official documentation and best practices for Next.js App Router applications.
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
Update `setupContextTracking` in `BrowserManager` to auto-switch `activePageIndex` to newly opened tabs and invalidate the CDP session accordingly. This mirrors what `newTab()` and `newWindow()` already do for explicitly created tabs, and aligns CLI behavior with how real browsers focus newly opened tabs.
Fixes#384
Summary
- The `--exact` flag on `find role`, `find label`, and `find placeholder` was accepted by the CLI but silently dropped by the server. The Zod validation schema, TypeScript types, and action handlers all lacked the `exact` field, so it was stripped before reaching Playwright's `getByRole`, `getByLabel`, and `getByPlaceholder` calls.
- Added `exact` to the schema, types, and handler for all three locators so the flag is forwarded to Playwright as intended.
- Added tests confirming `exact: true` survives protocol parsing for `getbyrole`, `getbylabel`, and `getbyplaceholder`.
Fixes#402
* feat: add --allow-file-access flag for file:// URL support
Adds the ability to open and interact with local files using file:// URLs.
This enables use cases like viewing local PDFs, testing local HTML files,
and allowing JavaScript to access other local files via XHR.
The flag adds Chromium's --allow-file-access-from-files and --allow-file-access
launch arguments. Only supported in Chromium browsers.
Fixes#345
* fix: add cli_allow_file_access tracking to prevent spurious warning
When --allow-file-access is set via AGENT_BROWSER_ALLOW_FILE_ACCESS env var
(not CLI), don't warn about the flag being ignored when daemon is already running.
* fix: only warn about ignored flags when explicitly passed via CLI
The warning about launch-time options being ignored (when daemon is
already running) was incorrectly shown when options were set via
environment variables like AGENT_BROWSER_EXECUTABLE_PATH, even when
no CLI flag was passed.
Now the warning only appears when flags are explicitly passed on the
command line, not when values come solely from environment variables.
Fixes#372
* feat: add cursor-interactive element detection in snapshots
Add -C/--cursor flag to snapshot command that detects clickable elements
that don't have proper ARIA roles but are interactive based on:
- cursor: pointer CSS style
- onclick attribute/handler
- tabindex attribute
This helps with modern web apps that use custom divs/spans as buttons.
Fixes#366
* fix: add cursor option to getSnapshot type signature
The warning about launch-time options being ignored (when daemon is
already running) was incorrectly shown when options were set via
environment variables like AGENT_BROWSER_EXECUTABLE_PATH, even when
no CLI flag was passed.
Now the warning only appears when flags are explicitly passed on the
command line, not when values come solely from environment variables.
Fixes#372
* Add base64 input for eval command
Adds -b/--base64 flag to decode script from base64, avoiding shell escaping issues for AI agents.
* Document base64 eval in SKILL.md
* fix: add retry logic for transient socket errors
Fixes race condition when rapidly closing and opening browser sessions.
The daemon has a 100ms shutdown delay, which caused the CLI to detect
stale daemons as "running" and fail with EAGAIN errors.
Changes:
- Add retry logic (5 attempts, exponential backoff) for transient errors
including EAGAIN, EOF, connection reset, and connection refused
- Add 150ms verification delay in ensure_daemon to detect shutting-down daemons
- Add cleanup_stale_files to remove leftover socket/PID files before starting
a new daemon
Tested with 20 rapid close/open cycles and 100+ parallel commands.
* test: add unit tests for transient error detection
Extracts is_transient_error() function and adds 14 unit tests covering:
- EAGAIN errors (macOS os error 35, Linux os error 11)
- WouldBlock and Resource temporarily unavailable
- EOF and empty JSON response errors
- Connection reset (macOS os error 54, Linux os error 104)
- Broken pipe errors
- Socket not found (os error 2)
- Connection refused (macOS os error 61, Linux os error 111)
- Non-transient errors (verifies they are NOT retried)
Chris Tate