Getting started

WhittleBrowser is an MCP server (and a TypeScript library) that lets an AI agent drive a Chromium browser through compact text views.

Requirements

macOS (Linux and Windows should work but are untested)
Node.js 22 or newer
pnpm 10 (npm i -g pnpm)

Install from npm

The package is @whittlebrowser/engine on npm. Connect it to your agent with one command:

claude mcp add whittlebrowser -- npx -y @whittlebrowser/engine     # Claude Code
codex mcp add whittlebrowser -- npx -y @whittlebrowser/engine      # Codex

You also need Google Chrome, or a downloaded Chromium (npx playwright-core install chromium, once). For Claude Desktop, Cursor, VS Code and other clients, see Use it with Claude, Cursor, Codex and other AI tools.

Install from source (to work on the engine)

Run it from a clone:

git clone https://github.com/vasanth7781/whittlebrowser-engine.git
cd whittlebrowser-engine
pnpm install
pnpm --filter @whittlebrowser/engine build
npx playwright-core install chromium    # downloads the browser it drives (once; skip it if Google Chrome is installed)

Connect a source checkout

From a clone, these commands register your build with a client:

pnpm connect          # Claude Code
pnpm connect codex    # Codex
pnpm connect desktop  # Claude Desktop (then quit and reopen it)
pnpm connect skill    # optional: a skill that teaches Claude to use the tools cheaply and safely

Each runs claude mcp add or codex mcp add with the right path, and prints the config JSON for Cursor, VS Code and other clients. This opens its own Chromium window. Add --headless for no window or --ephemeral for a throwaway profile. Setup for Cursor, Codex, VS Code and others is in Use it with Claude, Cursor, Codex and other AI tools; the full flag list is in Use with Claude Code.

Try it

Ask your agent, for example:

Use whittlebrowser to open news.ycombinator.com and list the top 5 stories with their links.

Watch the token count of each call in your agent's tool output. To see exactly what the model is sent for a page, run the server with --xray and compare the overlay with the text view.

Run the tests and benchmark

pnpm test                       # unit + browser + MCP tests (headless)
pnpm bench                      # token and safety benchmark vs Playwright MCP, browser-use, Stagehand
pnpm bench -- --live --pw-mcp   # include live sites and Playwright MCP's tool definitions
pnpm bench:agent --smoke        # one real-agent run per tool through Claude Code (needs the claude CLI)

Use it as a library

import { Session, launch, StaticPolicy } from '@whittlebrowser/engine';

See Protocol for the view format and tool arguments.

PreviousIntroduction NextUse with Claude Code