Quick answer: AREC (Agent Recording) is the open Markdown document that lets an AI agent read a screen recording: what the person asked for, the moments that matter, clicks and pointer positions, browser errors, and what the recording did not capture. It now has its own neutral home at arecformat.org, with the specification, changelog, JSON schema, validator, test fixtures, a worked example, research and a list of implementations. The current release is AREC 1.3.1, a stable release of the 1.3 format, in the public domain (CC0) with an MIT licensed validator. In our coding benchmark, an agent given a Clipy AREC recording scored 11.8 out of 12, against 5.8 with the transcript and 2.4 with the raw video.

  • arecformat.org is live, built from the public repository github.com/arecformat/arec.
  • Your recordings did not move. Every Clipy recording still has its AREC at the same address: the watch link with .arec on the end.
  • AREC 1.3.1 enforces the section 5 privacy rules (no secrets, no raw query values, no on-demand frame extraction) in documents of every version.
  • Clipy's AREC gained two sections this month: Expected result and Missing evidence.
  • The benchmark: with AREC, a coding agent finished every change in a recorded design review in 4 of 5 runs. With the transcript or the raw video, 0 of 5.

What is AREC, and why does Clipy write it?

When you record with Clipy, you get a normal watch link anyone can open, with no signup to watch. Put .arec on the end of that link and you get the same recording written for agents. That document is AREC (.md serves identical bytes).

It is plain Markdown an agent reads in one pass, and a Clipy recording's document carries:

  • Summary and Intent: what the recording is about and what the person wants done.
  • Expected result: what the person said should have happened, when they told us.
  • Key moments: timestamped clicks, pointer rests and highlights, each with its pointer position and a link to its frame.
  • Browser diagnostics: console errors and failed requests from the Chrome extension, redacted by rule.
  • Capture gaps and Missing evidence: what this recording did not capture.
  • Transcript: every spoken word, with timestamps.

Clipy was the first screen recorder to write AREC, and it writes one for every hosted recording, from the web recorder, Chrome extension, Mac, Windows, iPhone, iPad and Android apps, CLI and MCP server. Recordings you keep on your Mac get an .arec file next to the video, so a coding agent can read it straight from disk. The AREC docs walk through each section.

What does an agent actually get from a recording?

Picture a designer reviewing a landing page. In 40 seconds she asks for three things: "make this one the primary button" while spotlighting a button with Flare, "move this card before that one" while sweeping the pointer from one card to the other, and "the headline should read what's in this note" while pointing at a sticky note on screen. She posts the Clipy link in Slack, and a developer pastes it into Claude Code: "make the changes from this review."

What happens next depends on what the agent receives:

  • A video file is pixels. In our benchmark the agent could not take the MP4 as input, so it pulled frames out with local tools and worked from pictures, without the spoken requests.
  • A transcript keeps every word, but "this one", "that one" and "this note" point at nothing. The agent has to guess which button, which card and which headline.
  • An AREC document keeps each request beside its moment: the time, the pointer position, the gesture that picked out the target, and a link to the frame. The agent knows which button she meant.

It is the same as sharing your screen with a teammate: you talk, you point, and they get both halves. AREC gives an agent both halves too. We compared the inputs side by side in screenshots vs recordings for coding agents.

Why does a screen recording need its own format?

A video file tells a person what happened. An agent needs structure, and the same structure whichever tool made the recording. A shared format guarantees three things:

  1. Evidence tied to time. Every request and every click points at a moment and a frame, so an agent can trace a conclusion back to where it came from.
  2. Privacy by rule. Diagnostics must leave out headers, bodies, cookies, tokens and raw query values, and the validator checks it.
  3. Gaps stated out loud. A document says what it did not capture, so an agent never reads missing evidence as proof that nothing happened.

Readers are lenient by design: they never reject a document for its version or for content they do not recognize. The longer argument is in why agents need a recording format.

What is on arecformat.org?

Everything someone needs to write or read AREC, in one place:

  • The specification, including the section 5 security rules and a minimal hosted example.
  • The changelog, the full version history up to 1.3.1, plus the proposals for 1.4.
  • The JSON Schema (arec-1.3.schema.json), copied byte for byte so its $id did not change.
  • The reference reader and validator: no dependencies, Node 18 or newer, with a --strict mode for producers.
  • Conformance fixtures, passing and failing, each invalid one tagged with the rule it breaks.
  • A worked example: the full AREC document for a recorded design review.
  • Research: both published studies, and how AREC compares with video files, captions, screenshots, HAR files, session replays and test traces.
  • Implementations: the recorders that write AREC, the agents that read it, and how the format has developed.

On clipy.online, /spec, /spec/changelog and /spec.md now redirect permanently to the new site. The schema, validator, fixture and example downloads are still served at their clipy.online addresses too, so nothing that already points at them breaks. The move is in the changelog.

Why does AREC need a neutral home?

Because a format only becomes a format when other people implement it. A spec under one product's URL reads like that product's feature. On its own domain, with its own public repository, AREC is what it was always meant to be: shared ground.

The terms make that real. The specification, schema and fixtures are dedicated to the public domain under CC0 1.0, and the validator is MIT licensed. There is no fee, no registration and nothing to ask permission for, and the editor has promised not to assert any patent against an implementation. Any recorder, extension, test runner or bug reporter can write AREC, check its output with node bin/arec-validate.mjs --strict, and open a pull request to be listed.

It is also stable. Version 1.3 is frozen for the 1.x line: nothing a conformant document relies on is removed or redefined, and breaking changes are reserved for 2.0. Every change to the public repository gets an independent adversarial review before it is pushed.

What changed in AREC 1.3.1?

Section 5 of the spec has always forbidden secrets and raw query values in diagnostics, and evidence that needs on-demand frame extraction. AREC 1.3.1 states those rules precisely and validates documents of every version. The highlights:

  • Sensitive keys are matched however they are spelled, so accessToken and x-api-key are caught. The list now also covers postData, CSRF tokens, client secrets, private keys, JWTs and session ids.
  • Raw query values are defined and flagged. A diagnostic string that begins with a URL carrying a value (?token=abc, #access_token=abc) is an error. Key names without values are fine.
  • The reader scrubs URLs. It removes parameter values from every URL in a diagnostics section and keeps the key names.
  • The schema matches the validator, adds noRawQueryValues, and the test suite fails if the two drift apart. Two new invalid fixtures cover the new checks.

Documents still declare spec_version: 1.3. 1.3.1 tightens the checks and the wording; a document that follows section 5 needs no change.

What is new in Clipy's AREC this month?

Expected result

A bug is the gap between what happened and what should have happened. Any recording can now carry an optional answer to "What did you expect to happen?": the owner fills it in on the watch page, in the Summary tab, whenever they like, or sets it with --expected in the CLI, the REST API, the SDKs or the MCP update_recording tool. Your answer goes into an Expected result section right after Intent, quoted, with a note telling the agent that where the recording differs from it is likely what you want looked at. It also travels into Jira, Linear and Confluence reports.

Missing evidence

An agent cannot tell "nothing happened" from "nothing was captured" unless someone tells it. The new Missing evidence section lists what this particular recording lacks: silent stretches of 30 seconds or more, clicks outside the recorded area and highlights with no nearby click, right below Capture gaps, which already says when console, network or cursor data is missing. It opens with one instruction: where the recording lacks evidence, ask the user instead of guessing. The same list is in context.json and in get_recording through the MCP server. For a full bug-to-fix walkthrough, see giving Claude Code a recorded bug reproduction.

What did the coding agent benchmark show?

The AREC coding benchmark gives a coding agent one task in four forms. A 44-second recording of a design review asks for six changes to a landing page, and five of them only make sense with the screen: a headline shown in an on-screen note, a button picked out with Flare, a mobile menu item, an order shown by a move gesture, and a hover and keyboard-focus state. The agent received the raw video, the transcript, the Clipy AREC document with its frames, or a hand-written spec. Each form ran five times in a fresh, isolated repository with the same model, prompt, time limit and tools, 20 runs in all, and submissions were graded blind in Chrome against a fixed 12-point rubric.

What the agent receivedMean score (of 12)Completed all six changes
Clipy AREC11.84 of 5
Hand-written spec11.01 of 5
Transcript only5.80 of 5
Raw video2.40 of 5

AREC scored about twice what the transcript did, a 6.0-point lead, and every AREC run beat every transcript run (11 to 12 points against 3 to 7). It also scored higher than the hand-written spec. The transcript got the headline from the note, the mobile menu target and the reordering in 0 of 5 runs each, because the words never say what "this" and "that" point at. AREC got all three in 5 of 5. AREC runs took about 16 seconds longer on average than transcript runs, and that time bought the correct edits.

The study was preregistered, with its prompt, rubric, raw results and submissions published, and the harness is in the public clipy-recorder/clipy-arec-benchmark repository, so anyone can rerun it with another agent.

The visual case study used a scripted design review recorded with Clipy's Chrome extension, a misheard word included. AREC with its linked frames completed 5 of 5 attempts; the transcript alone, and AREC without its images, left the requests unresolved.

How do you hand an agent an AREC recording?

  1. Record with Clipy on the Mac or Windows app, the Chrome extension, the web recorder or your phone. Talk the way you would to a teammate, and point at what you mean.
  2. Share the normal link. People watch it in the browser, with no signup to watch.
  3. Paste the link into Claude Code, Codex or Cursor. With Clipy's agent skill installed, the plain watch link is enough; without it, add .arec to the end.

The Clipy CLI reads and searches your recordings from the terminal, and installs the skill:

clipy agents install claude   # or: codex, cursor, windsurf, opencode

It works the other way too: after changing your UI, an agent can record its own verification with clipy proof and hand back an .arec link. That flow is in recording proof of an agent's UI fix, and the wider setup is on Clipy for agents.

Frequently asked questions

Is AREC a Clipy-only format?

No. The specification, schema and fixtures are in the public domain under CC0 1.0 and the validator is MIT licensed, so any recorder, extension, test runner or bug reporter can write AREC and any agent can read it. Clipy was the first screen recorder to write it.

What is the difference between AREC 1.3 and 1.3.1?

1.3 is the stable format. 1.3.1 is a release of the reference reader, strict check, schema and wording that enforces the section 5 privacy rules in documents of every version: no secrets, no raw query values in diagnostics, and no evidence that needs on-demand frame extraction. Documents still declare spec_version 1.3, and a document that follows section 5 needs no change.

No. Every recording keeps its watch link for people and the same link ending in .arec for agents, with .md as a byte-identical alias. Only the specification pages moved: clipy.online/spec now redirects permanently to arecformat.org/spec.

Does an agent need a plugin to read AREC?

No. An AREC document is plain Markdown, so Claude Code, Codex, Cursor, Windsurf, OpenCode, ChatGPT and other assistants read it from a link or a file. Clipy's optional agent skill and MCP server add conveniences such as reading a plain watch link or fetching key-moment frames.

Does an .arec file contain the video?

No. It describes the recording: what was asked, the expected result, timestamped key moments linked to precomputed frames, redacted browser diagnostics, what was not captured, and the transcript. The video stays where it is, and the agent reads the document.

Record the next thing you would normally explain over a call, and paste the link into your agent instead. Clipy is free to start, with a 7-day free trial and no card needed: download the app or start from the Chrome extension, and read the format itself at arecformat.org.