Video vs Screenshots vs Logs vs Agent-Readable Recordings: What Should You Give Your AI Agent?
AI debugging context is the evidence you hand an AI agent to reproduce a bug: the timing, the UI state, the error, and your intent. No single format carries all four for free, so the best one depends on the bug.
Updated: July 2026
You hit a bug. You paste the problem into Claude Code or Cursor, and the agent asks the obvious question: what did you actually see? Now you have to decide how to show it. A video file. A screenshot. A wall of log output. Or a link the agent can read directly. Each one carries some of the story and drops the rest, and the wrong pick wastes tokens or leaves the agent guessing.
This page compares the four honestly. Screenshots and logs win real cases, and pretending otherwise would make everything below less trustworthy. The goal is a decision guide, not a sales pitch.
How do you show an AI agent what went wrong?
You give it context in a format it can actually read, sized to the bug. A single frozen screen needs a screenshot. A backend crash with no visible UI needs logs. A multi-step flow where timing and clicks matter needs something that carries motion and intent. Below, each format is scored on four axes: what it captures, what it misses, token cost, and how easily an agent can consume it.
Raw video files
A .mp4 or .webm captures the most raw signal: every frame, the full motion of the flow, and the audio if you narrated. For a human reviewer, video is the richest option. For an agent, it is close to useless on its own.
The problem is consumability. Language models read text. They do not watch video. To use a raw recording, an agent has to run it through a separate vision pipeline, sample frames, and stitch a description together, and even then it loses the console error that flashed for one frame and the reasoning you spoke aloud. Video also cannot be pasted into a chat context the way text can, and uploading a multi-megabyte file to a coding agent is often not an option at all. Video is high signal, low access.
Screenshots
A screenshot captures one moment with perfect fidelity: the exact pixels, the error toast, the value in the field, the state of the button. Modern agents can read images, so a screenshot is genuinely consumable, and for a large class of problems it is the correct answer. If the bug is "this layout is broken" or "this error message appeared," a single image says everything.
What a screenshot misses is everything before and after that frame. It has no timing, no sequence of clicks, no cause. You see the button stuck in a loading state, but not that three clicks earlier a request went out and never came back. For a static UI state, that missing history does not matter. For a flow, it is the whole bug. Token cost is moderate: an image costs more than a line of text but far less than a video transcript, and one screenshot is cheap.
Text logs
Logs capture the machine's side of the story with precision: stack traces, error codes, timestamps, request paths, and the exact line that threw. For a backend-only failure with no UI to look at, logs are the right and often only useful format. They are pure text, so agents consume them natively and cheaply, and a stack trace pointed at a file and line number is close to a direct instruction for where to fix.
What logs miss is the human side. They do not show what the screen looked like, what you clicked to trigger the path, or what you were trying to accomplish. A log line tells you a function threw; it does not tell you the user was three steps into an export flow. Logs also drown you in volume: the signal is a few lines buried in thousands, and dumping a raw log file can be the most token-expensive option of all. Filtered, logs are lean and excellent. Unfiltered, they are noise.
Agent-readable recordings
An agent-readable recording captures the composite. It carries timing from the timeline, causality from the ordered key moments, narrated intent from the transcript, and the exact UI state from extracted frames and click targets, all in one machine-readable document. An agent-readable recording is a screen recording whose share link doubles as a structured text document (summary, key moments, click targets, and transcript) that AI agents can read instead of watching video.
Consumability is the point of the format. The document is plain markdown, so any agent that can fetch a URL reads it with no vision pipeline and no SDK. Token cost is bounded: instead of every frame, the agent gets a summary, a handful of key moments, and a transcript, which is far leaner than a full video and far more complete than a screenshot. What it does not do is replace filtered logs for a pure backend crash, and it is more than you need for a single frozen screen. It shines when a bug is a sequence of steps and you want the agent to understand the whole path at once. For the mechanics of producing one, see give agents video context.
How do the four formats compare?
Here is the comparison across the four axes. "Agent-consumability" means how directly an AI agent can read the format without extra tooling.
| Format | What it captures | What it misses | Token cost | Agent-consumability |
|---|---|---|---|---|
| Raw video | Every frame, full motion, narration audio | Nothing inherent, but nothing is extracted or labeled | Very high (needs frame sampling) | Poor. Needs a separate vision pipeline; cannot paste into chat |
| Screenshot | One moment, exact pixels, error state | Timing, sequence, cause, before and after | Low to moderate (one image) | Good. Modern agents read images directly |
| Text logs | Stack traces, error codes, timestamps, file and line | UI state, what was clicked, user intent | Low if filtered, very high if raw | Excellent for filtered logs; native text |
| Agent-readable recording | Timing, causality, click targets, frames, narrated intent, summary | Deep backend internals a log would show | Bounded (summary + key moments + transcript, not every frame) | Excellent. Plain markdown, no tooling on the agent side |
Which format captures the most and which is easiest to read?
Raw video captures the most raw signal, and filtered logs and agent-readable recordings are the easiest for an agent to read. Those are two different questions, and that gap is the whole point. Video holds the most but hands over the least, because none of it is extracted or labeled for a language model. Logs and the markdown twin hand over the most because they are already text an agent can act on. Screenshots sit in between: easy to read, but they capture only a single instant.
When should you use each one?
Use a screenshot when the bug is a single static state: a broken layout, a wrong value, an error toast with no timing to explain. It is the fastest correct answer for a frozen moment.
Use text logs when the failure is backend-only or has no meaningful UI: a crash in a worker, a failed API call, an exception with a clean stack trace. Filter them first so the agent sees signal, not volume.
Use a raw video file when a human needs to watch the flow and no agent is involved, or when you specifically want the audio and full motion for review rather than for an agent to reason over.
Use an agent-readable recording when the bug is a sequence and you want an agent to fix it: a multi-step flow where the timing, the clicks, the on-screen error, and what you were trying to do all matter together. Take the recurring Export CSV bug. The button hangs on the payouts dashboard and the console throws a TypeError from exportWorker.ts:142. A screenshot shows the spinner but not the click that started it. The console log shows the error but not the flow. One agent-readable recording carries the click, the timeline, the frame of the error, and your narration in a single link the agent reads and acts on. That composite is the format's home ground, and it does not have to be best at everything else to earn it.
For the field definitions behind the format, see the AREC spec. AREC (Agent Recording) is the open format an agent-readable recording produces.
FAQ
Is a screenshot or a video better for Claude? It depends on the bug. For a single static state, like a broken layout or an error message, a screenshot is better: it is exact and Claude reads images directly. For a multi-step flow where timing and clicks matter, a raw video is hard for Claude to use, and an agent-readable recording is the better fit.
What is the best way to share a bug with an AI agent? Match the format to the bug. Backend crash: filtered logs. Frozen UI state: a screenshot. A flow with steps, timing, and on-screen errors: an agent-readable recording, which packs all of that into one link the agent reads.
Can an AI agent read a video file directly? Not usefully. Language models read text, not video, so a raw file needs a separate vision pipeline to sample and describe frames, and even then it drops narration and split-second errors. An agent-readable recording extracts that content into markdown the agent reads directly.
Do agent-readable recordings replace logs? No. For a backend-only failure with a clean stack trace and no UI, filtered logs are leaner and often the only format that matters. Agent-readable recordings win when the bug lives in a UI flow that logs cannot show. Use both when a bug spans front and back.
Which format uses the fewest tokens? Filtered logs and a screenshot are usually cheapest for narrow cases. A raw video is the most expensive because frames must be sampled. An agent-readable recording is bounded: it sends a summary, key moments, and a transcript rather than every frame, so it stays lean while covering a whole flow.
Record once. Paste the link. Your agent does the rest. clipy.online.