# BrowserForge

[![npm version](https://img.shields.io/npm/v/browserforge)](https://www.npmjs.com/package/browserforge)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/hodlthedoor/browserforge/actions/workflows/release.yml/badge.svg)](https://github.com/hodlthedoor/browserforge/actions/workflows/release.yml)

> Browser session recorder and live viewer for AI agents
>
> **[Homepage](https://hodlthedoor.github.io/browserforge/)** · **[npm](https://www.npmjs.com/package/browserforge)**

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:

```bash
# 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**

```bash
npm install -g browserforge
```

Or run without installing:

```bash
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`):

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

For **Claude Desktop** (`claude_desktop_config.json`):

```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:**

```bash
# 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:

```json
{
  "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](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:

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

For detailed solutions and diagnostic commands, see **[docs/troubleshooting.md](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](docs/pricing.md)** for full details and FAQ.

---

## Contributing

```bash
# 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](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](https://www.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](https://docs.npmjs.com/generating-provenance-statements) for supply chain security.

---

## License

MIT