Tracebug

TraceBug

Capture the bug. Let AI fix it.

Local-first, zero backend. One .html file — full replay, console errors, network requests, repro timeline — that your AI coding agent reads over MCP and fixes. Opens offline for humans too.

▶ Watch the 1-minute demo ( vertical Short ) · watch Claude debug a real bug · try it live in the sandbox

---

TraceBug is a local-first debugging assistant. Capture a bug → produce a single self-contained .html file → hand it to your AI coding agent (Claude Code, Cursor, Windsurf), which reads the evidence over a local MCP server and fixes it — or email/Slack it to a human dev who opens it offline. Every report also embeds a failing test the agent runs to verify the fix.

Every report opens with:

🔍 Possible Cause (high confidence): API POST /orders failed with 500 after clicking 'Place Order'

TL;DR: TypeError thrown on /checkout when clicking 'Place Order' button

No accounts. No SaaS lock-in. Data stays in your browser by default.

Optional cloud sharing (built, UI-gated off by default): if you'd rather share a URL than a file, sign in once and get a share link with the same content. The code ships behind a feature flag (PHASE2-CLOUD); the Share button stays disabled until the portal is switched on. Local .html export is the supported sharing path today.

Works with any frontend framework: React, Angular, Vue, Next.js, Nuxt, Vite, Svelte, SvelteKit, Remix, Astro, or plain HTML.

⚡ Get Started in 30 Seconds

New here? [Report your first bug in 2 minutes →](docs/quickstart.md)

npx tracebug init

That's it. The CLI detects your framework and prints the exact 2-line snippet. Paste it into your app, run npm run dev, and you'll see the TraceBug toolbar on the right edge.

Report a bug in 2 clicks:

1. Press `Ctrl+Shift+B` (or click the ⚡ button on the toolbar)
2. Review the auto-filled report, click "Copy GitHub Issue"
3. Paste into your repo. Done.

What TraceBug Does

Tester opens the page

↓ Arm a session (idle until you act): • ⚡ Quick Bug — Ctrl+Shift+B opens the ticket-review modal • 📷 Screenshot / Region • 🔴 Record — Sentry mode: rolling video buffer + HUD with timestamped comments. File multiple bugs from one screen-share. • ⏺ Track session — event-only capture (no video). Survives full-page navigation, so clicking a link keeps recording. ↓ The SDK captures: clicks, inputs, navigation, API calls, console, errors, the DOM stream (rrweb), environment, and a redacted Web-Storage snapshot ↓ Review the ticket, then export: • Export .html — self-contained interactive DOM replay (KB, not MB) • Export for AI (.html) — tiny text-only report to paste into a chat • Download report (.md) · .zip (GitHub-attachable) · failing test (.spec.ts) • Export HAR · file a real GitHub/Linear/Slack/Jira issue ↓ Complete report includes:

• Auto-generated title + smart summary + root-cause hint (high/medium/low confidence)
• Steps to reproduce, full session timeline
• Interactive DOM replay (or screen recording .webm), screenshots
• Console errors + stack traces, failed network requests with response snippets
• Environment (browser, OS, viewport, device) ↓

Send the .html → developer opens it offline and sees exactly what happened, or an MCP-connected coding agent reads it and debugs from it.

Scan Page (a11y via axe-core, broken images, mixed content, frustration

signals, failed/slow APIs, JS errors) is available programmatically as

TraceBug.scanPage(); it is no longer a toolbar button.

Two Ways to Use TraceBug

Option 1: npm Package (For Developers)

Install the SDK in your project — best for teams who want TraceBug always active on dev/staging.

npm install tracebug-sdk

import TraceBug from "tracebug-sdk";

TraceBug.init({ projectId: "my-app" });

Option 2: Chrome Extension (For Non-Developers)

Install the browser extension — no code needed. QA testers, PMs, and clients can use it on any website.

[Install from Chrome Web Store](https://chromewebstore.google.com/detail/fdemmibikigigkfjngclmdheeajhdgaj) — one click, works immediately.

Browser support

The SDK is framework- and browser-agnostic — it runs anywhere modern JS runs. ¹ The interactive DOM-replay export uses the browser-native CompressionStream / DecompressionStream (Chrome 80+, Firefox 113+, Safari 16.4+); on older engines the exporter ships the replay uncompressed and the viewer falls back to the screenshot gallery. The extension runs on Chromium browsers and Firefox 128+ (no Safari build — on Safari, use the npm SDK).

Features

🧠 Debugging Assistant (v1.3)

Every report opens with four derived signals that turn "what happened" into "why it likely happened":

Plus:

• Network response snippets — first 200 chars of every failed fetch/XHR response body, captured asynchronously (never blocks the request)
• In-memory failure buffer — last 10 failed requests accessible via TraceBug.getNetworkFailures()
• Deterministic — pure functions, no AI APIs, O(1) on already-computed report fields

All four signals ship inline in GitHub issues, Jira tickets, PDF reports, and the Quick Bug modal. See docs/bug-reporting.md for full output examples.

🤖 MCP Server — AI Agents Debug Your Reports (v1.5)

Your coding agent (Claude Code, Cursor, Windsurf, VS Code) reads TraceBug bug reports and fixes the bug — fully local, nothing uploaded:

claude mcp add tracebug -- npx -y tracebug mcp --dir ./bug-reports

-y skips npx's install prompt but does not pin a version — it resolves whatever's newest on the npm registry at the time it runs. For a known, audited build instead, pin explicitly: npx tracebug@1.10.1 mcp --dir ./bug-reports (bump the version when you deliberately upgrade).

The server reads the same self-contained .html files TraceBug exports. A tester hands a dev the report file, the dev drops it in the repo, and the agent gets nine tools: list_bug_reports, get_bug_report, get_console_errors, get_network_activity, get_repro_steps, get_screenshot (real image content), get_playwright_test, resolve_stack, and get_fix_context. get_bug_report returns a prioritized investigation guide computed from what the report contains, so the agent knows exactly which tools to call next. Console stacks + failed-request bodies + repro steps + frustration signals — everything an agent needs to go from bug report to fix.

The last three close the fix loop (v1.9): get_playwright_test returns the generated failing Playwright spec that replays the session and asserts the captured failure is gone — red until the bug is fixed, green after — so the agent can run it, patch, and re-run until green. resolve_stack maps the report's minified stack frames to original source files/lines using .map files found in the repo the server runs from. get_fix_context is a one-call fix starter: the failing request with response snippet, the user action that triggered it, the source-map-resolved top stack frames, and whether a failing test is available.

Kicking off is one paste: the extension shows a ready-made agent prompt after every Export .html (auto-copied), the exported file itself carries the same prompt in its AI tab, and in Claude Code you can just type /tracebug:debug_bug_report.

Other tools' MCP servers are cloud-hosted: your bug data must live on their servers first. TraceBug's runs on your machine over stdio and opens zero network connections. Try it instantly — this repo ships a demo report and a pre-configured .mcp.json. See docs/mcp.md.

🎭 Playwright Reporter — Bug Reports From Failed Tests (v1.6)

Every failed Playwright test becomes the same self-contained .html bug report — assertion error + code snippet, step timeline as repro steps, page console + network (via the optional fixture), failure screenshot, and a root-cause hint. Upload bug-reports/ as a CI artifact, then debug it with your agent via the MCP server:

// playwright.config.ts — that's the whole setup

reporter: [["list"], ["tracebug-sdk/playwright", { outputDir: "bug-reports" }]],

Nobody else captures bugs from test runs as portable files — cloud tools can't attach their viewer to a CI artifact. See docs/playwright.md.

🧠 AI Debugger — BYO-Key LLM Analysis (v1.6)

Run real LLM root-cause analysis with your own key — Anthropic, OpenAI, or local Ollama. The call goes directly from your browser to the provider: TraceBug never sees the key, the prompt, or the response, and the prompt is scrubbed of secret shapes before it leaves the page. No metered credits, no vendor cloud in the path.

Combined with the local heuristic hint and the local MCP server, this is AI debugging that never phones home — the one position no cloud-hosted, metered competitor can copy.