tracebug-sdk
Advanced tools
Capture a bug, see the root cause, and create a GitHub issue in 5 seconds. Zero-backend, browser-only debugging assistant. Free Sentry/LogRocket alternative.
Bug reports your dev can actually open.
Local-first. One .html file with full replay, console errors,
network requests, and screenshots. Opens offline.
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.
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
↓
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.
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 |
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 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.
| 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 |
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:
| 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)localStorage — 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 32 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.