BugShot

English · 한국어

Bug Reporting in One Shot.

Open-source bug reporting from your browser, straight to your tracker.

BugShot is a Chrome side panel that captures what happened — screenshots, recordings, console and network logs, user actions, environment details, and even CSS before/after diffs — and turns it into a report for Jira, GitHub, Linear, Notion, GitLab, Asana, ClickUp, Slack — or a server of your own over a custom webhook.

No BugShot account. No hosted workspace. Your capture data never passes through a BugShot server. BugShot is free, with no paid tier planned: there is no capture backend to run, no usage to meter, and no hosting bill to recover.

Install from the Chrome Web Store · Read the docs · Privacy

From a visible bug to an actionable report

1. Capture the problem — pick an element, take a screenshot, or record it.
2. Collect the evidence — environment, console, network, and action logs are attached automatically.
3. Send it where work happens — review the report and submit it directly to your tracker or Slack.

Why I built it

I'm a product designer. When I found a UI bug, I used to inspect the page in DevTools, change the CSS, take screenshots, move over to Jira, and manually build a before/after table for the issue.

That was tedious, so I made a tool that let me finish the whole workflow in one place and send the result to Jira in the format I wanted.

As I used it at work, our QA team asked if it could handle general bug reports too. That added screenshots and recordings, followed by network requests, console logs, and the rest of the evidence needed to reproduce a bug. It became an internal tool for the QA team; I still use it every day and keep improving it.

What started as a way to avoid making CSS diff tables by hand grew into this product in its first three months.

Privacy by architecture

Bug reports can contain some of the most sensitive parts of a production session: customer data in screenshots, tokens in network traffic, internal identifiers in console output, and the contents of form interactions.

I didn't want BugShot to become another server that received and stored that data. These are the core data paths:

Your browser ────────────────────────→ Your tracker, Slack, or webhook server
     │
     ├── when you use AI ────────────→ The LLM endpoint you selected
     │
     ├── OAuth exchange only ────────→ BugShot OAuth proxy
     │
     └── anonymous usage events ─────→ PostHog (via a proxy domain we own)

Screenshots, recordings, logs, CSS changes, attachments, and report bodies are assembled in the extension and sent directly to the destination you connected. For Jira, GitHub, Notion, Asana, ClickUp, and Slack, the BugShot-operated OAuth proxy relays authorization-code exchanges, and token refreshes for those three (Jira, GitHub, Asana). Linear and GitLab exchange and refresh tokens directly via PKCE, with no proxy in the path — five of the eight expire and refresh; Notion, ClickUp, and Slack issue tokens that don't. (GitHub depends on how its OAuth app is configured: with token expiration off, its tokens don't expire either.) Capture data never goes through the proxy. Anonymous analytics contain no capture or report content. Those events leave through in.bug-shot.com, a domain we own whose DNS record points straight at PostHog Cloud — it exists so ad and DNS blockers don't silently drop the numbers, and no BugShot server sits on that path either.

This has deliberate trade-offs: there is no BugShot account, team workspace, cloud sync, or server-side capture processing. The project is open source so you can inspect that architecture instead of taking the privacy claim on trust.

See every external request BugShot makes.

Getting Started

Requires Chrome 116 or later. Other Chromium browsers that ship the Side Panel API (Edge, Brave, Arc) should work, but Chrome is what's tested. There is no Firefox or Safari build — the whole UI is a Chrome MV3 side panel, and neither browser implements that API.

1. Install from the Chrome Web Store.
2. Open the panel — click the toolbar icon, press Cmd/Ctrl+Shift+E, or pick BugShot from the page's right-click menu.
3. Connect a destination — choose a tracker, Slack, or a custom webhook in the Integrations tab.
4. Capture — edit an element's styles, capture an element or area, take a viewport or full-page screenshot, or record the tab or screen. You can also start a report without a capture — from the capture screen's footer, or from the console and network log tabs.
5. Submit — review the evidence and send the completed report.

Full walkthrough in the Quick Start guide.

Features

🎨 Styling

Fix the bug visually before you even describe it.

• Element picker — hover to highlight, click to select an element on the page. The hover overlay paints margin (amber), padding (green), and flex/grid gaps (purple) with per-side pixel labels, beside an info card carrying the tag and classes, w × h, color and background swatches, font, and radius — the DevTools trip you're not taking. Works on nested and deeply styled elements; elements inside a shadow root resolve to their host (the browser's own hit-testing, not something we special-case), and pseudo-elements are not hit-testable.
• DOM tree navigation — can't reach it by hovering? Browse the live DOM tree in a dialog and pick the node directly, or step to its parent or first child — for wrappers and elements buried under an overlay.
• Live CSS editing — edit layout, spacing, sizing, color, typography, borders, and more through structured fields, or switch to a syntax-highlighted CSS code editor — prefilled with the element's current styles (four-side longhands merged into shorthands), with autocomplete and inline color swatches — to edit raw CSS directly (arbitrary properties, !important). Changes apply to the live page instantly, so you can dial in the exact fix and see it in place.
• Class & text editing — edit an element's class list or visible text live; those changes are tracked alongside its style diff.
• Design token awareness — resolves var() chains and shows the token name (e.g. --color-primary) instead of the raw computed value, so the report speaks your design system's language. When editing a value, you can pick one of the page's tokens instead of typing a raw value.
• Before/after diff — every change is tracked and rendered as a before → after table in the issue, plus paired before/after screenshots that widen to the enclosing dialog or table row so the fix is recognizable at a glance. Developers see exactly which properties to change. Both images can be annotated so you can point at the offending element even when the frame holds several, and removing an annotation restores the shot you originally captured. Edits across multiple elements are stacked and preserved until you submit.

📸 Capture

Grab exactly what's on screen and mark it up.

• Element capture — click an element to crop it, then use Add element while drafting to capture more from the same page. Images and DOM selectors stay in selection order, including repeated selections; annotate, download or delete each image individually.
• Works inside iframes — the picker reaches one level into embedded frames, cross-origin ones included.
• Area capture — drag any region of the screen to capture a precise slice.
• Screen capture — grab the whole visible viewport in one click, no dragging.
• Full-page capture — scroll and stitch the entire page into one tall screenshot; fixed and sticky headers are printed once, and very long pages stop at a limit with a notice.
• Annotation — mark up the shot with arrows, a freehand pen, text, shapes, and highlights before attaching it. Zoom (fit-to-width up to 400%) and pan the canvas so you can annotate fine detail on a tall full-page shot; the finished image is always attached at its original resolution.
• Inline evidence — capture an extra area or paste, drop, or add images directly into a body section, then annotate, restore, or delete them in place.

🎬 Recording

When a still image isn't enough, record the behavior.

• Tab recording — record the current tab, up to 2 minutes, encoded to MP4 (WebM fallback where MP4 isn't supported).
• Screen recording — record any window or the full screen via the system picker, up to 2 minutes. Which of the two the record button starts is a setting (Settings → Issue settings → Recording), not two separate buttons.
• Draw while recording — a mini toolbar (pen, box, or highlighter; up to 5 colors, fewer on a narrow panel; three thicknesses) lets you mark up the page during tab/screen recording. Freehand strokes fade tail-first in draw order over ~3s; a box fades all at once. Either way it's baked into the video.
• 30s Replay — an opt-in buffer that holds the last 30 seconds of frames in memory while the panel is open and idle on the active tab, then encodes them to MP4 when you capture. It looks back across page navigations, so you can catch the bug even after spotting it — no need to hit record beforehand.
• Trim before you file — stopping any recording (tab, screen, or 30s Replay) opens a trim screen. Drag the handles to keep just the bug moment, and the attached console, network, and action logs are narrowed to the same range. Leave the handles alone and nothing is re-encoded; if re-encoding fails, the original clip is attached as is.

📋 Logs

Reproduction context, collected for you in the background.

• Network & console logs — captured automatically while the panel is open and attached to the issue. Includes WebSocket frames and logs from cross-origin iframes (payment widgets, embeds), all filterable by origin. Sensitive headers (authorization, cookie, CSRF and x-*-token families), secrets in URL queries and fragments, and body keys like token / password / client_secret are masked at capture time — and the masking survives into Copy as cURL.
• Action log — clicks, text input, navigations, keyboard shortcuts, checkbox/radio toggles, dropdown selections, and drag & drop recorded as step-by-step reproduction. Sensitive values are masked, both by field label and by value shape (emails, long digit runs); rich-text editor content is never recorded.
• Add a log to the body — pick one console or network entry and drop it into the issue body as a code block (JSON pretty-printed and highlighted), right where you're describing the symptom. The attachment only opens after a download; this reads in the issue itself.
• API hosts in the environment — hosts from the network log that share a domain with the page are filled into the issue environment automatically, so a reader knows which server to look at without downloading the attachment. It is an ordinary row, so edit or delete it if it is not what you want.
• Live inspector in the panel — console and network logs are readable while you work, not only after export: live counts, type and level filters, URL and body search, request/response headers and payloads in a JSON tree, stack traces, and Copy as cURL.
• Reproduction environment — OS, browser version, page URL, the element's selector, viewport W × H, and capture time are filled into every report. These automatic metadata rows are read-only. You can add custom rows and edit or delete those rows and the API Hosts row.
• Log viewer — a standalone logs.html report with a video-synced timeline: click any console/network/action entry to jump to that exact moment in the recording. It also carries a Report tab (issue body preview + copy as markdown) and per-tab exports (HAR, console/action JSON).

All three logs ride along with every capture except element style editing, and the whole logs.html bundle can be toggled off with one switch before you submit (also toggleable on already-saved issues).

🤖 AI

• AI draft — BYOK (Bring Your Own Key) with OpenAI, Anthropic, Gemini, and more — or a local endpoint like Ollama, so the AI step can stay on your machine too; falls back to Chrome Built-in AI when no key is set and the model is ready for your interface language. Prepare a missing model explicitly in AI settings. Korean output requires a Korean-capable connected LLM; it is never silently replaced with English. No key yet? Connect free AI opens Google AI Studio to issue a free Gemini key, or signs you in to OpenRouter and issues a key automatically (free vision models only) — free tiers may use or log prompts, and the dialog says so before you connect. Drafts the title and body from your capture (styles, screenshot, or log summary) in one go. When the AI cites a relevant error log, the actual console/network entry is inserted into the body as a code block — serialized by the app, so log contents can't be hallucinated. With your own remote key, the capture screenshot goes in as an image and the drafting language is yours to pick, set independently of the interface language; Chrome Built-in AI and local endpoints are text-only and follow the interface language.
• AI styling — describe the fix in words and the AI writes the CSS onto the selected element, live on the page.
• Repro auto-fill — on by default whenever an AI is available, Chrome Built-in AI included: after a recording, the steps-to-reproduce section is written for you from the action log. With a connected remote AI, that means the action log is sent to it; Chrome Built-in AI processes it on-device. Turn it off under Settings → Issue settings → Other.

📥 Issue list & drafts

• Submitted issues — reports you've filed stay in the Issues tab with their platform badges, searchable and filterable by submitted/draft. Custom Webhook JSON template sends do not create an issue-history entry. Refresh to pull the current state back from the tracker, or change the status right from the panel and have it written back. Reports shared to Slack can be promoted to a tracker issue later, and the original Slack thread gets a reply with the new issue's URL.
• Attachment recovery — if some attachments fail, check each file's status, retry supported steps, or download the retained original files.
• Drafts — not ready to file? Save the report as a draft, reopen it later, edit any field, and submit when it's ready.

🔗 Integrations

Connect via OAuth or a token. Every tracker supports destination selection and attachment upload. GitHub uploads require a signed-in github.com session; GitLab uploads use the PAT or OAuth token from your connected account. Assignee covers every tracker except Notion; label selection is GitHub, Linear and GitLab only. Slack is a messenger rather than a tracker — it sends to a channel or DM instead. A custom webhook sends the report to a server you run, as described in the webhook contract.

Set defaults once in the Integrations tab — destination (project, repo, team, workspace, database, channel) plus assignee, label, issue type (Jira), and status / select properties (Notion) — and every new report comes pre-filled. File to the same destination again and whoever you assigned last wins over the default, so the common case stays one click; switch destination and the default takes over. CC is not a default either: it carries over from your last submission to that same destination, and is dropped when you switch.

Platform	Auth	Highlights
Jira	OAuth 3LO / API Token	project metadata, sprint picker, priority, parent epic, linked issue, auto-upload attachments
GitHub	OAuth / PAT	repo, labels, assignees, file upload (needs a signed-in github.com session)
Linear	OAuth PKCE / API Key	team, project, labels, priority
Notion	OAuth / Internal Token	database picker, status & select properties
GitLab	OAuth PKCE (gitlab.com only) / PAT	gitlab.com + self-managed instances
Asana	OAuth / PAT	workspace, project, assignee
ClickUp	OAuth / API Token	workspace → space → list, assignee
Slack	OAuth (user token)	channel/DM, @mentions, title + threaded details & files
Custom Webhook	URL + optional Bearer secret	multipart (files + cid: references, adds an issue-list row) or JSON template (no media, no history), custom headers, test send

🌐 Export & i18n

• Markdown copy — paste into Slack, Confluence, or anywhere with tables intact
• File attachments — attach your own files to the report, uploaded natively to the tracker (opt-in — Settings → Issue settings → Other)
• Local download — save the captured screenshot/video and the logs.html report
• i18n — Korean / English / French / Spanish / German / Japanese. The issue body has its own language setting, separate from the interface and from the AI drafting language
• Report body composition — toggle which sections (description, steps to reproduce, expected result, notes) go into the issue and drag them into the order you want, media and logs included; plus a title prefix
• Theme — light / dark / system

Development

pnpm install
pnpm dev          # dev server (HMR via @crxjs/vite-plugin)
pnpm build        # production build → dist/ (runs build:log-viewer first)
pnpm build:log-viewer  # log viewer bundle only (build/build:store/build:e2e run it automatically)
pnpm build:store  # store upload build (strips manifest key)
pnpm preview      # preview the production build
pnpm typecheck    # type check only
pnpm test         # unit tests (Vitest)
pnpm test:watch   # unit tests in watch mode
pnpm build:e2e    # e2e-only build → dist-e2e/ (test fixture — never load/upload)
pnpm test:e2e     # Playwright e2e suite (run build:e2e first)
pnpm test:coverage # coverage report
pnpm check:prearm # verify the recorder pre-arm chunk stayed a sync IIFE (CI gate)
pnpm sync:agents  # regenerate the Codex mirror (AGENTS.md, .agents/skills/)
pnpm sync:agents:check # fail if the mirror drifted (CI gate)

Load the unpacked extension from dist/ at chrome://extensions (developer mode). Opening the panel page (src/sidepanel/index.html) in a regular tab runs it in tab mode for browser automation agents; their manual is embedded in that page's source (#__BUGSHOT_AGENT__). The e2e suite lives in e2e/ — see e2e/README.md for coverage and gotchas. Patches are welcome: CONTRIBUTING.md covers which branch to target, what CI checks, and what won't be merged.

Build it yourself

Don't take the privacy claim on faith — build from source and watch the network tab:

git clone https://github.com/SinhyeokKang/bugshot-2.git
cd bugshot-2
pnpm install
cp .env.example .env.local   # optional — see below
pnpm build

Then load dist/ as an unpacked extension. Every key in .env.example is optional for building: capture and token-based connections work without OAuth configuration. OAuth connections require their client IDs and, where applicable, the proxy URL. Slack is OAuth-only, so its connection requires OAuth configuration. Without a PostHog key, analytics is a no-op and the build makes zero analytics requests.

Open DevTools on the side panel and inspect BugShot’s service worker from chrome://extensions. GitHub file uploads run in a dedicated github.com tab; inspect that tab for its upload requests. Compare the requests against the transmission table — the only BugShot-operated endpoint in the whole list is the OAuth token-exchange proxy, which relays the code→token swap and token refreshes and never carries capture data.

Stack

Runtime	Chrome MV3 — Side Panel + Service Worker + Content Script
UI	React 18, TypeScript, Tailwind CSS v3, shadcn/ui
State	Zustand + chrome.storage (session / local)
Build	Vite + @crxjs/vite-plugin
Test	Vitest (unit) · Playwright (e2e)

Architecture

The decisions that shaped the codebase, and what each one cost:

No backend, by construction. There is no BugShot server in the data path — not "we don't look at it," but nowhere to look. Captures, logs, and report bodies are assembled in the extension and POSTed straight to your tracker with your own credentials. The one BugShot-operated endpoint is a Cloudflare Worker that swaps an OAuth code for a token (and relays refreshes for Jira, GitHub, and Asana), because the client secret can't ship in a public bundle; Linear and GitLab skip even that via PKCE. The cost is real: no cross-device sync, no team workspace, no server-side processing — features that would each require breaking this property, so they don't get built.

Recorders are a synchronous IIFE, and that constrains the build. Console and network hooks have to be installed at document_start before the page's own inline scripts run, or the first errors are already gone. That only holds if the recorder chunk is self-contained — a single external static import turns it into an async loader and the hooks land too late. So the throttle helper is deliberately duplicated between the recorder and the side panel rather than shared, and a sessionStorage flag lets recording start buffering before the side panel has even connected.

Full-page capture is orchestrated across three contexts. The side panel drives it, a content-script executor scrolls the page, and each tile goes through the background worker's captureVisibleTab. Repeated fixed headers and late-appearing sticky elements are suppressed by visibility between tiles — including elements that appear or change position mid-capture — then the original styles and scroll offset are restored.

iframe support is one level deep, and says so. The picker is injected into all frames; a child registers with the top frame over postMessage and elements are identified by a selector + frameId composite key. Frames that don't register — nested two levels deep, or sandboxed — hit an explicit refusal path with a dialog rather than failing silently. The registration token is a correlation hint, not an authentication boundary: the child broadcasts it, so a hostile parent page can read it. That's a documented, accepted limit, not an oversight.

Styles are resolved against your design system. The CSS pipeline follows var() chains to report --color-primary instead of a computed RGB triple — which means fetching cross-origin stylesheets from the background worker at a page-supplied URL, i.e. an SSRF surface. It runs behind src/lib/ssrf-guard.ts: http(s) only, with loopback, private, link-local, CGNAT, multicast, IPv6 ULA, and IPv4-mapped-IPv6 bypasses all rejected. The caller in src/background/messages.ts adds the rest: credentials: "omit", redirect: "manual", a timeout, a content-type check, and size caps. One residual gap is documented in ssrf-guard.ts itself rather than papered over: a hostname that resolves to an internal address can't be caught statically, since fetch re-resolves DNS. The fetched CSS is used on-device only.

Eight platform integrations behind one adapter seam. Each platform gets its own auth (OAuth or token), field schema, and upload path, but the report body is built once and rendered per target — Markdown, Jira ADF, Notion blocks, Slack mrkdwn. A ninth target, the custom webhook, rides the same seam without an auth axis at all — the receiving server is the user's, so there is no token to exchange or refresh. In multipart mode, upload and creation share one request, so the body carries cid: references instead of URLs. JSON template mode sends only the rendered JSON, without file uploads or an issue-history entry.

Much of this can't be unit-tested — DOM measurement, pointer drags, canvas, and media APIs need a real browser — so a Playwright suite carries what Vitest can't, and the coverage metric deliberately excludes browser-bound files so the number stays an honest signal.

Full detail lives in docs/ARCHITECTURE.md (Korean).

Privacy

Every outbound request the extension can make is enumerated here — trackers, Slack, your webhook server, your LLM endpoint, the OAuth proxy, and analytics, plus a few auxiliary requests such as AI key issuance and stylesheet fetches — with the exact data each one carries:

• External transmission table — every destination, what it receives, and why
• Permissions notice — why the extension needs <all_urls>
• docs/PERMISSION.md — per-permission engineering reference: lifecycle, expiry, fallbacks (Korean)

Full policy: English · 한국어 · bug-shot.com

Why it asks for access to every site

Chrome renders this permission as "Read and change all your data on all websites" — the most alarming line in the install dialog, and it's required rather than optional. BugShot did ship the optional version first, requesting the permission at runtime, and it was dropped because it broke in use: captureVisibleTab runs on either activeTab or a broad host permission, and activeTab is revoked when the page navigates to a different origin, with no way to re-acquire it programmatically. A 30-second replay that relies on repeated captureVisibleTab calls would stop when the bug you were chasing crossed origins — which is precisely when you need it.

So the permission is broad. The data path isn't — everything it unlocks happens on your machine, and the transmission table above is the complete list of what leaves it. If you'd rather narrow the grant, Chrome lets you — Extensions → BugShot → Site access — with the understanding that the features which need the breadth will degrade accordingly.

A note on language. This README is kept in sync with its Korean edition, as are the privacy policy and the user guide. The engineering docs under docs/ and the source comments are written in Korean — the project is built and maintained by one person, and that's the language it was thought in. Everything you need to audit the privacy claims above is in English.

License

MIT © 2026 Sinhyeok Kang