tracebug-sdk
Advanced tools
Capture a browser bug into one offline .html file your AI coding agent reads over MCP and fixes — session replay, console, network, repro timeline, and a generated failing test. Local-first, zero backend. Free.
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 15-second demo · 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.
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:
Ctrl+Shift+B (or click the ⚡ button on the toolbar)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.
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" });
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 |
| Browser | npm SDK | Extension |
|---|---|---|
| Chrome | ✅ | ✅ |
| Edge | ✅ | ✅ |
| Brave / Opera | ✅ | ✅ |
| Firefox | ✅ | ⏳ (port paused — SDK only) |
| Safari | ✅¹ | ❌ (SDK only) |
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.
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:
fetch/XHR response body, captured asynchronously (never blocks the request)TraceBug.getNetworkFailures()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.
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.
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.
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.
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.
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.
"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.
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.
.zip, because GitHub issues accept .zip attachments by drag-and-drop but reject bare .html.githubRepo) and Copy issue markdown (fully offline, pastes into any tracker). Both are precomputed at export time from the already-redacted report.| 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 | console.error + warn + info + log (each non-error level capped at 50/session); warn/info render in the repro timeline |
| Unhandled Rejections | Promise rejection reason + stack |
| Environment | Browser, OS, viewport, device type, connection, language, timezone |
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. |
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.
| 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 |
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
| 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 |
// 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..."
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));
// In Playwright/Cypress tests
expect(TraceBug.getErrorCount()).toBe(0);
// Upload full session as test artifact on failure
const json = TraceBug.exportSessionJSON();
npm install tracebug-sdk
npm install github:prashantsinghmangat/tracebug-ai
See Chrome Extension section below.
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"] |
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();
// 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();
// 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.
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"
});
// 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", ... }
import { getAllSessions, clearAllSessions, deleteSession } from "tracebug-sdk";
const sessions = getAllSessions();
const bugs = sessions.filter(s => s.errorMessage);
clearAllSessions();
deleteSession("session-id");
import {
generateReproSteps,
captureEnvironment,
buildReport,
generateGitHubIssue,
generateJiraTicket,
generateBugTitle,
buildTimeline,
formatTimelineText,
} from "tracebug-sdk";
// 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();
The compact toolbar on the right edge of the screen provides:
Ctrl+Shift+B)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.
Review and edit the ticket, then export or file it:
| 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) andCtrl+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.
Full documentation is in the docs/ folder:
The TraceBug Chrome Extension lets non-developers use all TraceBug features without writing code.
Recommended: Install from Chrome Web Store — works in Chrome, Edge, Brave, and Opera.
From source (for developers):
git clone this repo, then npm install && npm run buildchrome://extensions/ → Enable Developer mode → Load unpacked → select tracebug-extension/chrome.scripting.executeScript with world: "MAIN" to bypass Content Security Policy restrictions| 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 |
TraceBug is published on the Chrome Web Store:
# 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)
cd example-app
npm install
npm run dev
# Open http://localhost:3000
/vendorpassword, secret, token, ssn, credit)Bearer headers, cloud provider keys) — a logged secret never enters the report object🛡 N sensitive values auto-maskedredact: { fields, patterns } in config — also settable in the extension popup's 🛡 Redaction rules sectionlocalStorage — nothing leaves the browser| 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 |
npm uninstall tracebug-sdk
Then remove the TraceBug.init() call from your app's entry file.
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:
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.
Built with ❤ by Prashant Singh Mangat
MIT Licensed · No tracking · No backend · Your data stays in your browser
Go to chrome://extensions/ → click Remove on TraceBug.
MIT
Prashant Singh Mangat
FAQs
Capture a browser bug into one offline .html file your AI coding agent reads over MCP and fixes — session replay, console, network, repro timeline, and a generated failing test. Local-first, zero backend. Free.
The npm package tracebug-sdk receives a total of 43 weekly downloads. As such, tracebug-sdk popularity was classified as not popular.
We found that tracebug-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A new federal program will let vetted U.S. cybersecurity firms help investigate and disrupt foreign cybercrime groups under government direction.
Research
/Security News
The campaign amassed more than 75,000 installs by targeting Russian-speaking users seeking access to blocked services.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.