BrowserForge

Browser session recorder and live viewer for AI agents

Homepage · npm

BrowserForge sits transparently in front of any Chrome DevTools MCP server, recording every browser session your agents take. Watch them live, replay later, debug what went wrong.

To generate screenshots of the UI for documentation:

# Start BrowserForge with some recorded sessions, then:
# 1. Open http://localhost:7600 — capture the live viewer
# 2. Open http://localhost:7600/sessions — capture the session list
# 3. Click into a session — capture the replay view

Quick Start

1. Install

npm install -g browserforge

Or run without installing:

npx browserforge

2. Configure your MCP client

Replace chrome-devtools-mcp with browserforge in your MCP config. BrowserForge proxies all tool calls transparently.

For Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "chrome-devtools-mcp": {
      "command": "npx",
      "args": ["browserforge", "--target", "npx chrome-devtools-mcp"]
    }
  }
}

For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "chrome-devtools-mcp": {
      "command": "npx",
      "args": ["browserforge", "--target", "npx chrome-devtools-mcp"]
    }
  }
}

3. Open the live viewer

http://localhost:7600

Sessions are recorded automatically. Browse past sessions at http://localhost:7600/sessions.

How It Works

BrowserForge is an MCP proxy — it intercepts JSON-RPC messages between your AI agent and the target MCP server. When it detects browser actions (navigate, click, fill, etc.), it captures a screenshot via Chrome DevTools Protocol (CDP) and saves it to disk.

Your agent sees the exact same tools and responses it would get from chrome-devtools-mcp directly. Zero behaviour change, full observability.

CLI Reference

browserforge [options]

Options:
  --port <number>         Web UI port                  (default: 7600)
  --target <command>      Target MCP server command    (default: 'npx chrome-devtools-mcp')
  --storage-dir <path>    Session storage directory    (default: ~/.browserforge/sessions)
  --chrome-port <number>  Chrome CDP debug port        (default: 9222)
  --max-sessions <number> Max sessions to retain       (default: 100)
  --max-age-days <number> Max session age in days      (default: 30)
  --web-only              Run only the web UI (no MCP proxy)
  --version, -v           Show version
  --help, -h              Show help

Examples:

# Custom UI port
browserforge --port 8080

# Custom target MCP server
browserforge --target "node /path/to/my-cdp-server.js"

# Custom storage location, keep 30 days
browserforge --storage-dir ~/recordings --max-age-days 30

Session Storage

Sessions are stored as plain files — no database required:

~/.browserforge/
  config.json              # Default configuration
  sessions/
    <session-id>/
      session.json         # Action timeline + metadata
      frames/
        001.png            # Screenshot per action
        002.png
        ...

Each session directory is self-contained. You can copy, zip, or delete them manually.

Configuration

On first run, BrowserForge creates ~/.browserforge/config.json with defaults:

{
  "storage": {
    "maxSessions": 100,
    "maxAgeDays": 30
  },
  "ui": {
    "port": 7600
  },
  "screencast": {
    "enabled": true,
    "quality": 60,
    "maxFps": 5
  },
  "chrome": {
    "debugPort": 9222
  }
}

CLI flags override the config file. Edit config.json to set persistent defaults.

Requirements

• Node.js >= 22
• Chrome/Chromium with remote debugging enabled (port 9222 by default)
• The target MCP server (e.g. chrome-devtools-mcp) installed separately

Architecture

BrowserForge is an MCP proxy that spawns the target server as a child process and forwards JSON-RPC messages bidirectionally over stdio. An interceptor correlates tools/call requests with their responses, triggering the recording engine to capture screenshots via CDP on each browser action.

Sessions are stored as self-contained directories (PNG frames + JSON manifest) with automatic retention. A WebSocket server streams CDP screencast frames to the Preact-based live viewer in real time.

For the full technical deep-dive, see docs/architecture.md.

Troubleshooting

Common issues:

• Chrome not starting — check if another instance is using the debug port
• CDP connection refused — Chrome needs --remote-debugging-port=9222
• No screenshots — verify CDP page targets exist (curl http://127.0.0.1:9222/json)
• Target MCP server exited — verify the --target command works standalone
• Sessions not appearing — check storage dir permissions and disk space

Quick health check:

curl -s http://localhost:7600/api/health | python3 -m json.tool

For detailed solutions and diagnostic commands, see docs/troubleshooting.md.

Pricing

BrowserForge is free and open source (MIT). Local recording, live streaming, session replay, and compare are all free forever.

| Feature | Free | Pro ($19/mo) | |---|:---:|:---:| | Local recording & replay | ✓ | ✓ | | Live streaming viewer | ✓ | ✓ | | Cloud session sync | — | ✓ | | API access | — | ✓ | | Session retention | 30 days | 365 days |

A Team plan ($49/mo) adds shared dashboards, role-based access, and 5 seats.

See docs/pricing.md for full details and FAQ.

Contributing

# Clone and install
git clone https://github.com/hodlthedoor/browserforge.git
cd browserforge
npm install

# Development (watch mode)
npm run dev

# Run tests
npm test

# Type checking
npm run typecheck

# Build for production
npm run build

See docs/mcp-config-examples.md for detailed setup examples with different MCP clients.

Publishing

BrowserForge uses GitHub Actions to publish to npm automatically when a GitHub release is created.

Prerequisites (one-time setup):

1. Create an npm account at npmjs.com if you don't have one
2. Generate an npm access token: Account → Access Tokens → Generate New Token (Automation type)
3. Add it as a secret in the GitHub repo: Settings → Secrets and variables → Actions → NPM_TOKEN

Once configured, publishing is as simple as creating a new release on GitHub. The workflow will build and publish automatically with npm provenance for supply chain security.

License

MIT