Report a Problem

Turn "something broke" into a precise, replayable recording. Instead of a vague bug report — a screenshot, a half-remembered console error, a "it didn't work" — you get one JSON file that holds the whole flow: every network request and response (with bodies), every console line, every JS error, and every navigation, timestamped and in order. That file is the bug report.

This repo ships that idea as two products:

• For developers — a black-box recorder you paste into the browser and drive yourself while debugging, then hand the JSON to your coding agent.
• For your end-users — an embeddable "Report a problem" widget they click when they hit a bug; it records their session, redacts secrets, asks consent, and files the report to a server you triage.

Both record the same thing. The difference is who presses record and where the recording goes.

The two products

1 · CLI / agent skill → cli-skill/

What it is. A self-contained userscript (code-flow-capture.user.js) you load into DevTools or Tampermonkey. It records the whole flow to a local JSON, which you hand to any LLM/CLI (Claude Code, or anything else) to find the failure and propose a fix. Packaged as a Claude Code skill with /capture, /start-capture, /stop-capture commands, but the recorder is plain JS that works anywhere.

Who it's for. Developers and coding agents.

When to use it. You're debugging a flow yourself and want the exact network + console + error trace around the failure, without transcribing anything.

→ cli-skill/README.md · analysis playbook

2 · On-site "Report a problem" → on-site/

What it is. An embeddable widget + SDK your app mounts, backed by an ingest server. When an end-user hits a bug they click the widget, reproduce it, review what was captured (secrets already redacted client-side), consent, and submit. The report lands in a database for the operator to triage. Ships as core/ (engine), sdk/ (widget + controller), server/ (Fastify ingest with pluggable storage/auth), and db/ (schema + provider DDLs).

Who it's for. Your end-users — with an operator/support team on the receiving end.

When to use it. You want real users to report bugs from inside your product, and you want each report to arrive as a replayable session, not a screenshot.

→ on-site/README.md · Integrate the widget · Self-host the server · Build guide

At a glance

One shared contract

Both products emit the same { meta, events } JSON, defined once in PROTOCOL.md (schema 1.1.0). Target that shape and any producer works with any consumer — so anything that analyses one product's capture analyses the other's. The agent playbook you use on a developer capture reads a user-submitted report byte-for-byte the same way.

{
  "meta": { "schemaVersion": "1.1.0", "startedAt": "…", "stoppedAt": "…", "url": "…", "events": 128 },
  "events": [
    { "t": 0,    "kind": "nav",     "type": "pushState", "to": "…" },
    { "t": 1420, "kind": "fetch",   "method": "POST", "url": "…/rebuild", "status": 422, "ok": false, "reqBody": "…", "resBody": "{\"error\":\"…\",\"code\":\"…\",\"details\":{…}}" },
    { "t": 1421, "kind": "console", "level": "error", "args": ["…"] }
  ]
}

A failed request carries the server's full { error, code, details } right in resBody — nothing to transcribe.

Quick start

Product 1 — record a flow yourself:

1. Open cli-skill/code-flow-capture.user.js, copy it, and paste into DevTools → Console on the page under test (or install it in Tampermonkey). Recording starts.
2. Reproduce the bug, then click the pill to stop — a code-flow-capture-<timestamp>.json downloads.
3. Hand that JSON to your agent and ask it to find the failure. Full guide: cli-skill/README.md.

Product 2 — let end-users report:

1. Mount the widget in your app:
   hljs language-js

   Copy

   import { mountCaptureWidget } from "@code-flow-capture/sdk/widget"
   mountCaptureWidget({ ingestUrl: "https://capture.example.com", appKey: "myapp" })
   

2. Stand up the ingest server (on-site/server/) with a database and env config.
3. See on-site/INTEGRATE.md (wire the widget), on-site/SELF-HOST.md (deploy the server), and on-site/BUILD-GUIDE.md (how the pieces fit).

Privacy

• No headers, ever. Neither producer reads request/response headers — Authorization, Cookie, Set-Cookie, and CSRF tokens are never captured.
• Secrets in bodies are redacted client-side. The on-site SDK runs a redaction pass before a report leaves the browser — values under keys like password / token / api-key, plus JWTs, Bearer …, and card-shaped strings, are masked. (The paste-in developer recorder does not redact, so treat its JSON as a private debug artifact and keep captures out of version control.)
• Captures hold your app's real payloads. This repo's .gitignore keeps capture JSON, .env files, and node_modules out of git by default.

License

MIT — see LICENSE.