browser-goblin

Give your coding agent eyes, hands, and a QA brain inside a real browser.

browser-goblin lets Pi stop guessing from source code alone. It can open your app, click through user flows, read the accessibility tree, inspect console errors, catch failed network requests, measure Web Vitals, capture responsive screenshots, and leave behind clean artifacts you can review. It turns browser work into an agentic coding loop: observe → reproduce → debug → patch → verify.

Use it when you want Pi to:

• test local or deployed web apps like a real user
• debug broken navigation, JavaScript errors, hydration issues, and failed API calls
• run desktop/tablet/mobile visual QA in one command
• inspect authenticated flows with reusable browser sessions
• capture screenshots and artifact manifests without cluttering your repo
• validate fixes instead of merely editing files and hoping
• produce support-grade bug reports with repro steps, evidence, and browser health checks

browser-goblin uses Vercel Labs' agent-browser CLI as its browser automation backend. This package is a Pi extension, adding tools, slash commands, skills, artifact management, persistent defaults, and visual-QA workflows. The underlying CLI can be used by other harnesses, but this integration requires Pi.

GitHub source · npm package · Pi package page

Install

Requires Pi and Node.js 24 or newer. The browser backend is pinned to agent-browser 0.39.2 so installs use the tested CLI version.

Install the published package from your terminal:

pi install npm:browser-goblin

Start Pi, or run /reload in an existing Pi session, then check the browser setup:

/browser-doctor

The backend can use an existing supported Chrome installation. If diagnostics report that Chrome is missing, install it from your terminal using the matching backend version:

npx --yes agent-browser@0.39.2 install

On Linux, additional browser system libraries may be needed; the backend also supports install --with-deps. After setup, run /browser-doctor again in Pi.

Only load one copy of Goblin: use the npm package for normal use, and an isolated source checkout for development. You do not need to clone the repository to use the published package. See CONTRIBUTING.md for development setup.

Update

Update only Goblin from your terminal:

pi update npm:browser-goblin

Then run /reload in Pi, or restart Pi, to load the updated extension. If you installed a pinned version such as npm:browser-goblin@0.5.0, install the desired newer version explicitly instead.

Agentic workflows

One-command responsive QA:

/browser-qa http://localhost:3000 --headed

Pi opens the page, captures desktop/tablet/mobile screenshots, checks console errors, page errors, 4xx/5xx network requests, and Web Vitals, then reports artifact paths.

Debug a broken flow:

Open http://localhost:3000, reproduce the checkout bug, inspect console/network errors, patch the likely source files, then rerun the flow in the browser.

Visual review before shipping:

Run browser_qa on the dashboard, inspect the mobile screenshot, fix spacing or hierarchy issues, and rerun the same QA pass.

Support and bug reports:

Use browser-testing to reproduce the user's issue, collect screenshots/network evidence, and summarize exact repro steps plus validation results.

Quick examples

Visible browser:

/browser-headed on
Open http://localhost:3000 and test the main flow.

Background/headless-style browser:

/browser-headed off
Use browser-testing to test http://localhost:3000 and report console errors.

One-off visible open without changing preference:

Use browser_open with headed true to open http://localhost:3000.

Tools

Core tools:

• browser_open
• browser_snapshot
• browser_click
• browser_fill
• browser_press
• browser_wait
• browser_screenshot
• browser_read
• browser_tabs
• browser_set_viewport
• browser_reload
• browser_back
• browser_forward
• browser_artifacts_list
• browser_artifacts_latest
• browser_qa
• browser_close

Debug tools:

• browser_console
• browser_errors
• browser_network
• browser_vitals
• browser_eval
• browser_debug legacy combined debug tool
• browser_batch
• browser_artifacts_clean

Slash commands:

/browser-tools core|debug|all|off
/browser-session [session-id]
/browser-headed on|off|auto
/browser-artifacts
/browser-artifacts list [--all]
/browser-artifacts latest [--all]
/browser-artifacts clean [--all] [--confirm]
/browser-config [show|viewport|artifact-dir|reset]
/browser-qa <url> [--viewports=desktop,tablet,mobile] [--headed] [--annotate]
/browser-doctor

Artifacts

Screenshots with no explicit path are saved automatically under:

~/.pi/agent/browser-artifacts/<session-id>/

List or retrieve latest artifacts:

Use browser_artifacts_list.
Use browser_artifacts_latest.

Clean artifacts safely:

Use browser_artifacts_clean without confirm for a dry run.
Use browser_artifacts_clean with confirm true to delete.

Override the root directory with:

export PI_BROWSER_ARTIFACT_DIR=/path/to/browser-artifacts

Visual QA

Use viewport presets:

Use browser_set_viewport with preset desktop, take a screenshot, then try tablet and mobile.

Screenshots support:

• automatic timestamped filenames
• full: true
• annotate: true
• manifest metadata in <artifact-session>/manifest.json

Run a full quick pass:

Use browser_qa for http://localhost:3000 with desktop, tablet, and mobile.

Or:

/browser-qa http://localhost:3000 --headed

Skills

Bundled skills:

• browser-testing
• browser-debugging
• browser-visual-qa
• browser-auth

Notes

• Prefer browser_snapshot and refs like @e3 over screenshots/selectors.
• Refs persist for surviving elements across same-document changes. Take a fresh snapshot after navigation, element replacement, or ambiguous-ref errors.
• Screenshots are for visual QA, canvas/charts/images, and layout issues.
• Browser state defaults to a stable worktree-scoped session with --restore.
• Prefer http://localhost over http://0.0.0.0 when browser APIs, service workers, or cookies matter.
• Treat state files, cookies, and Chrome profile snapshots as secrets.

Configuration

Persistent defaults are stored in:

~/.pi/agent/browser-tools.json

Manage them with:

/browser-headed on|off|auto
/browser-session <session-id>|default
/browser-config viewport desktop|tablet|mobile
/browser-config artifact-dir ~/.pi/agent/browser-artifacts
/browser-config show

These settings are saved at the user level and can affect future Pi runs and other projects. In particular, /browser-session <session-id> overrides the automatic worktree-scoped browser session. Prefer the tool's session parameter for a one-off task instead of changing that persistent default.

Environment variables still win where supported.

Set a custom agent-browser binary path if needed:

export PI_BROWSER_AGENT_BROWSER_BIN=/path/to/agent-browser

Development checks

For contributors, run these from a source checkout after installing development dependencies as described in CONTRIBUTING.md. Do not run the development scripts from Pi's installed node_modules copy.

npm run check
npm run check:package
npm run test:smoke

The smoke test starts a local fixture and exercises Goblin's tools against the pinned backend, including forms, persistent refs, tabs, screenshots, and responsive QA. No personal browser profile or external test website is needed. For an npm-installed extension, use /browser-doctor and the workflows above instead.

Contributing and security

• See CONTRIBUTING.md for local setup, validation, and release notes.
• See SECURITY.md for guidance on browser state, cookies, screenshots, and responsible disclosure.
• browser-goblin controls a real browser. Review third-party packages before installing them and avoid sharing sensitive artifacts.