tracebug

TraceBug

バグを記録。AI に修正させましょう。
ローカルファーストで、バックエンドは不要です。1 つの .html ファイルに、完全なリプレイ、コンソールエラー、ネットワークリクエスト、再現タイムラインが含まれます。AI コーディングエージェントが MCP 経由で内容を読み取り、修正します。人間もオフラインで開けます。

▶ 15 秒のデモを見る · Claude が実際のバグをデバッグする様子を見る · サンドボックスで実際に試す

---

TraceBug はローカルファーストのデバッグアシスタントです。バグを記録 → 自己完結した単一の .html ファイルを作成 → AI コーディングエージェント（Claude Code、Cursor、Windsurf）に渡します。エージェントはローカル MCP サーバー経由で証拠を読み取り、バグを修正します。または、オフラインで開けるファイルを人間の開発者にメールや Slack で送れます。各レポートには、エージェントが実行して修正を検証する失敗テストも埋め込まれています。

各レポートを開くと、次の内容が表示されます。

🔍 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

アカウントは不要です。SaaS に縛られることもありません。デフォルトでは、データはブラウザー内に保持されます。

任意のクラウド共有（実装済み、デフォルトでは UI で無効）：ファイルではなく URL で共有したい場合は、一度サインインするだけで、同じコンテンツを含む共有リンクを取得できます。コードは機能フラグ（PHASE2-CLOUD）で無効化されています。ポータルが有効になるまで、共有ボタンは無効のままです。現在、サポートされている共有方法はローカルの .html エクスポートです。

あらゆるフロントエンドフレームワークで動作します：React、Angular、Vue、Next.js、Nuxt、Vite、Svelte、SvelteKit、Remix、Astro、またはプレーンな HTML に対応しています。

⚡ 30 秒で始める

初めてですか？2 分で最初のバグを報告する →

npx tracebug init

これで完了です。CLI がフレームワークを検出し、正確な 2 行のスニペットを表示します。アプリに貼り付けて npm run dev を実行すると、画面右端に TraceBug のツールバーが表示されます。

2 クリックでバグを報告：

1. Ctrl+Shift+B を押す（またはツールバーの ⚡ ボタンをクリックする）
2. 自動入力されたレポートを確認し、**「GitHub Issue をコピー」**をクリックする
3. リポジトリに貼り付ければ完了です。

TraceBug の機能

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.

ページをスキャン（axe-core による a11y、壊れた画像、混在コンテンツ、フラストレーションの兆候、失敗または低速な API、JS エラー）は、TraceBug.scanPage() としてプログラムから利用できます。ツールバーのボタンではなくなりました。

TraceBug の 2 つの使い方

オプション 1：npm パッケージ（開発者向け）

SDK をプロジェクトにインストールします。開発環境やステージング環境で TraceBug を常に有効にしたいチームに最適です。

npm install tracebug-sdk

import TraceBug from "tracebug-sdk";
TraceBug.init({ projectId: "my-app" });

オプション 2：Chrome 拡張機能（開発者以外向け）

ブラウザー拡張機能をインストールするだけで使えます。コードは不要です。QA テスター、PM、クライアントはあらゆるウェブサイトで使用できます。

Chrome ウェブストアからインストール — ワンクリックですぐに使えます。

ブラウザー	対応状況
Chrome	はい — Chrome ウェブストアからインストール
Edge	はい — Chrome ウェブストアの拡張機能がネイティブに動作します
Brave	はい — Chrome ウェブストアの拡張機能がネイティブに動作します
Opera	はい — 先に「Install Chrome Extensions」アドオンをインストール
Firefox	未対応 — 代わりに npm SDK を使用してください

ブラウザーの対応状況

ブラウザー	npm SDK	拡張機能
Chrome	✅	✅
Edge	✅	✅
Brave / Opera	✅	✅
Firefox	✅	⏳（移植は一時停止中 — SDK のみ）
Safari	✅¹	❌（SDK のみ）

SDK はフレームワークやブラウザーに依存せず、最新の JS が動作する環境ならどこでも実行できます。 ¹ インタラクティブな DOM リプレイのエクスポートでは、ブラウザー標準の CompressionStream / DecompressionStream（Chrome 80+、Firefox 113+、Safari 16.4+）を使用します。古いエンジンでは エクスポーターがリプレイを圧縮せずに出力し、ビューアーは スクリーンショットギャラリーにフォールバックします。現在、拡張機能は Chromium のみをサポートしています（Firefox への移植は一時停止中で、 Safari 版はありません）。これらのブラウザーでは npm SDK を使用してください。

機能

🧠 デバッグアシスタント（v1.3）

各レポートには、4 つの推定シグナルが表示されます。「何が起きたか」を「なぜ起きた可能性が高いか」に変えます。

シグナル	表示例
🔍 根本原因のヒント	信頼度（高／中／低）とともに表示される "API POST /orders failed with 500 after clicking 'Place Order'"
TL;DR	ネットワーク、エラー、クリック、ページの各シグナルを組み合わせた 1 文の要約
ユーザーのクリック	バグ発生前の最後のクリックについて、タグ、テキスト、セレクター、id、aria-label、testId を表示
最近のアクション	直近約 10 件のユーザー操作を平易な英語で表示（"Clicked 'Edit' button"、"Navigated to /checkout"）

さらに、以下の機能もあります。

• ネットワークレスポンスの抜粋 — 失敗したすべての fetch／XHR レスポンス本文の先頭 200 文字を非同期で取得します（リクエストをブロックしません）
• メモリー内の失敗バッファー — 直近 10 件の失敗したリクエストに TraceBug.getNetworkFailures() からアクセスできます
• 決定的な処理 — 純粋関数を使用し、AI API は使わず、計算済みのレポートフィールドに対して O(1) で処理します

4 つのシグナルすべてが、GitHub のイシュー、Jira チケット、PDF レポート、Quick Bug モーダルにインラインで表示されます。出力例の全容はdocs/bug-reporting.mdを参照してください。

🤖 MCP サーバー — AI エージェントがバグレポートをデバッグします（v1.5）

コーディングエージェント（Claude Code、Cursor、Windsurf、VS Code）が TraceBug のバグレポートを読み取り、バグを修正します — すべてローカルで行われ、アップロードは一切ありません：

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

サーバーは、TraceBug がエクスポートする自己完結型の .html ファイルを読み取ります。テスターがレポートファイルを開発者に渡し、開発者がリポジトリに配置すると、エージェントは 9 つのツールを利用できます：list_bug_reports、get_bug_report、get_console_errors、get_network_activity、get_repro_steps、get_screenshot（実際の画像コンテンツ）、get_playwright_test、resolve_stack、get_fix_context。get_bug_report は、レポートの内容に基づいて作成した、優先順位付きの調査ガイドを返すため、エージェントは次に呼び出すツールを正確に把握できます。コンソールのスタックトレース、失敗したリクエストの本文、再現手順、フラストレーションの兆候など、バグレポートから修正に至るまでにエージェントが必要とするすべてが揃っています。

最後の 3 つのツールが修正までのループを完結させます（v1.9）。get_playwright_test は、セッションを再現し、記録された失敗が解消されたことを検証する、生成済みの失敗する Playwright テスト仕様を返します。バグが修正されるまでは赤、修正後は緑になるため、エージェントはテストを実行して修正を適用し、緑になるまで再実行できます。resolve_stack は、サーバーの実行元リポジトリ内で見つかった .map ファイルを使い、レポートの圧縮済みスタックフレームを元のソースファイルと行に対応付けます。get_fix_context は、修正を始めるための情報を一度の呼び出しで提供します。失敗したリクエストとレスポンスの抜粋、リクエストを引き起こしたユーザー操作、ソースマップで解決したスタックフレームの先頭部分、失敗するテストが利用可能かどうかが含まれます。

開始するために必要なのは、1 回の貼り付けだけです。拡張機能は Export .html のたびに、すぐ使えるエージェント用プロンプトを表示し（自動コピーされます）、エクスポートしたファイル自体にも同じプロンプトが AI タブに含まれています。Claude Code では、/tracebug:debug_bug_report と入力するだけです。

他のツールの MCP サーバーはクラウドでホストされるため、まずバグデータを各サーバーに保存する必要があります。TraceBug のサーバーは stdio 経由でマシン上で動作し、ネットワーク接続は一切確立しません。すぐにお試しいただけるよう、このリポジトリにはデモレポートと、設定済みの .mcp.json が含まれています。docs/mcp.md をご覧ください。

🎭 Playwright Reporter — 失敗したテストからバグレポートを作成（v1.6）

失敗した Playwright テストはすべて、同じ自己完結型の .html バグレポートになります。アサーションエラーとコードスニペット、再現手順としてのステップのタイムライン、ページのコンソールとネットワーク（オプションのフィクスチャ経由）、失敗時のスクリーンショット、根本原因のヒントが含まれます。bug-reports/ を CI アーティファクトとしてアップロードし、MCP サーバー経由でエージェントにデバッグさせましょう：

// playwright.config.ts — that's the whole setup
reporter: [["list"], ["tracebug-sdk/playwright", { outputDir: "bug-reports" }]],

テスト実行時のバグを、持ち運び可能なファイルとして記録できるツールは他にありません。クラウドツールでは、CI アーティファクトにビューアーを添付できないからです。docs/playwright.md をご覧ください。

🧠 AI Debugger — 自分のキーを使った LLM 分析（v1.6）

自分のキーを使って、Anthropic、OpenAI、ローカルの Ollama による本格的な LLM 根本原因分析を実行できます。呼び出しはブラウザーからプロバイダーへ直接送信されます。TraceBug がキー、プロンプト、応答を参照することはなく、ページを離れる前にプロンプトから秘密情報のパターンが除去されます。従量課金のクレジットも、ベンダーのクラウドを経由することもありません。

ローカルのヒューリスティックによるヒントおよびローカルの MCP サーバーと組み合わせれば、ホームに情報を送信しない AI デバッグを実現できます。これは、クラウドでホストされ、従量課金の競合製品にはまねできない立ち位置です。docs/ai-debugger.md をご覧ください。

🌐 HAR エクスポート（v1.6）

ワンクリックで、記録したネットワークアクティビティを、DevTools、Charles、Fiddler、Postman で開ける標準の HAR 1.2 ファイルとしてエクスポートできます。この機能を提供する競合製品はありません。Jam は「HAR が提供するすべて」をうたっているにもかかわらず、エクスポート機能はありません。ネットワークの記録は、誰かのクラウドに保存されたデータ行ではなく、お客様が所有する持ち運び可能なファイルです。docs/har-export.md をご覧ください。

🧪 生成される失敗再現 Playwright テスト（v1.9）

すべてのエクスポートには、記録されたセッションを再生する実行可能な Playwright spec が含まれます（ロケーターは data-testid → id → aria-label → role+name → 記録された CSS セレクターの順に優先されます）。また、記録された失敗が解消されたことをアサートします。つまり、失敗していたエンドポイントが失敗しなくなり、コンソールエラーが出なくなることを確認します。バグがある間は赤、修正後は緑になります。入手方法は3つあります。Quick Bug More メニューの Download failing test (.spec.ts)、.html エクスポートへの埋め込み、または MCP get_playwright_test ツールです。エージェントはこれを実行して修正を適用し、緑になるまで再実行できます。

🔎 インスペクトモード — デザインQAのバグに対するスタイルの証拠（v1.9）

「ボタンの見た目がおかしい」という報告に、根拠が付くようになりました。DevTools風のインスペクトモード（拡張機能のポップアップ → Inspect element、または TraceBug.activateInspectMode()）では、ホバーするとボックスモデルのハイライトと算出スタイルの概要ツールチップが表示されます。クリックすると要素がレポートに添付され、タイポグラフィ、16進数表記の色、ボックスモデルを含む厳選されたスタイルスナップショットに加えて、WCAG テキストコントラスト判定（比率とAAの合否）が記録されます。注釈カード、生成された GitHub イシュー、エクスポートに表示され、MCP エージェントが get_bug_report から取得する構造化データにも含まれます。

🎬 録画前のオプション＋要素単位のぼかし（v1.9）

拡張機能のポップアップにある ⚙ Record options パネルでは、任意の3秒／5秒のカウントダウンと Blur before recording を設定できます。最初のフレームをキャプチャする前に、機密領域をマスキングできます。（キャプチャ対象とマイクの行は画面録画について説明するもので、1.11の拡張機能では一時停止され、1.11.1で再び利用可能になります。）一式の機能は公開 SDK API から利用でき、動画は現在動作します：TraceBug.prepareRecording({ blurFirst, delaySec, surfaceMode, withMicrophone })。

ぼかしは要素単位で、クリックして適用します。ホバーするとハイライトされ、クリックすると要素自体に filter: blur(12px) が適用され、もう一度クリックするとぼかしが解除されます。ぼかしは要素自身の描画に含まれるため、スクロールに物理的に遅れることはありません。ぼかした要素には tb-mask も設定されるため、DOM再生では動画のピクセルだけでなく、そのテキストもマスキングされます。

📦 受け取った人が対応できるレポート（v1.8）

• Download .zip (attach to GitHub) — 同じオフライン再生を .zip にまとめたものです。GitHub イシューでは .zip の添付をドラッグ＆ドロップで受け付けますが、.html 単体は受け付けないためです。
• エクスポートしたレポート内のイシュー操作 — ビューアーのヘッダーには Open GitHub issue（エクスポーターで githubRepo が設定されている場合は、入力済みURLを使用）と Copy issue markdown（完全オフラインで、任意のトラッカーに貼り付け可能）があります。どちらも、すでに機密情報を削除したレポートをもとに、エクスポート時に事前計算されます。

自動キャプチャ（手間いらず）

項目	詳細
クリック	要素のタグ、テキスト、id、className、aria-label、role、data-testid、href、ボタンの種類
入力	フィールド名、種類、値（機密フィールドは自動的にマスキング）、プレースホルダー
ドロップダウン	選択されたオプションのテキストと値、利用可能なすべてのオプション
フォーム送信	フォームの id、action、method、すべてのフィールド値（パスワードはマスキング）
ナビゲーション	遷移元 → 遷移先のルート（pushState、replaceState、popstate に対応）
API リクエスト	URL、method、ステータスコード、応答時間（fetch と XMLHttpRequest の両方）
エラー	メッセージ、スタックトレース、ソースファイル、行、列
コンソール	console.error + warn + info + log（エラー以外の各レベルはセッションごとに最大50件）。warn/info は再現タイムラインに表示されます
未処理の拒否	Promise の拒否理由とスタック
環境	ブラウザー、OS、ビューポート、デバイスの種類、接続、言語、タイムゾーン

Sentry モード — ローリングビデオバッファ

QA セッションの開始時に録画を一度クリックするだけで、同じ画面共有からバグチケットをいくつでも作成できます。NVIDIA Shadowplay / OBS のリプレイバッファに着想を得ています。

機能	内容
一度だけ選択	録画をクリック → OS のダイアログで画面／ウィンドウ／タブを選択します。HUD が表示されたら、通常どおり QA を行います。
📸 キャプチャボタン	進行中の録画を完成した .webm として切り出し、チケットモーダルを開きます。録画は続行されます。
タイムスタンプ付きコメント	HUD にメモを入力 → Enter キーを押すと、現在の動画タイムスタンプとともに保存されます。
エラー発生時の自動キャプチャ	録画待機中に JS エラーが発生すると、エラートーストに「動画付きでキャプチャ」が表示されます。クリックするとバッファをキャプチャします。
スマート停止	1 回以上キャプチャしている場合、停止しても何も表示されません。キャプチャしていない場合は、全録画を含むモーダルが開きます。

自動スキャナー

スキャンをクリックすると、ブラウザー内の 6 つの検出器が並行して実行され、見落としていた可能性のある問題が表示されます。

検出器	検出内容
a11y	axe-core による WCAG 2.0/2.1 A+AA の違反
画像の読み込み失敗	読み込みに失敗した <img> 要素
混在コンテンツ	HTTPS ページ上の http:// リソース（CSP によるブロックまたはダウングレード）
JS エラー	重複を除外したコンソールエラーと未処理の拒否
リクエストの失敗	レスポンス本文の抜粋を含む、4xx／5xx／ネットワークエラーの API 呼び出し
低速 API	2 秒を超える正常な呼び出し

各問題には、場所を特定（該当要素を点滅表示）、チケットを作成（クイックバグモーダルに情報を事前入力）、非表示の操作があります。

QA ツール（一クリック）

ツール	内容
クイックバグキャプチャ	Ctrl+Shift+B で、タイトルと説明が自動入力されたチケット確認モーダルを開きます
スクリーンショット	自動生成された名前（例：01_click_add_vendor.png）でビューポートをキャプチャし、アクティブなチケットに追加します
範囲スクリーンショット	ドラッグして範囲を選択する、切り取りツール形式のキャプチャです。チケットに追加されます
音声メモ	バグの説明を音声で入力します — Web Speech API による音声テキスト変換を使用します
GitHub Issue	完全な GitHub マークダウンを生成します — クリップボードにコピーされ、スクリーンショットと .webm が自動ダウンロードされます
Jira チケット	優先度とラベルを含む Jira マークアップを生成します

プログラムから利用可能（v1.0 でデフォルト UI から削除）

これらの機能は引き続きバンドルに含まれますが、ツールバーのボタンはなくなりました。パワーユーザーは直接呼び出すことができます。

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

自動生成

出力	詳細
バグタイトル	セッションのコンテキストに基づくスマートなタイトル（例：「ベンダーの更新に失敗 — TypeError」）
再現手順	イベントタイムラインから生成される番号付きの手順
セッションタイムライン	すべてのイベントについて経過時間のタイムスタンプを含むデバッグタイムライン
環境スナップショット	ブラウザーのバージョン、OS、ビューポート、デバイスタイプ、接続状況

スマートフィルタリング

• SDK の自己フィルタリング：TraceBug は独自 UI の操作（ダッシュボード、注釈キャンバス、ボタンのクリック）を記録しません
• フレームワーク由来のノイズ除去：内部開発サーバーへのリクエスト（webpack HMR、Vite ping、Next.js のスタックフレーム）は、タイムラインとレポートから自動的に除外されます
• 重複エラーの除外：連続する同一のエラーはまとめられます

ユーザー識別とバグワークフロー

// 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..."

プラグインとフックのシステム

フォークせずに TraceBug を拡張できます — イベントのフィルタリング、レポートの強化、カスタムアクションの実行が可能です。

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 ヘルパー

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

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

インストール

npm から

npm install tracebug-sdk

GitHub から

npm install github:prashantsinghmangat/tracebug-ai

Chrome 拡張機能（コード不要）

下記のChrome 拡張機能のセクションをご覧ください。

設定

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 オプション

値	動作
"auto"	開発環境／ステージング環境では有効、本番環境では無効（デフォルト）
"development"	NODE_ENV が "development" の場合のみ
"staging"	開発環境とステージング環境（ホスト名に staging、stg、uat、qa のいずれかを含む）
"all"	本番環境を含め、常に有効
"off"	完全に無効
string[]	カスタムホスト名。例：["localhost", "staging.myapp.com"]

プログラム用 API

コア

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();
}

音声の文字起こしは、GitHub Issue、Jira Ticket、PDF レポートに自動的に含まれます。

テスターのメモ

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();

ダッシュボード

画面右端のコンパクトなツールバーでは、次の操作ができます。

• ⚡ クイックバグ — チケット確認モーダルを開きます（Ctrl+Shift+B）
• 📷 スクリーンショット — 注釈エディターでページをキャプチャします
• ▢ 領域 — 選択した領域をキャプチャします
• 🔴 録画 — 画面録画（Sentry モード：ローリングバッファ＋HUD）
• ⏺ セッションを記録 — 動画なしのイベントのみのキャプチャです（ページ遷移後も保持されます）
• ✓ 保存済みチケットを表示 — オフラインの保存済みチケット一覧を表示します
• ✕ — このページで TraceBug をオフにします

注釈モードと描画モードはバンドルに含まれていますが、v1.0 では単独のツールバーボタンとしての提供を終了しました。プログラムから、または録画 HUD のペンボタンから利用できます。docs/annotate-and-draw.md をご覧ください。

クイックバグモーダル

チケットを確認・編集してから、エクスポートまたは登録します。

• タイトル、概要、根本原因のヒント、再現手順、タイムラインを自動生成します
• インタラクティブな DOM リプレイ（または画面録画）、スクリーンショットギャラリー
• タブ：情報 · コンソール · ネットワーク · 操作 · AI · イベント
• エクスポート：.html をエクスポート（リプレイ） · AI 用にエクスポート（.html） · レポートをダウンロード（.md） · .zip をダウンロード（GitHub に添付可能） · 失敗したテストをダウンロード（.spec.ts） · HAR をエクスポート
• 直接登録：GitHub · Linear · Slack · Jira（トークンを設定すると実際の課題を登録できます）

キーボードショートカット

ショートカット	操作
Ctrl+Shift+B	クイックバグのチケットモーダルを開く
Ctrl+Shift+S	スクリーンショットを撮影する
Esc	現在のモードを終了／モーダルを閉じる

注：Ctrl+Shift+A（注釈）と Ctrl+Shift+D（描画）は、デフォルトでは割り当てられなくなりました。プログラム用 API（TraceBug.activateAnnotateMode()／activateDrawMode()）から引き続きモードを呼び出せます。また、描画モードは録画 HUD の ✎ ボタンからも利用できます。

ドキュメント

詳しいドキュメントは docs/ フォルダーにあります。

• はじめに — インストール、セットアップ、初回の使い方
• API リファレンス — プログラム用 API の全項目
• 設定 — すべての設定オプションの説明
• バグ報告 — スクリーンショット、メモ、音声、エクスポート
• MCP サーバー — AI エージェント（Claude Code、Cursor）にレポートのデバッグを任せる
• 注釈と描画 — UI の注釈機能
• Chrome 拡張機能 — 拡張機能のインストールと使い方
• アーキテクチャ — TraceBug の内部動作
• ADR — ローカルファースト、単一ファイルの HTML、rrweb、MV3、依存関係ゼロを採用した理由
• パフォーマンス — 実測値と再現可能なベンチマーク
• 互換性 — ブラウザの対応状況、サポートポリシー、既知の制限事項
• 移行ガイド — アップグレード時の注意点と API の安定性
• ロードマップ — リリース済み · 進行中 · 予定 · 長期計画

Chrome 拡張機能

TraceBug Chrome 拡張機能を使うと、開発者以外の方もコードを書かずに TraceBug の全機能を利用できます。

インストール方法

推奨： Chrome ウェブストアからインストール — Chrome、Edge、Brave、Opera で動作します。

ソースからインストール（開発者向け）：

1. このリポジトリを git clone し、npm install && npm run build を実行します
2. chrome://extensions/ を開く → デベロッパーモードを有効にする → パッケージ化されていない拡張機能を読み込む → tracebug-extension/ を選択します

使い方

1. 任意のウェブサイト（ステージング環境、本番環境、localhost、社内ツール）に移動します
2. ツールバーの TraceBug 拡張機能アイコンをクリックします
3. **「このサイトで有効にする」**をオンにします — TraceBug を有効にした状態でページが再読み込みされます
4. ページ上にフローティングのバグボタンが表示されます
5. スクリーンショット、メモ、GitHub/Jira の課題、PDF レポートなど、すべての QA ツールを使えます
6. 拡張機能のポップアップからもクイックアクションを利用できます

拡張機能の機能

• サイトごとの切り替え — テスト対象のサイトでのみ有効にできます
• バッジインジケーター — 現在のタブで有効な場合、「ON」を緑色で表示します
• クイックアクション — ポップアップから注釈、描画、スクリーンショット、PDF レポート、GitHub の課題、Jira チケットを利用できます
• 有効なサイトの一覧 — ポップアップから有効なすべてのサイトを管理できます
• ページ上のコンパクトなツールバー — npm SDK と同じフル機能のツールバーです
• CSP セーフ — Content Security Policy の制限を回避するため、world: "MAIN" を指定した chrome.scripting.executeScript を使用します

ブラウザーの互換性

ブラウザー	対応状況
Google Chrome	対応
Microsoft Edge	対応
Brave	対応
Opera	対応（先に「Install Chrome Extensions」アドオンをインストールしてください）
Firefox	未対応 — npm SDK をお使いください

Chrome ウェブストア

TraceBug は Chrome ウェブストアで公開されています。

TraceBug 拡張機能をインストール

ソースからビルド

# 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

サンプルのバグをテスト

1. /vendor に移動します
2. 「編集」をクリックします
3. ステータスを「Inactive」に変更します
4. 「更新」をクリックします — TypeError が発生します
5. バグボタンをクリックすると、再現手順を含むレポートが表示されます

プライバシー

• 機密フィールドは自動的にマスキングされます（password、secret、token、ssn、credit）
• キャプチャ時に、トークン形式に一致する約 20 種類のパターン（JWT、Bearer ヘッダー、クラウドプロバイダーのキー）をマスキングします — ログに記録されたシークレットがレポートオブジェクトに含まれることはありません
• エクスポートの手順とエクスポートされたレポートには、マスキングされた内容が正確に表示されます：🛡 N sensitive values auto-masked
• アプリ固有の PII は、設定内の redact: { fields, patterns } で保護できます — 拡張機能のポップアップにある 🛡「編集ルール」セクションからも設定できます
• すべてのデータは localStorage に保存され、TraceBug に送信されることはありません。GitHub、Linear、Slack、または AI プロバイダーに送信する内容は、ご自身で選択できます
• SDK は自身の UI 操作をキャプチャしません
• 外部サーバー、トラッキング、分析はありません

フレームワークの互換性

形式	ファイル	対応環境
ESM（import）	dist/index.js	Vite、Next.js、Nuxt、SvelteKit、モダンな webpack
CJS（require）	dist/index.cjs	Angular CLI、旧バージョンの webpack、Node.js
IIFE（グローバル）	tracebug-extension/tracebug-sdk.js	Chrome 拡張機能、通常の <script> タグ
TypeScript	dist/index.d.ts	ESM と CJS の両方で完全な型サポート

アンインストール

npm パッケージ

npm uninstall tracebug-sdk

その後、アプリのエントリーファイルから TraceBug.init() の呼び出しを削除します。

---

⭐ 時間を節約できたら、このリポジトリにスターを付けてください

TraceBug によって開発をより速く進められたなら、スターを付けていただくのが何よりのお礼になります。他の開発者にも見つけてもらいやすくなります。

ぜひ広めてください：

• Twitter/X でシェア
• LinkedIn でシェア
• Hacker News でシェア

バグを見つけた場合や、機能のアイデアがある場合は、issue を作成してください。TraceBug は、質の低いバグ報告を改善するために作られました。少しでも良くできるよう取り組んでいます。

---

❤ を込めて Prashant Singh Mangat が作成
_{MIT ライセンス · トラッキングなし · バックエンドなし · データはブラウザー内に保存されます}

Chrome 拡張機能

chrome://extensions/ に移動し、TraceBug の 削除 をクリックしてください。

ライセンス

MIT

作者

Prashant Singh Mangat

• GitHub：prashantsinghmangat
• npm：tracebug-sdk