How to Give Claude Code, Cursor, or Codex Video Context

Updated: July 2026

To give an AI agent video context, record your screen with Clipy, copy the share link, and paste it into your agent: the agent fetches a structured text version of the recording and reads that instead of the video. Setup takes about a minute per agent, once.

The 60-second version

Four steps. Do them once and every recording after is a paste.

  1. Record. Open Clipy, capture the flow you want the agent to understand, and stop. Short clips are agent-ready in about 10 seconds.
  2. Copy the link. Every recording produces one share link, for example https://clipy.online/video/3kelcef8wo8h.
  3. Paste it into your agent. Drop the link into a Claude Code, Cursor, or Codex prompt like any other reference.
  4. The agent fetches the twin. With the Clipy skill installed, the agent resolves the link to its text version and reads that.

That text version is the markdown twin. 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. So a link that plays a video for you becomes a document your agent can act on.

You install the skill once per agent. After that, pasting a link is the whole workflow.

Per-agent setup

Three agents, same shape: run the install command, approve once in the browser, then paste a link. Each install command uses @clipy/cli, which you can run with npx and never keep installed.

Claude Code

Install the skill:

npx @clipy/cli agents install claude

You approve once in the browser, and the skill lands in Claude Code. Public share links now resolve with no key.

MCP option (private library + search):

claude mcp add --scope user clipy --env CLIPY_API_KEY=clipy_sk_live_xxx -- npx -y @clipy/mcp

Swap clipy_sk_live_xxx for a real key from settings/api-keys. The MCP server adds access to your private recordings and search across their transcripts. The one-call bundle it exposes is the get_agent_context tool.

Example prompt to paste:

Here's a recording of the bug: https://clipy.online/video/3kelcef8wo8h
Read it, find the failing code, and open a PR with the fix.

Expected behavior: Claude Code fetches the twin, reads the summary and key moments, spots the console TypeError from exportWorker.ts:142, opens the file, and proposes the fix. It never decodes a frame of video. For a deeper walkthrough of this agent specifically, see Clipy for Claude Code.

Cursor

Install the skill:

npx @clipy/cli agents install cursor

Approve once in the browser and Cursor picks up the skill. Any clipy.online/video/... link you paste into the agent now auto-resolves.

MCP option (private library + search):

Add the same server through Cursor's MCP configuration, pointing it at npx -y @clipy/mcp with CLIPY_API_KEY set to a key from settings/api-keys. This gives Cursor your private recordings and transcript search.

Example prompt to paste:

This recording shows the repro: https://clipy.online/video/3kelcef8wo8h
Watch what I did, then tell me which component owns the broken state.

Expected behavior: Cursor reads the twin, follows the click targets and transcript to reconstruct the flow, and answers from the recording's text. "Watch" resolves to "read the document," so the answer is grounded in the exact UI state you captured.

Codex

Install the skill:

npx @clipy/cli agents install codex

Approve once in the browser and Codex has the skill. Pasted public links resolve without a key.

MCP option (private library + search):

Register the Clipy MCP server in Codex with npx -y @clipy/mcp and CLIPY_API_KEY from settings/api-keys. Codex then reaches your private library and can search across transcripts.

Example prompt to paste:

Recording of the failure: https://clipy.online/video/3kelcef8wo8h
Use it as context. Summarize the root cause and draft the patch.

Expected behavior: Codex fetches the twin, uses the summary for orientation and the key moments for specifics, and drafts the patch against the code the recording points at.

Troubleshooting

Public share link, skill only, no key. If the recording is a public share link, the skill alone resolves it. There is nothing else to configure: install the skill, paste the link, done. You do not need an API key for public links.

Private library link needs an MCP key. If the link points at a recording in your private library, the skill cannot read it without credentials. Add the Clipy MCP server with a personal key from settings/api-keys. The key scopes the agent to your own recordings and unlocks search.

Nothing resolves after install. Confirm the install finished the browser approval step, then re-paste the link. If you want to read a recording by hand to confirm it is reachable, append .md to the watch URL (https://clipy.online/video/<id>.md) and open it: public links return the twin with no key.

Wrong agent installed. The three install commands are distinct (... install claude, ... install cursor, ... install codex). Run the one matching the agent you are actually pasting links into.

What the agent actually receives

When your agent resolves a link, it does not get a video file. It gets the markdown twin: a summary, timestamped key moments with extracted frames, click targets as UI element plus x/y coordinates, cursor paths, and a timestamped transcript of your narration. That is enough to reconstruct what happened without a single decoded frame.

We keep the field-by-field breakdown on its own page so this guide stays a how-to. For what each section holds, what an agent does with it, and what breaks without it, read the markdown twin, section by section. For the category and the why behind it, start with agent-readable recording. The frozen field names live in the AREC spec.

FAQ

Can I paste a video into Claude Code? Not a raw video file. Paste a Clipy share link instead. With the Clipy skill installed, Claude Code resolves the link to a text version of the recording and reads that. Install with npx @clipy/cli agents install claude, approve once, then paste any clipy.online/video/... link.

Do I need an API key? For public share links, no. The skill alone resolves them. You only need a key when the link points at a recording in your private library. Get one from settings/api-keys and add it through the Clipy MCP server, which also enables search across your transcripts.

Does this work in Cursor and Codex too? Yes. The setup is identical: run npx @clipy/cli agents install cursor or ... install codex, approve once in the browser, and paste links into the agent. The MCP option for private recordings works the same way across all three.

How fast is a recording ready to paste? Short clips are agent-ready in about 10 seconds after you stop recording. Processing runs on-device through Clipy's pipeline. Recording is free; you sign in with Google to save and share, which is what produces the link you paste.

What if I do not have the skill installed? You can still read any public recording by hand. Append .md to the watch URL (https://clipy.online/video/<id>.md) and open it. The skill just automates that resolution so your agent does it silently every time you paste a link.

Install the Clipy skill and paste your first link.