TraceBug is a local-first debugging assistant. Capture a bug → produce a single self-contained .html file → email/Slack it to a dev → they open it offline and see exactly what happened.

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 (coming in a future release — not in v1.3): if you'd rather share a URL than a file, sign in once and get a tracebug.netlify.app/share/<id> link with the same content. The code ships behind a feature flag today; the Share button is disabled until the portal launches. Local .html export is the supported sharing path in v1.3.

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

⚡ Get Started in 30 Seconds

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 as GitHub Issue"
3. Paste into your repo. Done.

What TraceBug Does

Tester opens the page
  ↓
SDK silently captures: clicks, inputs, navigation, API calls, errors, environment
  ↓
Three primary toolbar actions cover the main workflows:
  • ⚡ Quick Bug   — Ctrl+Shift+B opens the ticket-review modal
  • 🔍 Scan Page   — runs in-browser detectors (a11y via axe-core, broken
                     images, mixed content, frustration signals like rage/dead
                     clicks, plus failed APIs, slow APIs, and JS errors from
                     the session) → opens issues panel
  • 🔴 Record      — arms Sentry mode: rolling video buffer + HUD with
                     timestamped comments. File multiple bugs from one
                     screen-share without re-picking
  ↓
Click "Copy as GitHub Issue" or "Copy as Jira Ticket"
  ↓
Complete bug report copied to clipboard:
  - Auto-generated title + smart summary + root-cause hint (high/medium/low confidence)
  - Steps to reproduce
  - Screenshots, screen recording (.webm) with timestamped comments
  - Console errors + stack traces, failed network requests with response snippets
  - Environment (browser, OS, viewport, device)
  - Full session timeline
  ↓
Paste into GitHub/Jira → screenshots + .webm auto-download. Developer has everything.

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 | Supported | |---------|-----------| | Chrome | Yes — install from Chrome Web Store | | Edge | Yes — Chrome Web Store extensions work natively | | Brave | Yes — Chrome Web Store extensions work natively | | Opera | Yes — install "Install Chrome Extensions" add-on first | | Firefox | Not yet — use the npm SDK instead |

Features

🧠 Debugging Assistant (v1.3)

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

| Signal | What it looks like | |---|---| | 🔍 Root Cause Hint | "API POST /orders failed with 500 after clicking 'Place Order'" with confidence tier (high/medium/low) | | TL;DR | One-sentence summary combining network + error + click + page signals | | User clicked | Tag, text, selector, id, aria-label, testId for the last click before the bug | | Recent Actions | Last ~10 user actions as plain-English steps ("Clicked 'Edit' button", "Navigated to /checkout") |

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 six tools: list_bug_reports, get_bug_report, get_console_errors, get_network_activity, get_repro_steps, and get_screenshot (real image content). 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.

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.

Auto-Captured (Zero Effort)

| What | Details | |------|---------| | Clicks | Element tag, text, id, className, aria-label, role, data-testid, href, button type | | Inputs | Field name, type, value (sensitive fields auto-redacted), placeholder | | Dropdowns | Selected option text + value, all available options | | Form Submits | Form id, action, method, all field values (passwords redacted) | | Navigation | Route from → to (supports pushState, replaceState, popstate) | | API Requests | URL, method, status code, response time (both fetch and XMLHttpRequest) | | Errors | Message, stack trace, source file, line, column | | Console Errors | console.error() calls | | Unhandled Rejections | Promise rejection reason + stack | | Environment | Browser, OS, viewport, device type, connection, language, timezone |

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.

| Feature | What it does | |---|---| | One-time picker | Click Record → pick screen/window/tab in the OS dialog. The HUD appears; you do QA normally. | | 📸 Capture button | Snapshots the in-progress recording into a finished .webm and opens the ticket modal. Recording keeps running. | | Timestamped comments | Type a note in the HUD → press Enter → it's saved with the current video timestamp. | | Auto-capture on error | When a JS error fires while armed, the error toast offers "Capture with video" — one click captures the buffer. | | Smart Stop | If you took at least one capture, Stop ends silently. Otherwise it opens the modal with the full recording. |

Auto-Scanner

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

| Detector | What it catches | |---|---| | a11y | WCAG 2.0/2.1 A+AA violations via axe-core | | Broken images | <img> elements that failed to load | | Mixed content | http:// resources on HTTPS pages (CSP-blocked or downgraded) | | JS errors | Deduped console errors + unhandled rejections | | Failed requests | 4xx/5xx/network-error API calls with response body snippets | | Slow APIs | Successful calls over 2s |

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

QA Tools (One Click)

| Tool | What it does | |------|-------------| | Quick Bug Capture | Ctrl+Shift+B opens the ticket-review modal with auto-filled title + description | | Screenshot | Captures viewport with auto-generated name (e.g., 01_click_add_vendor.png); added to the active ticket | | Region Screenshot | Drag-to-select snipping-tool style; added to ticket | | Voice Note | Speak to describe the bug — speech-to-text via Web Speech API | | GitHub Issue | Generates complete GitHub markdown — copies to clipboard, screenshots + .webm auto-download | | Jira Ticket | Generates Jira markup with priority + labels |

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

| Output | Details | |--------|---------| | Bug Title | Smart title from session context (e.g., "Vendor Update Fails — TypeError") | | Repro Steps | Numbered steps generated from event timeline | | Session Timeline | Debug timeline with elapsed timestamps for every event | | Environment Snapshot | Browser version, OS, viewport, device type, connection |

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: "[email protected]", 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

| Value | Behavior | |-------|----------| | "auto" | Enabled in dev/staging, disabled in production (default) | | "development" | Only when NODE_ENV is "development" | | "staging" | Dev + staging hosts (staging, stg, uat, qa in hostname) | | "all" | Always enabled, including production | | "off" | Completely disabled | | string[] | Custom hostnames, e.g. ["localhost", "staging.myapp.com"] |

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:

• Session panel (logo button) — Full bug reporting with timeline, errors, export
• Annotate mode — Click elements to attach feedback
• Draw mode — Draw rectangles/ellipses for layout issues
• Screenshot — Capture with annotation editor
• Annotation list — View/export/delete all annotations
• Settings — Pause recording, view stats, clear data

Session Panel Details

• Session list with error/healthy indicators and "Repro Ready" badges
• QA Toolbar: Screenshot, Add Note, Voice Note, GitHub Issue, Jira Ticket, PDF Report
• Session overview, problems detected, error details, performance insights
• Tester notes, screenshots gallery, environment info
• Color-coded event timeline with rich details
• Auto-generated reproduction steps with copy button
• Export: JSON, Text, HTML, PDF, GitHub Issue, Jira Ticket

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Ctrl+Shift+B | Open the Quick Bug ticket modal | | Ctrl+Shift+S | Take a screenshot | | Esc | Exit the current mode / close the modal |

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

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

| Browser | Supported | |---------|-----------| | Google Chrome | Yes | | Microsoft Edge | Yes | | Brave | Yes | | Opera | Yes (install "Install Chrome Extensions" add-on first) | | Firefox | Not yet — use the npm SDK |

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)
• 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

| Format | File | Works with | |--------|------|------------| | ESM (import) | dist/index.js | Vite, Next.js, Nuxt, SvelteKit, modern webpack | | CJS (require) | dist/index.cjs | Angular CLI, older webpack, Node.js | | IIFE (global) | tracebug-extension/tracebug-sdk.js | Chrome Extension, plain <script> tag | | TypeScript | dist/index.d.ts | Full type support in both ESM and CJS |

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