What Is an Agent-Readable Recording?

An agent-readable recording is a screen recording whose share link an AI agent can read as structured text (a summary, key moments, click targets, and transcript) instead of watching the video.

Updated: July 2026

The definition

An agent-readable recording is a screen recording built to be understood by AI agents, not just watched by people. You record your screen once. The share link you get back has two faces. Open it in a browser and you see a normal video player. Point an AI agent at it and the agent fetches a structured text document that describes everything that happened on screen.

That document is called the markdown twin. It is plain markdown, so a language model reads it directly, with no plugin and no video decoding.

Here is the full idea in one line:

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.

The category is new, so the words are worth pinning down. "Agent-readable recording" is the thing: a recording an agent can read. AREC (Agent Recording) is the open format that encodes it. The markdown twin is the actual document an AREC recording produces. You will see all three across this page, and they always mean those three things.

Why agents are blind to video

AI agents cannot watch video. A .mp4 file is opaque to a language model. It is a wall of encoded pixels with no structure a model can reason over, and no timeline it can point at. You can hand an agent a two-minute screen recording of a bug and it learns nothing from the bytes.

So people fall back to describing the problem in text. That is where context leaks out. Prose loses the timing. It loses the cursor movement. It loses the exact UI state that made the bug reproducible in the first place.

Think about how much a written bug report drops on the floor. "The button doesn't work" says nothing about which button, where on the screen, in what state, after which click, with what error in the console. You saw all of that. You watched it happen. But the moment you translate it into a sentence, the agent only gets the sentence.

Screenshots help, but a screenshot is one frozen instant with no order and no motion. Logs help, but logs have no picture of the screen and no idea what the user was trying to do. None of these carry the whole event: what was on screen, what got clicked, where the cursor went, what was said, and when each of those happened.

An agent-readable recording is the missing piece. It keeps the timing, the click coordinates, the cursor path, the narration, and the visual moments, and it hands all of it to the agent as text the agent already knows how to read.

How does it work?

It works by giving one share link two faces: a video player for humans and a markdown document for agents. You record once and share one URL. Whoever opens it gets what they need. A person gets the player. An agent gets the markdown twin.

To read the twin as an agent, you append .md to any watch URL. So https://clipy.online/video/<id> becomes https://clipy.online/video/<id>.md. Public share links need no key at all. The agent fetches that URL and gets the whole document in one go.

The processing that builds the twin runs on-device through Clipy's own pipeline. Short clips are agent-ready in about 10 seconds. Recording is free, and you sign in with Google to save and share.

What is inside the markdown twin

The markdown twin carries a small, fixed set of fields. Here is each one at overview depth. For a field-by-field annotated walkthrough with real excerpts, see the anatomy of the markdown twin.

Metadata. The document header. It holds source_url (the canonical share link the agent can cite), duration (total length), created (when the recording was made), and spec_version (which version of the format this document follows). This tells the agent what it is looking at and how fresh it is.

Summary. A short natural-language description of what the recording shows. The agent reads this first to get the gist before deciding how deeply to parse the rest.

Key moments. An ordered list of the important instants in the recording. Each key moment carries a timestamp (offset from the start), a frame (a reference to the still image extracted at that instant, so the agent can look at the exact pixels without decoding video), a click_target (the UI element that was interacted with, given as a description plus x and y coordinates), and a description (what happened, in plain language). Click targets are what make a flow reproducible: the agent learns not just that a click happened, but what was clicked and where.

Transcript. A timestamped transcript of the narration. This is intent and spoken reasoning that no frame captures. It is what you were thinking out loud while the bug happened.

Cursor paths. Optional. The movement of the cursor between key moments, as timestamped coordinates. An agent can use these to reconstruct motion and hesitation, and an agent that ignores them still reads the document correctly.

Some fields are reserved for future versions of the format, including console events, network events, and a signature block. These are named in the spec so tools can plan for them, but they do not ship today. Do not expect them in a twin yet.

Walkthrough: fix a bug with one recording

Here is the whole loop, end to end, with a bug you have probably hit.

You are on a payouts dashboard. The Export CSV button is stuck in a loading state and never downloads a file. You open DevTools and there it is: a console TypeError coming from exportWorker.ts:142. You could try to describe all of that to your coding agent. Instead, you record it.

1. Record once. You start Clipy and capture the screen while you reproduce the bug. You click Export CSV, the button spins, you open the console, you point at the error, and you say out loud what you are seeing. You stop. In about 10 seconds the clip is agent-ready and you have a share link.

2. Paste the link into Claude Code. You drop the clipy.online/video/... link into your agent. If you are running Claude Code, this pairs naturally with a screen recorder for Claude Code. The agent takes the URL, appends .md, and fetches the markdown twin. No key is needed for a public link.

3. The agent reads the twin. It gets the summary ("Export CSV leaves the button loading and never downloads; console shows a TypeError from exportWorker.ts:142"). It gets the key moment where you clicked Export CSV, with the element name and the x/y coordinates. It gets the key moment where the console error appears, with the frame it can look at. It gets your narration, timestamped. It now knows what happened, in what order, and where.

4. The agent opens the fix PR. With the file, the line number, the reproduction steps, and the visual state in hand, the agent traces the TypeError in exportWorker.ts, writes the fix, and opens a pull request. You never typed a bug report. You recorded the bug and let the agent read it.

That is the payoff. Record once, paste the link, the agent does the rest. For a deeper how-to with per-agent setup, see give your agent video context.

Who is it for?

Anyone whose work is easier to show than to type, and who wants an AI agent to act on it.

Developers with coding agents. This is the core case. You reproduce a bug on screen once and your agent reads the recording, gets the file and line and reproduction steps, and opens the fix. It replaces the slow round trip of writing a bug report by hand.

QA. Instead of filing a ticket that a developer or an agent has to re-derive, you record the failing flow. The click targets, the timing, and the UI state travel with the recording, so the reproduction is already captured, not described from memory.

Support. A customer or teammate shows you the problem. You record the repro and hand the link to an agent that can read exactly what went wrong and where, without a back and forth of "can you send a screenshot."

Product managers. You walk through a flow or a rough spec on screen and narrate the intent. The transcript and key moments give an agent a structured record of what you meant, not a lossy summary written after the fact.

The format is open

The markdown twin is not a Clipy-only trick. It is an instance of AREC (Agent Recording), an open format for agent-readable recordings. AREC defines the fields the document carries and the rules a consumer follows to read it. Because it is open, any recorder can emit it and any agent can consume it, and because it is plain markdown, a consumer that can fetch a URL can read it. Clipy is one implementation of the format. The spec is the format itself.

Record once. Paste the link. Your agent does the rest. clipy.online.

FAQ

Can Claude Code watch a video? No. Claude Code, like every language model, cannot watch video. It reads the markdown twin instead. You paste a Clipy link, the agent appends .md, and it fetches a text document with the summary, key moments, click targets, and transcript. It reads what happened rather than watching it.

What is the difference between a transcript and an agent-readable recording? A transcript is only the spoken words. An agent-readable recording is the whole event as text: the transcript plus timestamped key moments, extracted frames, click targets with coordinates, cursor paths, and metadata. The transcript is one field inside it. The recording carries what was on screen, not just what was said.

Do I need the MCP server or the skill? For public share links, neither. Appending .md to a watch URL returns the twin with no key. The Clipy skill lets an agent auto-resolve any clipy.online/video/... link. The MCP server adds private-library access and search across your transcripts. Start with public links, add the others when you need them.

Does it work with Cursor and Codex? Yes. The Clipy skill installs into Claude Code, Cursor, and Codex, so a pasted link auto-resolves to the markdown twin in any of them. Even without the skill, any of these agents can read a public link by fetching the .md URL directly.

What does AREC stand for? AREC stands for Agent Recording. It is the open format that encodes an agent-readable recording: the fields the markdown twin carries and the rules for reading it. It is open, so any tool can emit or consume it. The spec lives at AREC format.

Is the format proprietary? No. AREC (Agent Recording) is an open format. Any recorder can emit a conformant markdown twin and any agent can consume one, and the field definitions live in the public AREC spec. Clipy is one implementation of the format, not a gatekeeper for it.