Bug reporting from video walkthroughs

Record yourself using an application. Say what is wrong as you go. Get tickets in your issue tracker, each one carrying the screenshot or video clip that proves the problem.

This is a Cowork project. There is no app to install and no service to sign up for. You clone the folder, point Cowork at it, and describe the recording. Claude does the rest.

What it actually does

1. Moves your recording into a timestamped session folder.
2. Transcribes the narration with word-level timestamps.
3. Reads the transcript and pulls out every problem you stated, merging repeats and dropping anything you took back.
4. Decides per issue whether a still frame proves it or whether it needs a clip, then cuts the frame or clip at the right moment, and looks at the result to confirm it shows what you described.
5. Shows you a numbered list and waits.
6. Creates a ticket for each issue you approve, with the evidence attached.

It will not create a ticket you have not approved, and it will not raise an issue you did not state. The transcript is the source of truth.

Why voice

Writing a good bug report takes several minutes. Saying "the save button overlaps cancel here" takes four seconds. A ten minute walkthrough can carry twenty issues, and each one arrives with a timestamp that identifies the exact frame showing the defect. Getting the evidence is the part people skip, and it is the part this automates.

Requirements

• A screen recorder that captures your microphone. QuickTime Player on macOS, Xbox Game Bar on Windows, OBS on Linux. You already have one.
• Cowork, with a folder connected to your clone of this repo.
• An issue tracker. Linear works out of the box. Anything else takes about five minutes to set up, see below.
• Nothing else. ffmpeg and Python already exist in the Cowork sandbox, and the speech model installs itself on first use.

Transcription runs locally in the sandbox. Your recording and its transcript never leave your machine. Only the evidence files attached to a ticket are uploaded, and they go to your own tracker.

Setup

git clone https://github.com/<you>/bug-reporting.git
cd bug-reporting
cp .env.example .env     # then add your tracker credentials

In Cowork, connect the bug-reporting folder as your project folder. Then say:

Run the setup check.

Claude runs scripts/setup.sh, installs the speech model environment, and tells you what is missing. Fix anything it flags, then you are ready.

Using Linear

Create a personal API key at Linear, Settings, Security and access, Personal API keys. Put it in .env as LINEAR_API_KEY. That is the whole setup.

Using something else

Tell Claude:

I use Jira, not Linear. Set that up.

Claude searches the connector registry for your tracker, asks you to connect it, checks what the connector can actually do, writes a short notes file describing how to file a ticket there, and updates the configuration. It then creates one test ticket so you can see it worked. Basecamp, Asana, GitHub Issues, Jira, Monday, ClickUp and Notion all follow the same path.

If your tracker has an HTTP API but no connector, Claude can write a small adapter script instead. scripts/trackers/linear.py is the reference implementation, and CLAUDE.md documents the three commands an adapter must provide.

Using it

1. Record the walkthrough

Use whatever screen recorder you already have. The microphone must be on, since the narration is the whole input.

• macOS: QuickTime Player, File, New Screen Recording. Or press Shift-Command-5. Open Options and select your microphone before you record.
• Windows: Xbox Game Bar, Windows-G, then turn the microphone on. The Snipping Tool also records screen and audio.
• Linux: OBS Studio, or the built-in GNOME screen recorder.

Record the application, talk through it, and say what is wrong as you meet it. Stop when you are done. You get a single video file, normally .mov or .mp4.

2. Attach it to the Cowork chat

Drag the video file into the Cowork chat window, with a short prompt:

Bug walkthrough of Acme Admin. File the approved ones under the Q3 Bugs project.

Nothing is uploaded to a server. Cowork works on the file locally, and the video is moved into a session folder inside this project.

Two things matter: which application the recording covers, and where the tickets should go. You can name the application in the first seconds of the video instead of in the prompt, and you can choose the destination later, when you approve the list.

3. Approve the list

Claude replies with a numbered list of issue titles and waits. Reply with the ones you want, edit any title you dislike, then Claude files them.

Getting better results

• Say the problem while it is on screen, not after you navigate away.
• Name the screen before you name the defect: "on the settings page, the save button overlaps cancel".
• Say "ignore that" or "actually no" when you change your mind. It gets dropped and reported back to you, so you can correct it.
• Say "that is a blocker" or "just cosmetic" if you want to control priority.
• Do the action, then describe it. Evidence is cut at or just before your words.

Configuration

The configuration block sits at the top of CLAUDE.md, in plain YAML:

tracker:          Linear
tracker_mode:     script
tracker_adapter:  scripts/trackers/linear.py
default_project:
default_labels:   Bug
session_timezone: Europe/London
whisper_model:    small
transcribe_language:

Change session_timezone to your own zone, since session folders are named from it. Raise whisper_model to medium if your audio is noisy or heavily accented; it is more accurate and about half the speed.

What lands on disk

reports/2026-08-12-094715/
  source.mov          your recording
  session.json        video metadata
  transcript.json     words with start and end times
  transcript.txt      readable transcript
  issues.json         the issue list, approval state, ticket ids
  report.md           rendered report with evidence
  evidence/
    issue-01.png
    issue-02.mp4

Everything under reports/ is git-ignored. Recordings of internal applications stay yours, even if you fork this repo publicly.

Licence

MIT. See LICENSE.