bug2context

Turns a screen recording of a bug into structured, chronological context an AI agent can actually read.

Screenshots lose the story: bugs happen fast, a still frame has no timeline, and the logs and the narration live somewhere else entirely. LLMs don't take video. This distills a recording into one markdown chronology — key frames, the text on screen, device logs and spoken narration, all on the same clock.

• No SDK. Works on any video, including one someone sent you over WhatsApp.
• Local-first. Nothing leaves your machine. No account, no API key, no cloud.
• MCP-native. Claude Code calls it as a tool; you just point at the file.

uvx bug2context               # guided menu
uvx bug2context process bug.mp4 --out bundle/

Running it with no arguments opens a menu — record an Android device, process a video you already have, or list previous bundles — and writes to ~/.bug2context/, which is where the MCP server looks. Everything it does is reachable through the flags below; it just stops you having to remember them.

What comes out

- `[00:00]` 🖼 `frames/frame_001_00-00.png` — start of recording
      OCR: Cart 2 items
- `[00:04]` 🖼 `frames/frame_002_00-04.png` — screen changed
      OCR: Applying discount..
- `[00:04]` 📋 W/DiscountEngine: rate field missing
- `[00:06]` 🖼 `frames/frame_003_00-06.png` — screen changed
      OCR: TypeError: cannot read 'rate'
- `[00:06]` 📋 E/RideService: NullPointerException at RideRequest.kt:142
- `[00:06]` 📋 F/AndroidRuntime: FATAL EXCEPTION: main
- `[00:06]` 🎙 "ahí está, explota al aplicar el descuento"

A full run is in examples/report.md.

bundle/
├── report.md    the chronology above
├── frames/      the key frames, named by timestamp
└── meta.json    the same data, structured, for programmatic use

Install

Requires ffmpeg on PATH (brew install ffmpeg).

uvx --from 'bug2context[ocr]' bug2context          # OCR: Apple Vision on macOS, tesseract elsewhere
uvx --from 'bug2context[ocr,audio]' bug2context    # plus spoken narration

Or from source:

git clone https://github.com/emanueld92/bug2context
cd bug2context
uv sync --extra ocr --extra audio

Every stage is optional and degrades quietly: no OCR backend still gives you frames, no audio track still gives you the visual timeline.

Use it from Claude Code

claude mcp add bug2context -- uvx --from 'bug2context[ocr]' bug2context-mcp

Working from a local clone instead: uvx --from /path/to/bug2context bug2context-mcp.

Then just ask: "analiza este video del bug: ~/Desktop/crash.mp4".

Bundles default to ~/.bug2context/<video>-<timestamp>/.

Android: screen + logcat in one command

uv run bug2context record --seconds 60 --package com.example.app --out bundle/

Reproduce the bug while it records. Both streams start from a single host timestamp — that anchor is what makes a stack trace land next to the frame showing the crash.

Pass --package. Level filtering alone is not enough on a real phone: a 2 min capture held 7,634 W/E/F lines and none came from the app under test — they were all AppOpsControllerImpl, GNSSMGT and friends. Scoping to the app's process left 35. Crash tags (AndroidRuntime, DEBUG) are kept regardless of process, since a crash report is the whole point.

Logs are captured unfiltered and scoped afterwards, so an app that crashes and restarts still has its death recorded. Consecutive identical entries fold into one with a (×N) count — framework chatter arrives in bursts of fifteen.

Already have a log file? Merge it into any video:

uv run bug2context process bug.mp4 --logcat logcat.tx

... [View full README on GitHub](https://github.com/emanueld92/bug2context#readme)