AREC — Agent Recording: Specification v0.1 (Draft)

Version 0.1, Draft. This is an open format: any recorder may emit it, any agent may consume it. Feedback: support@clipy.online.

Updated: July 2026

Purpose

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. AREC (Agent Recording) is the open format for agent-readable recordings, published as a recording.md file. It defines the fields that document carries and the rules a consumer follows to read it. The goal is narrow and practical: give an AI agent everything it needs to understand what happened on a screen, in plain markdown, with zero tooling on the agent's side.

The format exists because agents cannot watch video. A .mp4 is opaque to a language model. Describing a bug in prose loses the timing, the cursor path, and the exact UI state that made it reproducible. AREC encodes those things as text so the agent can act on them.

Design principles

  1. Markdown-first. The document is markdown. Language models already read markdown natively, so there is no parser to ship and no SDK to install. A consumer that can fetch a URL can read an AREC document.
  2. One-URL duality. The same share link serves two audiences. A human opening it in a browser gets a video player. An agent fetching it gets the AREC document. Neither has to know the other exists.
  3. Self-contained. One document carries everything an agent needs to reason about the recording. No side calls, no secondary fetches to reconstruct context.
  4. Extensible. Optional sections may be added over time. A consumer that does not understand a section ignores it and keeps working, so new fields never break old readers.

Document structure

An AREC document is a single markdown file. Fields are grouped into required sections, one optional section, and sections reserved for future versions. For each field: what it contains, and why an agent needs it.

Required

Metadata. The document header.

  • source_url: the canonical share link. Why: the agent can cite the exact recording it read.
  • duration: total length of the recording. Why: lets the agent reason about pacing and where in the timeline a moment sits.
  • created: ISO 8601 timestamp of when the recording was made. Why: ordering and freshness.
  • spec_version: the AREC version this document conforms to (for v0.1, 0.1). Why: the consumer knows which rules apply.

Summary. A short natural-language description of what the recording shows. Why: the agent gets the gist in one read before deciding how deeply to parse the rest.

Key moments. An ordered list of the important instants in the recording. Each key moment contains:

  • timestamp: offset from the start of the recording. Why: anchors the moment to the timeline.
  • frame: a reference to the extracted still image at that instant. Why: the agent can look at the exact pixels that mattered without decoding video.
  • click_target: the UI element interacted with, expressed as a description plus x/y coordinates. Why: the agent learns not just that a click happened but what was clicked and where, which is what makes a flow reproducible.
  • description: what happened at this moment, in plain language. Why: narrated intent the pixels alone do not carry.

Transcript. A timestamped transcript of the narration. Why: intent, reasoning, and spoken context that no frame captures.

Optional

Cursor paths. The movement of the cursor between key moments, as timestamped coordinates. A consumer may use these to reconstruct motion and hesitation. A consumer that ignores them still has a conformant read.

Reserved for future versions

The following are defined so implementers reserve the names. They are reserved, optional, and not required for conformance in v0.1. A v0.1 document is complete without them.

  • Console events: timestamped browser console output (logs, warnings, errors) captured during the recording.
  • Network events: timestamped request metadata (method, sanitized path, status, duration).
  • Signature block: a cryptographic signature over the document for provenance.

Example document

The following is an illustrative example, not literal product output. It shows a minimal conformant AREC document for the recurring Export CSV bug.

# Recording: Export CSV button stuck loading

## Metadata
- source_url: https://clipy.online/video/3kelcef8wo8h
- duration: 00:41
- created: 2026-07-22T14:03:00Z
- spec_version: 0.1

## Summary
On the payouts dashboard, clicking Export CSV leaves the button in a
loading state and never downloads a file. The browser console shows a
TypeError from exportWorker.ts line 142.

## Key moments
- timestamp: 00:06
  frame: frames/0006.jpg
  click_target: { element: "Export CSV button", x: 812, y: 274 }
  description: User clicks Export CSV on the payouts dashboard.
- timestamp: 00:09
  frame: frames/0009.jpg
  click_target: null
  description: Button enters a spinner state and stays there.
- timestamp: 00:14
  frame: frames/0014.jpg
  click_target: { element: "DevTools console", x: 640, y: 393 }
  description: Console logs "TypeError: cannot read properties of undefined
  (reading 'rows')" at exportWorker.ts:142.

## Transcript
- 00:02 "I'm on the payouts dashboard and I'll try to export."
- 00:06 "Clicking Export CSV now."
- 00:10 "It just spins, nothing downloads."
- 00:13 "Opening the console. There's the error, exportWorker line 142."

Conformance

A document is a conformant AREC v0.1 document if it contains the required sections: metadata (with source_url, duration, created, spec_version), summary, at least one key moment with timestamp, frame, click_target, and description, and a transcript.

A conformant consumer MUST ignore sections it does not recognize and continue reading the sections it does. This is the forward-compatibility rule: it lets future versions add sections without breaking existing agents.

Versioning

AREC uses a semver-style version in spec_version. The 0.x line is a draft: fields may change between 0.x releases. Every change to this specification will be logged on this page with its date. A 1.0 release will freeze the required-field set.

This format was briefly published as OAR (Open Agent Recording); it was renamed to AREC (Agent Recording) to avoid collision with the existing .oar archive format. The filename convention is recording.md.

License

The text of this specification is licensed under CC BY 4.0.

See also: what is an agent-readable recording, an annotated walkthrough of the format, and how to give your agent video context.

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