Agent Browser

Agent Browser is an open-source browser automation layer for AI agents. It gives coding agents, deploy agents, and research agents a safe way to inspect web pages, capture screenshots, read console and network signals, and validate web apps.

Why it exists

Modern AI agents need a browser tool that is:

• safe by default
• easy to inspect
• usable from CLI and MCP
• suitable for testing, deploy validation, and page understanding

Agent Browser provides that foundation without credential automation, anti-detection tooling, or private-network scraping.

Talocode ecosystem

Agent Browser fits into the Talocode stack:

• Codra CLI — the coding agent
• Codra Action — GitHub automation
• Codra Deploy — deployment and runtime validation
• Agent Browser — browser automation and web inspection

Typical uses:

• AI agents test web apps
• Codra checks frontend behavior
• Codra Deploy validates live deployments
• LaunchPix captures landing pages
• TeraAI reads and understands web pages
• Developers run browser automation through CLI and MCP

Install

npm install
npm run build

Playwright requires a Chromium binary for live browsing:

npx playwright install chromium

Development

npm install
npm run dev -- --help
npm run typecheck
npm run test
npm run build

Local development against localhost:

export AGENT_BROWSER_ALLOW_LOCALHOST=1

CLI

agent-browser --help
agent-browser check https://example.com
agent-browser check https://example.com --screenshot-out ./deploy.png --vision --json
agent-browser navigate https://example.com
agent-browser snapshot https://example.com
agent-browser screenshot https://example.com --out ./example.png
agent-browser console https://example.com
agent-browser network https://example.com
agent-browser mcp

Machine-readable output:

agent-browser --json snapshot https://example.com

Screenshot overwrite protection:

agent-browser screenshot https://example.com --out ./example.png --force

MCP usage

Start the MCP server:

agent-browser mcp

Available tools:

• browser_navigate
• browser_snapshot
• browser_screenshot
• browser_console
• browser_network
• browser_check

Each tool validates URL safety and returns structured JSON results.

browser_check runs the deploy-friendly smoke check preset and returns a normalized pass/warn/fail protocol result. Optional vision uses the Python module when available.

Safety model

Agent Browser blocks unsafe protocols and private network targets by default. Localhost is disabled unless AGENT_BROWSER_ALLOW_LOCALHOST=1 is set for local development.

Sensitive query parameters are redacted from network output. The project does not store secrets, automate login, bypass CAPTCHAs, or provide anti-detection behavior.

See docs/SAFETY.md for details.

Architecture

See docs/ARCHITECTURE.md.

Optional Vision Module

Agent Browser also includes an optional Python package for screenshot visual inspection. OpenCV is not required for normal TypeScript CLI or MCP usage.

cd python/agent-browser-vision
pip install -e ".[dev]"
agent-browser vision inspect ./screenshot.png --json
agent-browser vision diff ./before.png ./after.png --out ./diff.png --json

You can also call the Python CLI directly:

agent-browser-vision inspect ./screenshot.png --json
agent-browser-vision diff ./before.png ./after.png --out ./diff.png --json

The vision module can detect blank or blurry screenshots, compare before/after captures, save diff images, and flag major layout shifts.

See docs/VISION.md for details.

Smoke checks

Deploy-friendly preset for agents, Codra CLI, and Codra Deploy:

agent-browser check https://example.com
agent-browser check https://example.com --screenshot-out ./deploy.png --vision --json
codra browser check https://example.com

See docs/CHECKS.md for the pass/warn/fail model.

Use as GitHub Action

Run deploy-friendly smoke checks in any external repository:

- uses: talocode/agent-browser@v0
  with:
    url: https://example.com
    screenshot-out: agent-browser-screenshot.png
    vision: "false"
    upload-artifact: "true"

Pin an immutable release when needed:

- uses: talocode/agent-browser@v0.1.0
  with:
    url: https://example.com

External verification passed from talocode/agent-browser-action-test using talocode/agent-browser@v0.

Copy a full external verification workflow from docs/examples/external-verification.md or examples/github-action/external-smoke.yml.

For Codra Deploy post-deploy checks, see docs/CODRA_DEPLOY_INTEGRATION.md.

See also docs/GITHUB_ACTION.md, docs/RELEASE.md, and examples/github-action/.

Roadmap

• Deeper Codra and Codra Deploy integrations
• Persistent sessions for multi-step agent workflows
• Accessibility-oriented snapshots
• CI-friendly smoke check presets
• Optional form inspection without credential automation

License

MIT