TraceBug

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 →

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.

Related MCP server: SuperBased Observer

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 — 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 is Chromium-only today (Firefox port paused; no Safari build) — on those, 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

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. See docs/ai-debugger.md.

🌐 HAR Export (v1.6)

One click exports the captured network activity as a standard HAR 1.2 file that opens in DevTools, Charles, Fiddler, or Postman. No competitor ships this — Jam even markets "everything a HAR offers" without the export. Your network capture is a portable file you own, not a row in someone's cloud. See docs/har-export.md.

🧪 Generated Failing Playwright Test (v1.9)

Every export carries a runnable Playwright spec that replays the captured session (locators prefer data-testid → id → aria-label → role+name → captured CSS selector) and asserts the captured failure is gone — the failing endpoint must stop failing, the console errors must stop being thrown. Red while the bug exists, green after the fix. Get it three ways: Download failing test (.spec.ts) in the Quick Bug More menu, embedded in the .html export, or via the MCP get_playwright_test tool — so an agent can run it, patch, and re-run until green.

🔎 Inspect Mode — Style Evidence for Design-QA Bugs (v1.9)

"The button looks wrong" now ships with the receipts. A DevTools-style inspect mode (extension popup → Inspect element, or TraceBug.activateInspectMode()): hover paints the box-model highlight plus a computed-style summary tooltip; click attaches the element to the report with a curated style snapshot — typography, colors as hex, box model — plus a WCAG text-contrast verdict (ratio + AA pass/fail). Surfaced on annotation cards, in generated GitHub issues, in the export, and as structured data MCP agents get from get_bug_report.

🎬 Pre-Recording Options + Element-Level Blur (v1.9)

The extension popup's ⚙ Record options panel picks the capture surface (current tab / desktop picker), an optional 3s/5s countdown, and Blur before recording — redact sensitive areas before the first frame is captured. Also public SDK API: TraceBug.prepareRecording({ blurFirst, delaySec, surfaceMode, withMicrophone }).

Blur itself is element-level, click-to-blur: hover highlights, click applies filter: blur(12px) to the element itself, click again unblurs. Because the blur is part of the element's own rendering, it physically cannot lag behind scrolling. Blurred elements also get tb-mask, so the DOM replay masks their text, not just the video pixels.

📦 Reports the Recipient Can Act On (v1.8)

• Download .zip (attach to GitHub) — the same offline replay wrapped in a .zip, because GitHub issues accept .zip attachments by drag-and-drop but reject bare .html.

• Issue actions inside the exported report — the viewer header has Open GitHub issue (prefilled URL when the exporter configured githubRepo) and Copy issue markdown (fully offline, pastes into any tracker). Both are precomputed at export time from the already-redacted report.

Auto-Captured (Zero Effort)

Sentry Mode — Rolling Video Buffer

Click Record once at the start of a QA session, file as many bug tickets as you want from the same screen-share. Inspired by NVIDIA Shadowplay / OBS replay buffer.

Auto-Scanner

Click Scan to run six in-browser detectors in parallel and surface issues you might not have noticed:

Each issue offers Locate (flash the offending element), File ticket (pre-fills the Quick Bug modal), and Dismiss.

QA Tools (One Click)

Available Programmatically (cut from default UI in v1.0)

These features still ship in the bundle but no longer have toolbar buttons. Power users can call them directly:

TraceBug.activateAnnotateMode();   // element annotate mode (Ctrl+Shift+A no longer wired)
TraceBug.activateDrawMode();       // live-page rectangles/ellipses
TraceBug.downloadPdf();            // PDF report
TraceBug.exportAnnotationsJSON();  // JSON / Markdown export

Auto-Generated

Smart Filtering

• SDK self-filtering: TraceBug never records its own UI interactions (clicks on the dashboard, annotation canvas, buttons)

• Framework noise removal: Internal dev-server requests (webpack HMR, Vite ping, Next.js stack frames) are automatically excluded from timeline and reports

• Duplicate error dedup: Consecutive identical errors are collapsed

User Identification & Bug Workflow

// Identify who's using the app (persisted in localStorage)
TraceBug.setUser({ id: "user_123", email: "dev@co.com", name: "Jane" });

// Flag current session as a bug (adds red BUG badge)
TraceBug.markAsBug();

// Get a 2-sentence Slack-friendly summary
const summary = TraceBug.getCompactReport();
// "Bug on /vendor — TypeError: Cannot read 'status' after clicking Edit → selecting Inactive..."

Plugin & Hook System

Extend TraceBug without forking — filter events, enrich reports, or trigger custom actions:

TraceBug.use({
  name: "slack-webhook",
  onReport: (report) => { fetch("https://hooks.slack.com/...", { method: "POST", body: JSON.stringify(report) }); return report; },
});

TraceBug.on("error:captured", (error) => console.log("Bug found:", error.data.error.message));

CI/CD Helpers

// In Playwright/Cypress tests
expect(TraceBug.getErrorCount()).toBe(0);

// Upload full session as test artifact on failure
const json = TraceBug.exportSessionJSON();

Installation

From npm

npm install tracebug-sdk

From GitHub

npm install github:prashantsinghmangat/tracebug-ai

Chrome Extension (No Code Required)

See Chrome Extension section below.

Configuration

TraceBug.init({
  projectId: "my-app",        // Required: identifies your app
  maxEvents: 200,             // Max events per session (default 200)
  maxSessions: 50,            // Max sessions in localStorage (default 50)
  enableDashboard: true,      // Show the floating bug button (default true)
  enabled: "auto",            // Control when SDK is active (see below)
});

enabled option

Programmatic API

Core

import TraceBug from "tracebug-sdk";

TraceBug.pauseRecording();
TraceBug.resumeRecording();
TraceBug.startRecording();   // alias for resumeRecording
TraceBug.stopRecording();    // alias for pauseRecording
TraceBug.isRecording();
TraceBug.getSessionId();
TraceBug.destroy();

Screenshots

// Capture full-viewport screenshot (auto-named from last event context)
const screenshot = await TraceBug.takeScreenshot();
// → { filename: "01_click_add_vendor.png", dataUrl: "data:image/png;...", ... }

// Snipping-tool style: user drags a region, press Esc to cancel
const region = await TraceBug.takeRegionScreenshot();
// → { filename: "02_click_..._region.png", ... } | null

const allScreenshots = TraceBug.getScreenshots();

Voice Recording

// Check if voice recording is supported in the browser
if (TraceBug.isVoiceSupported()) {
  // Start recording — speech-to-text via Web Speech API (free, no API keys)
  TraceBug.startVoiceRecording({
    onUpdate: (text, interim) => console.log("Transcript:", text),
    onStatus: (status, msg) => console.log("Status:", status),
  });

  // Stop recording — returns the transcript
  const transcript = TraceBug.stopVoiceRecording();
  // → { id, timestamp, text: "When I click update the page breaks", duration }

  // Get all voice transcripts
  TraceBug.getVoiceTranscripts();
}

Voice transcripts are automatically included in GitHub Issue, Jira Ticket, and PDF reports.

Tester Notes

TraceBug.addNote({
  text: "Button doesn't respond after selecting Inactive status",
  expected: "Vendor should update successfully",
  actual: "App throws TypeError and freezes",
  severity: "critical",  // "critical" | "major" | "minor" | "info"
});

Reports

// Generate complete bug report object
const report = TraceBug.generateReport();

// Get auto-generated bug title
const title = TraceBug.getBugTitle();
// → "Vendor Update Fails — TypeError"

// Get GitHub issue markdown (copies to clipboard in dashboard)
const markdown = TraceBug.getGitHubIssue();

// Get Jira ticket payload
const ticket = TraceBug.getJiraTicket();
// → { summary, description, environment, priority, labels }

// Download PDF report
TraceBug.downloadPdf();

// Get environment info
const env = TraceBug.getEnvironment();
// → { browser: "Chrome", browserVersion: "122", os: "Windows 10/11", ... }

Data Access

import { getAllSessions, clearAllSessions, deleteSession } from "tracebug-sdk";

const sessions = getAllSessions();
const bugs = sessions.filter(s => s.errorMessage);
clearAllSessions();
deleteSession("session-id");

Standalone Utilities

import {
  generateReproSteps,
  captureEnvironment,
  buildReport,
  generateGitHubIssue,
  generateJiraTicket,
  generateBugTitle,
  buildTimeline,
  formatTimelineText,
} from "tracebug-sdk";

Element Annotation & Draw

// Activate modes programmatically
TraceBug.activateAnnotateMode();   // Click elements to annotate
TraceBug.activateDrawMode();       // Draw shapes on the page

// Check state
TraceBug.isAnnotateModeActive();
TraceBug.isDrawModeActive();

// Export all annotations
const report = TraceBug.getAnnotationReport();
const md = TraceBug.exportAnnotationsMarkdown();
await TraceBug.copyAnnotationsToClipboard("markdown");

// Deactivate
TraceBug.deactivateAnnotateMode();
TraceBug.deactivateDrawMode();
TraceBug.clearAnnotations();

Dashboard

The compact toolbar on the right edge of the screen provides:

• ⚡ Quick Bug — open the ticket-review modal (Ctrl+Shift+B)

• 📷 Screenshot — capture the page, with an annotation editor

• ▢ Region — capture a selected region

• 🔴 Record — screen recording (Sentry mode: rolling buffer + HUD)

• ⏺ Track session — event-only capture, no video (survives navigation)

• ✓ View saved tickets — the offline Saved Tickets list

• ✕ — turn TraceBug off on this page

Annotate and Draw modes still ship in the bundle but were cut as standalone toolbar buttons in v1.0 — reach them programmatically or via the recording HUD's Pen button. See docs/annotate-and-draw.md.

Quick Bug modal

Review and edit the ticket, then export or file it:

• Auto-generated title, summary, root-cause hint, reproduction steps, timeline

• Interactive DOM replay (or the screen recording), screenshots gallery

• Tabs: Info · Console · Network · Actions · AI · Events

• Export: Export .html (replay) · Export for AI (.html) · Download report (.md) · Download .zip (GitHub-attachable) · Download failing test (.spec.ts) · Export HAR

• File directly: GitHub · Linear · Slack · Jira (real issues with a configured token)

Keyboard Shortcuts

Note: Ctrl+Shift+A (annotate) and Ctrl+Shift+D (draw) are no longer bound by default. The underlying modes remain callable via the programmatic API (TraceBug.activateAnnotateMode() / activateDrawMode()); draw mode is also reachable from the ✎ button on the recording HUD.

Documentation

Full documentation is in the docs/ folder:

• Getting Started — Install, setup, first use

• API Reference — Complete programmatic API

• Configuration — All config options explained

• Bug Reporting — Screenshots, notes, voice, export

• MCP Server — Let AI agents (Claude Code, Cursor) debug your reports

• Annotate & Draw — UI annotation features

• Chrome Extension — Extension install & usage

• Architecture — How TraceBug works internally

• ADRs — Why local-first, single-file HTML, rrweb, MV3, zero deps

• Performance — Measured numbers + the reproducible benchmark

• Compatibility — Browser matrix, support policy, known limitations

• Migration Guide — Upgrade notes and API stability

• Roadmap — Shipped · in progress · planned · long-term

Chrome Extension

The TraceBug Chrome Extension lets non-developers use all TraceBug features without writing code.

How to Install

Recommended: Install from Chrome Web Store — works in Chrome, Edge, Brave, and Opera.

From source (for developers):

1. git clone this repo, then npm install && npm run build

2. Open chrome://extensions/ → Enable Developer mode → Load unpacked → select tracebug-extension/

How to Use

1. Navigate to any website (staging, production, localhost, internal tools)

2. Click the TraceBug extension icon in the toolbar

3. Toggle "Enable on this site" — the page reloads with TraceBug active

4. The floating bug button appears on the page

5. Use all QA tools: screenshots, notes, GitHub/Jira issues, PDF reports

6. Quick actions also available directly from the extension popup

Extension Features

• Per-site toggle — enable only on sites you're testing

• Badge indicator — shows "ON" in green when active on current tab

• Quick actions — Annotate, Draw, Screenshot, PDF Report, GitHub Issue, Jira Ticket from the popup

• Active sites list — manage all enabled sites from the popup

• Compact toolbar on page — same full-featured toolbar as the npm SDK

• CSP-safe — uses chrome.scripting.executeScript with world: "MAIN" to bypass Content Security Policy restrictions

Browser Compatibility

Chrome Web Store

TraceBug is published on the Chrome Web Store:

Install TraceBug Extension

Build from Source

# Clone the repo
git clone https://github.com/prashantsinghmangat/tracebug-ai.git
cd tracebug-ai

# Install dependencies
npm install

# Build SDK (produces CJS + ESM + IIFE for extension)
npm run build

# Output:
#   dist/index.js              — ESM (npm package)
#   dist/index.cjs             — CJS (npm package)
#   dist/index.d.ts            — TypeScript declarations
#   tracebug-extension/tracebug-sdk.js — IIFE (Chrome Extension)

Run Example App

cd example-app
npm install
npm run dev
# Open http://localhost:3000

Test the Example Bug

1. Go to /vendor

2. Click "Edit"

3. Change Status to "Inactive"

4. Click "Update" — triggers TypeError

5. Click the bug button to see the report with reproduction steps

Privacy

• Sensitive fields auto-redacted (password, secret, token, ssn, credit)

• ~20 token-shape patterns masked at capture (JWT, Bearer headers, cloud provider keys) — a logged secret never enters the report object

• The export flow and the exported report show exactly what was masked: 🛡 N sensitive values auto-masked

• App-specific PII covered via redact: { fields, patterns } in config — also settable in the extension popup's 🛡 Redaction rules section

• All data stays in localStorage — nothing leaves the browser

• SDK never captures its own UI interactions

• No external servers, no tracking, no analytics

Framework Compatibility

Uninstall

npm Package

npm uninstall tracebug-sdk

Then remove the TraceBug.init() call from your app's entry file.

⭐ Star this repo if it saves you time

If TraceBug helped you ship faster, a star is the best way to say thanks — it helps other developers find it too.

Spread the word:

• Share on Twitter/X

• Share on LinkedIn

• Share on Hacker News

Found a bug or have a feature idea? Open an issue — TraceBug was built because bug reports sucked. We're here to make them suck less.

Chrome Extension

Go to chrome://extensions/ → click Remove on TraceBug.

License

MIT

Author

Prashant Singh Mangat

• GitHub: prashantsinghmangat

• npm: tracebug-sdk