An agentic debugging workflow is a loop where a teammate records a bug once and an AI coding agent reads that recording, reproduces the issue, and opens the fix — with no re-typed repro steps in between. With Clipy, the recording ships as a machine-readable document (AI summary, pointed-at frames, click coordinates, full transcript) that Claude Code or Cursor can act on directly.
Disclosure: Clipy is our product. We've kept this factual and cite sources for external claims — tell us if anything is stale.
The usual bug loop leaks time at every handoff. QA sees something break, writes a ticket, guesses at repro steps, drops a screenshot. The engineer reads the ticket, can't reproduce it, asks for a screen recording, waits a day. By the time anyone touches code, half the context is gone. This is a walkthrough of a tighter loop: one recording, one link, an agent that reads it, and a fix that comes back with its own recorded proof of work.
The whole loop on one page
Here's the pipeline end to end before we break down each step:
- A teammate hits a bug and records it with Clipy — screen, voice, and the exact click.
- The share link lands in a Slack channel (it's live within ~2 seconds of pressing Stop).
- A developer pastes that same link into Claude Code.
- The agent fetches the recording's markdown document — summary, key-moment frames, click coordinates, transcript — and restates the bug in its own words.
- It writes a failing test, proposes a fix plan, implements, and opens a pull request.
- The agent (or the developer) attaches a new Clipy recording of the verification run to the PR, so the human reviewer watches the fix work instead of trusting a green check.
Steps 1–5 are shipped and boring in the best way. Step 6 — agents producing recordings for humans to review — is the direction this is all heading, and it's where the loop closes on itself. More on that at the end.
Step 1: Record the bug, don't describe it
The single biggest time sink in bug reports is translation loss. The reporter knows exactly what happened; the ticket captures maybe 60% of it. A recording captures all of it and costs less effort than writing the ticket.
Clipy runs in the browser with no install, and also ships a Chrome extension, a native Mac app, and a Slack app. Recording is free forever — unlimited length, up to 4K, no watermark, no credit card, and no signup wall for whoever watches it later. The reporter just narrates while it breaks: "I click the Export button here, the spinner starts, and it never resolves."
That narration matters more than it looks. When they say "this button," Clipy captures the frame at that instant and — on Mac-app recordings and Chrome-extension tab recordings — the real click coordinates as fractions of the frame. On the Mac app it goes further: at each click it records the macOS Accessibility role and label of the element under the cursor (for example AXButton "Export"), not just a pixel. So "this button" resolves to an actual, named UI element instead of a vague gesture. That's the raw material an agent needs and a screenshot never has.
Step 2: The link travels in Slack
The reporter pastes the share link into your bug channel. For humans, it unfurls as a normal video preview they can click and watch — Slack renders shared links through its standard link unfurling behavior, and Clipy ships a Slack app for richer previews.
The important property: the same URL serves two audiences. A human watches the video. An agent, as we'll see next, reads a structured document from the exact same link. Nobody has to export anything, attach a transcript, or maintain a second artifact. One link, two readers.
Step 3: Wire Claude Code to read Clipy links
Do this once. Install the Clipy skill so your agent knows that any clipy.online/video/<id> link is fetchable as a recording document:
mkdir -p ~/.claude/skills/watch-clipy-recording
curl -fsSL -o ~/.claude/skills/watch-clipy-recording/SKILL.md \
https://clipy.online/skills/watch-clipy-recording/SKILL.md
Restart Claude Code once so it picks up the new skill folder. Skills are just SKILL.md files the agent loads as custom instructions — see the Claude Code docs for how skills, slash commands, and MCP fit together. The full install reference, including the Codex-style folder and the claude.ai ZIP upload, is at clipy.online/docs/skill.
After that, the agent already knows the convention: fetch the link's markdown twin, wait if the recording is still processing, treat the extracted frames as ground truth, and list the issues it found before touching code. No MCP setup required for public links.
If you'd rather skip the skill for a one-off, you can point the agent straight at the machine-readable document by appending .md to any watch link — https://clipy.online/video/<id>.md. The skill just automates that convention and adds the "restate before acting" discipline.
Step 4: Paste the link and let the agent read
Here's the actual paste-in prompt. Drop the link and a short instruction:
Watch https://clipy.online/video/abc123xyz and fix the bug it shows.
Before writing any code:
1. Read the summary and key moments, and look at the frames to identify the
exact element the reporter pointed at.
2. Restate the bug and the expected behavior as a numbered list.
3. Reproduce it with a failing test.
Then propose a fix plan and wait for my OK before implementing.
What the agent fetches is not the MP4 — today's models don't watch hour-long video, and a raw file is a dead end in a context window. It fetches a text-plus-images document derived server-side from the recording. Concretely it contains:
- An AI summary and action items — the TL;DR of what the reporter demonstrated and asked for.
- Key moments: timestamped instants where the reporter referenced something visible, each with the extracted frame image and, where a click track exists, the click coordinates (x/y as fractions of the frame). The agent's vision reads the frame; the coordinates remove any "which of the three Export buttons" ambiguity.
- The full timestamped transcript of the narration.
Being precise about scope, because it changes how you prompt: this recording gives the agent what was said, what was shown, and where the cursor clicked — plus the AX element label on Mac recordings. It does not hand the agent your browser's console errors or network request payloads. If a bug's root cause lives in a failed XHR, capture that from your devtools and paste it alongside the link; the recording localizes the bug in the UI, your logs localize it in the stack. Used together they're far stronger than either alone, and the recording alone is usually enough to point the agent at the right file.
For the deeper mechanics of what's inside that document and why it works, see the pillar guide on agent-readable screen recordings.
Step 5: From plan to pull request
A good agentic debugging workflow forces the agent to reason before it edits. The prompt above does this deliberately: it has to restate the bug and write a failing repro first. That single constraint is what separates a reliable AI bug fixing workflow from an agent that confidently rewrites five files and breaks three of them.
The agent comes back with something like: "The Export button calls exportReport(), which awaits pollJobStatus(). The frame at 0:14 shows the spinner in its loading state and the transcript confirms it never resolves. pollJobStatus() has no timeout and swallows the rejection, so the promise hangs forever. Here's the failing test." You read the plan, confirm the diagnosis matches the recording, and give the go-ahead.
From there it's a normal Claude Code session — it implements the fix, runs the suite, and opens the PR:
# the agent runs your tests, then:
git checkout -b fix/export-spinner-hang
git commit -am "fix(export): add timeout + surface rejection in pollJobStatus"
gh pr create --title "Fix export spinner that never resolves" \
--body "Repro recording: https://clipy.online/video/abc123xyz"
Note the PR body already links the original recording via gh pr create. Anyone reviewing the PR can watch the exact bug it claims to fix. The context that started in Slack is now permanently attached to the change that resolved it. For a fuller tour of driving Claude Code from a recording, see recording bugs for Claude Code.
Traditional loop vs. agentic loop
| Stage | Ticket-and-screenshot loop | Agentic debugging workflow |
|---|---|---|
| Capture | Reporter writes repro steps from memory | Reporter records the bug as it happens |
| Handoff | Screenshot + text ticket | One link, humans and agent read it |
| Repro | Engineer re-derives steps, often fails | Agent reads frames + click coords, writes a failing test |
| Fix | Manual, context reconstructed | Agent proposes a plan, implements on approval |
| Proof | "Fixed, please retest" | Verification recording attached to the PR |
The row that changes the culture is the last one.
Step 6: The loop closes — the agent records its own proof
Everything above is a human recording for an agent. The forward-looking half of this workflow is the reverse: the agent recording for a human.
When the agent finishes a fix, "the tests pass" is a claim, not evidence. A green CI check tells you the assertions the agent wrote came back true — it doesn't tell you the actual button now works. The natural close of the loop is for the agent's verification run to be recorded and dropped into the PR as its own Clipy link: the agent (or a browser it drives, or you, watching it work) records itself exercising the fixed flow — clicking Export, watching the spinner resolve, confirming the download — and attaches that recording. The reviewer watches thirty seconds of the fix behaving correctly instead of trusting a checkmark. And because it's a Clipy link, the next agent that touches this code can read that verification recording too.
That's the shape worth building toward: recordings flowing in both directions, humans and agents each producing artifacts the other can act on. The consumption half — agents reading recordings — is fully live today via the skill and MCP. The production half, agents pressing record on their own verification runs, is the emerging frontier, and it turns a one-way bug report into a closed feedback loop where every fix arrives with watchable proof.
Start with steps 1–5 — they work right now, they're free, and they'll shave a day off your next "can't reproduce." Then keep an eye on step 6, because it's coming fast.
FAQ
What is an agentic debugging workflow?
It's a debugging process where a human records a bug once and an AI coding agent reads that recording to reproduce, diagnose, and fix it — instead of a person re-typing repro steps into a ticket. The agent works from what was said and shown in the recording (transcript, key-moment frames, click coordinates), not from a lossy text summary.
Can Claude Code actually read a screen recording?
Not the raw video, but yes to a document derived from it. Claude Code doesn't watch MP4s; with the Clipy skill installed it fetches the recording's markdown twin — summary, timestamped transcript, and frame images of the moments the reporter pointed at — which is text and images, the two formats every agent understands. Install it from clipy.online/docs/skill.
Does the recording include console logs and network requests?
No. A Clipy recording gives the agent the video-derived context: transcript, key-moment frames, click coordinates, and (on Mac recordings) the clicked element's accessibility label. It does not capture browser console errors or network payloads. If a bug's cause is in a failed request, grab that from your devtools and paste it alongside the link — the recording localizes the bug in the UI, your logs localize it in the stack.
How does the agent know which button I meant?
Through key moments. When you say "this button," Clipy extracts the frame at that instant, and on Mac-app and Chrome-extension tab recordings it fuses the real click coordinates. On the Mac app it also records the element's Accessibility role and label. So "this" resolves to a specific, named element even when three buttons look alike.
Do I need to pay for any of this?
No. Recording, share links, transcripts, summaries, key moments, the .md documents, and the MCP server are all free — no watermark and no signup wall for viewers. You only sign in (one Google click) to save and share your own recordings.