WebBlackbox

A flight recorder and time-travel debugger for web applications.
_{Always recording. So when something goes wrong, you know exactly what happened — and why.}

---

WebBlackbox records what happened inside your web app, packages it into a portable .webblackbox archive, and lets you replay the session later with timeline, screenshots, network, console, storage, DOM, and performance context intact.

If you already have an archive, open it in the hosted Player:

https://webllm.github.io/webblackbox/

Demo:

video.mp4

Why WebBlackbox

• Record user interactions, navigation, console output, runtime errors, network traffic, storage activity, screenshots, and performance signals in one archive.
• Choose between lite capture for lower page-thread overhead and full capture for CDP-backed debugging detail.
• Export encrypted, portable .webblackbox archives for offline replay and team handoff.
• Replay sessions with a rich Player UI and generate curl, fetch, HAR, Playwright, and bug-report artifacts.
• Connect archives to AI workflows through the MCP server.

Choose Your Path

Goal	Use	Docs
Capture sessions in Chrome	@webblackbox/extension	apps/extension/README.md
Replay and inspect archives	Hosted Player	https://webllm.github.io/webblackbox/
Embed lite capture in your app	webblackbox	packages/webblackbox/README.md
Build archive analysis tooling	@webblackbox/player-sdk	packages/player-sdk/README.md
Analyze archives with an AI assistant	@webblackbox/mcp-server	apps/mcp-server/README.md
Self-host share links	@webblackbox/share-server	apps/share-server/README.md

Quick Start

Replay an Existing Archive

1. Open the hosted Player: https://webllm.github.io/webblackbox/
2. Click Load Archive.
3. Select a .webblackbox file or a compatible ZIP export.
4. Inspect the timeline, screenshots, network waterfall, console, storage, and generated artifacts.

Record with the Chrome Extension

1. Download the latest extension package from GitHub Releases.
2. Unzip the downloaded Chrome extension package locally.
3. Open chrome://extensions/.
4. Enable Developer mode.
5. Click Load unpacked and select the extracted extension directory.
6. Click the WebBlackbox toolbar icon and choose Start Lite or Start Full.
7. Reproduce the issue, then export a .webblackbox archive.
8. Open the archive in the hosted Player.

Embed Lite Capture in Your App

npm install webblackbox

import { WebBlackboxLiteSdk } from "webblackbox";

const sdk = new WebBlackboxLiteSdk();
await sdk.start();

Full SDK details are in packages/webblackbox/README.md.

What It Captures

WebBlackbox currently records 57 event types across 13 categories, including:

• User input and navigation
• Console logs and runtime errors
• Network requests, responses, failures, redirects, WebSocket, and SSE events
• DOM mutations and snapshots
• Screenshots and viewport changes
• Cookies, localStorage, sessionStorage, IndexedDB, Cache, and service worker lifecycle
• Web Vitals, long tasks, traces, CPU profiles, and heap snapshots

For the full event schema, defaults, and message types, see packages/protocol/README.md.

Archive Format

Sessions are exported as .webblackbox ZIP archives containing:

• manifest.json with export metadata and encryption info
• chunked NDJSON event streams
• time/request/text indexes
• content-addressed blobs for screenshots, DOM snapshots, and captured bodies
• integrity hashes for verification

Archives can be encrypted with AES-GCM and PBKDF2-derived keys while keeping the manifest readable.

Documentation

• Chrome Extension Guide
• Player Guide
• Web SDK Guide
• Player SDK Guide
• MCP Server Guide
• Share Server Guide
• Architecture Notes
• Performance Notes

Contributing

If you want to work on the monorepo itself, start with CONTRIBUTING.md.

License

MIT © Web LLM