amagi-screen

Send Claude a video of your bug, not a paragraph describing it.

amagi-screen turns a screen recording into something Claude can actually read: it detects every moment the screen changes, saves a frame for each one, reads any on-screen text with OCR, and flags frames that look like an error or exception. Everything lands in one index.md in timestamp order.

Everything runs locally. There are no API keys and nothing leaves your machine.

Install

pipx install amagi-screen

You also need ffmpeg on your PATH. OCR is optional and needs the tesseract binary — without it, amagi-screen still extracts the frame timeline, just without on-screen text or error flags.

Usage

amagi-screen <recording> [-o OUTDIR] [--threshold 0.12] [--max-frames 60] [--no-ocr]

Example:

amagi-screen ./bug_repro.mp4 -o runs

The last line of stdout is the path to the run folder, so scripts and agents can pick it up.

Output

Each run writes <outdir>/<recording_name>/:

• index.md: the file to read. Each detected frame, in time order, with its OCR'd text and a ⚠ possible <word> flag when the text looks like an error, exception, or failure.
• events.md: just the flagged frames — usually the fastest way to find the moment something broke.
• frames/: JPEG frames named frame_<seconds>s.jpg, 1280 px wide.
• metadata.json: title, source path, duration, frame count, and whether OCR ran.

Real output from a 6-second test clip with two scene changes (no tesseract installed in this run, so no on-screen text — see Limitations):

# demo_recording

- Source recording: demo_recording.mp4
- Duration: 00:06
- OCR: unavailable (install tesseract for on-screen text)

## Timeline

**[00:02]** see frame: frames/frame_00002s.jpg

**[00:04]** see frame: frames/frame_00004s.jpg

Use it as a Claude Code skill

The repo includes a SKILL.md. Copy it into your skills folder:

mkdir -p ~/.claude/skills/amagi-screen
cp SKILL.md ~/.claude/skills/amagi-screen/SKILL.md

When you paste a screen recording and ask what went wrong, Claude runs amagi-screen, reads index.md and events.md, and opens the frames it needs.

Limitations

• OCR needs tesseract on PATH. Without it, frames still get extracted, but there's no on-screen text and no error flagging.
• Scene detection finds a different number of frames depending on how much the UI actually changes. A very static recording (one screen, no clicks) falls back to a fixed interval sample instead.
• Frames are stills. Fast cursor movement, animation, and quick modal flashes between two detected frames are lost.
• --threshold needs tuning per app: dense, animated UIs need a higher threshold than static dashboards, or you'll get too many near-duplicate frames.

Related AmagiLabs projects

• amagi-watch — give Claude a video URL and get back a transcript + key frames.
• amagi-listen — give Claude a podcast or meeting recording and get back a chaptered transcript.
• legal-review-skills
• More tools at github.com/amagilabs.

If amagi-screen saves you a round trip explaining a bug, a star helps other people find it.

Legal

amagi-screen only reads files you point it at. It doesn't upload, store, or transmit recordings anywhere.

License

MIT. Copyright (c) 2026 AmagiLabs (Amagisolutionsgroup, Inc.). See LICENSE.

Built by AmagiLabs.