There is a moment every developer working with coding agents knows. Claude Code reports the task complete. The tests pass. The diff looks reasonable. And a small voice asks: but did it actually work?

Not "does the code compile." Not "are the tests green." Did the thing the user actually experiences, the checkout button, the export, the login, behave the way it is supposed to? Autonomous agents can now ship features and fixes end to end. The part that has not caught up is verification. And the fastest verification is not reading the diff. It is watching the work.

With Clipy, the agent records its own proof while it works, and you confirm in about thirty seconds. Or you hand the recording to another agent and let it confirm for you. This post is the practical version: what to tell Claude Code, the exact commands, and how the CLI, the MCP server, and the skill fit together.

TL;DR

  • Reading a diff tells you what changed. It does not tell you what happened when a human clicks the button. That gap is where "the tests pass" bugs live.
  • Clipy lets a coding agent record a screen recording of its own verification run, headless in CI or on your real screen, and hand you a link.
  • One command wires it into your agent: npx @clipy/cli agents install claude (also codex and cursor).
  • The agent records with clipy record for a quick capture, or runs a live clipy session and drops clipy mark notes as it verifies each step. Assertions like --assert-text make a mark machine checkable, so "it worked" is evidence, not a claim.
  • Every recording has a machine readable twin at /video/<id>.md, so a second agent can read the recording (summary, key moments, transcript) and tell you whether the fix holds.
  • You watch a thirty second clip instead of re-reading a hundred line diff. Full reference lives at clipy.online/docs/agents.

Reading the diff is not verification

A diff is a description of intent. It is the agent telling you, in code, what it meant to do. Reviewing it is useful and you should keep doing it. But a diff cannot show you the one thing that actually matters: the running application in front of a user.

Think about the failures that survive a green test suite. The API returns 200 but renders an empty cart. The form submits but the success toast never fires. The fix works on desktop and breaks the mobile layout. The migration runs and silently drops a column. None of these show up in a diff, and plenty of them slip past unit tests, because the test asserted the thing the author thought to assert, not the thing the user notices.

When an agent writes the code and the tests, this gap gets wider, not narrower. The agent is confident. The agent is often right. But "often right" is exactly the regime where you need cheap verification, because the failures are rare enough to be surprising and common enough to hurt. Re-reading the whole diff by hand is not cheap. It is the most expensive form of verification there is, and it still misses runtime behavior.

The fastest verification is watching the work

Here is the reframe. Instead of asking the agent to convince you in code, ask it to show you the running result. A short screen recording of the actual repro, followed by the actual fix, answers "did it work" in the time it takes to watch it. You are not parsing logic in your head. You are looking at the product.

This is not a new idea for humans. It is why a Loom link on a pull request is worth more than three paragraphs of description. What is new is that the agent can now produce that recording itself, without you in the loop, as part of finishing the task. The recording becomes an artifact of the work, like a test or a changelog entry, rather than something a human has to remember to capture afterward.

And because a Clipy recording is agent readable, the loop closes both ways. The agent that did the work records the proof. A different agent, a reviewer running in CI or in your terminal, can read that proof and give a verdict, without a human watching anything at all. You only step in when something looks off.

How to make your agent record its own proof

There are three ways an agent talks to Clipy, and you will usually use them together. The skill is the zero setup way to read a pasted recording link. The CLI (@clipy/cli) is what an agent runs in a terminal to record and to read. The MCP server (@clipy/mcp) is the same power as tool calls, for agent hosts that speak the Model Context Protocol. Start with the one command that wires all of it in.

Step 1: one command to wire it into your agent

npx @clipy/cli agents install claude   # also: codex, cursor

The first time you run it, your browser opens at clipy.online and you click Approve once. That mints a scoped, revocable API key, stores it in ~/.config/clipy, and installs the Clipy skill into your agent's skills directory. From that point on, your agent knows two things: how to record with Clipy, and how to read any Clipy link it is handed. No key to copy or paste. You can revoke it any time at clipy.online/settings/api-keys.

On a headless box, a CI runner, or over SSH, there is no browser to open. The login detects that and switches to a copy code flow: it prints an approval URL you open on any device, you click Approve, and you paste the one time code back into the terminal. Fully non interactive setups skip login entirely and set CLIPY_API_KEY in the environment.

Step 2: tell Claude Code what you want

With the skill installed, you do not need to teach the agent the commands. You describe the outcome and let it drive. These prompts work as written:

Before you fix this, reproduce the bug and record the repro with Clipy.
Then fix it, record the fix, and give me both share links.
Record a live Clipy session while you run the test suite. Drop a mark
each time you verify a step, and assert the ones you can. Stop when the
suite passes and paste me the link.
Here is a Clipy link: https://clipy.online/video/<id>
Read it and tell me whether the checkout bug is actually fixed.

The point is that the agent decides which Clipy command fits. Your job is to ask for proof, the same way you would ask a human teammate to "throw a quick Loom on the PR." What the agent runs under the hood is the next section, so you know what it is doing.

Step 3: what the agent actually runs

For a quick, one shot capture of a web app, the agent runs a headless recording. This needs no desktop and works in CI:

clipy record --url http://localhost:3000 --for 30 \
  --type bug_report --title "Checkout returns 500 on empty cart"

That launches a headless Chromium the CLI owns, records the page for the given duration, uploads it, and prints a share link plus an agent context link. Headless captures are silent, so the agent narrates with timestamped notes that become the recording's transcript:

clipy record --url http://localhost:3000 --for 30 \
  --note "3: open cart" --note "12: click checkout, server 500s"

For work that unfolds over time, the agent opens a live session, works, marks what it verifies, and stops when done:

clipy session start --url http://localhost:3000 --type bug_report
clipy mark "cart total shows \$0.00 before checkout" --assert-selector "#total" --assert-text "\$0.00"
clipy chapter "Applying the fix"
clipy mark "checkout now succeeds, order id rendered" --assert-url "**/order/**"
clipy session stop --json

The session records in the background the whole time. It auto stops and uploads at a safety cap so it can never run away. Navigations and console errors get marked automatically. And clipy session stop prints the same share and agent context URLs, ready to paste.

The cleanest pattern for CI wraps an existing command so the recording is kept only when the run is meaningful:

clipy session run --url http://localhost:3000 -- npx playwright test
# child exits 0        -> session stop  (the recording is uploaded)
# child exits non-zero -> session abort (nothing is uploaded)

Now every passing verification run leaves a link, and failed runs do not litter your library.

Recording the real screen, not just a headless page

Sometimes the thing you need to prove is not a URL. It is a desktop app, a native window, or a full multi step flow across tabs. If the Clipy Mac app is running, the same CLI can drive it over a local bridge:

clipy sources                                  # list windows and displays
clipy record --source mac-screen --window "Chrome"

That records the real Chrome window, with system audio on by default and the microphone off unless you add --mic. Everything else, marks, transcript, the share link, works the same. Real screen and window capture are CLI features that lean on the Mac app; the headless path above needs no desktop at all.

Marks turn "it worked" into evidence, not a claim

A mark is a timestamp plus a line of text the agent drops into a live session. Marks are sorted and become the recording's transcript, so even a silent headless capture reads back as a narrated timeline of what the agent checked and when. That alone is useful. But the real upgrade is that a mark can carry verified provenance.

There are two levels. A Clipy verified mark asks Clipy to check the claim against the live page at that instant:

clipy mark "empty state renders" --assert-selector ".empty-cart"
clipy mark "total is correct" --assert-selector "#total" --assert-text "\$42.00"
clipy mark "landed on the receipt" --assert-url "**/order/**"

Clipy evaluates the assertion in the running page and tags the mark: a check for pass, a cross for fail, a warning if it genuinely could not evaluate. It never silently reports a pass it did not verify. A driver attested mark is the weaker form, where the agent states what it observed and Clipy records only that the agent asserted it:

clipy mark "api returned 200 with order id" --observed "status=200" --verdict pass

You can also make a failed assertion abort the whole session, so a broken verification never gets uploaded as if it succeeded:

clipy mark "checkout succeeds" --assert-url "**/order/**" --fail-mode abort

The difference matters. When you or a reviewing agent reads the recording, the marks are not just the agent's narration. They are a checklist with pass and fail results that Clipy stood behind at capture time. "The bug is fixed" stops being a sentence and becomes a verified line in the transcript.

Another agent confirms for you

This is where the loop closes. Every Clipy recording has a machine readable twin. Append .md to any watch URL and you get the full context document: the AI summary, the key moments (timestamped frames of what was on screen, with click coordinates where they were captured), and the timestamped transcript including the marks. No API key is needed for a public link.

https://clipy.online/video/<id>         # the human watch page
https://clipy.online/video/<id>.md      # the same recording, agent readable

Because the skill taught your agent to recognize Clipy links, you can literally paste a link into a second agent and ask for a verdict. It fetches the .md, reads the summary and the marks, and tells you whether the fix holds. If you prefer the terminal, the CLI reads the same data:

clipy wait <id> --for both     # block until transcript + summary are ready
clipy context <id>             # the full agent context bundle as markdown
clipy summary <id>             # TL;DR, key points, action items
clipy transcript <id>          # plaintext, or --srt / --vtt subtitles
clipy moments <id>             # key moments with click coordinates and frame URLs

From an MCP host like Claude Desktop or Cursor, the one call you want is get_agent_context. It returns the metadata, summary, key moments as inline images, and the transcript in a single tool response, which is exactly what a reviewing agent needs to reach a verdict. Wire it up once:

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

The MCP server also exposes the recording side as tool calls (start_recording, add_marker, stop_recording), so an agent that lives entirely inside an MCP host can record and read without ever shelling out to the CLI.

A full example: repro, fix, proof

Here is the whole loop as you would actually run it. The bug: checkout returns a 500 when the cart is empty. You hand it to Claude Code with one instruction.

You: The checkout endpoint 500s on an empty cart. Reproduce it and record
the repro with Clipy, then fix it and record the fix. Give me both links.

The agent reproduces first, so there is proof the bug was real:

clipy session start --url http://localhost:3000/checkout --type bug_report
clipy mark "cart is empty" --assert-selector ".cart-empty"
clipy mark "clicking checkout returns 500" --assert-text "Internal Server Error"
clipy session stop --json
# -> { "shareUrl": "https://clipy.online/video/3kelcef8wo8h", ... }

It writes the fix, then records the verification run, this time asserting success:

clipy session run --url http://localhost:3000/checkout -- npm run e2e:checkout
# tests pass, session uploads
clipy mark "empty cart now shows a friendly message, no 500" --assert-selector ".cart-empty-message" --fail-mode abort

You get two links. You watch the first for ten seconds and see the 500. You watch the second and see the friendly empty state. Total verification time: under a minute, and you looked at the running product, not the diff. Or you skip watching entirely and paste both links into a reviewing agent:

You: Before link is the bug, after link is the fix. Confirm the 500 is gone
and the empty cart is handled. https://clipy.online/video/... and /video/...

The reviewer reads both .md twins, checks that the "returns 500" assertion is present in the before recording and absent in the after, sees the passing assertion on the empty state, and reports back. You did not open a browser.

Skill, CLI, or MCP: which one when

They are complementary, not competing. A quick map:

  • Skill: the default for reading a pasted public link with zero setup. Install once, paste a clipy.online/video/... link, done. Docs at clipy.online/docs/skill.
  • CLI: for terminals, shell scripts, and CI. It records and reads. It self describes with clipy guide --json, so an agent can discover every command and flag instead of guessing. Docs at clipy.online/docs/cli.
  • MCP: for authenticated tool calls from Claude Desktop, Cursor, Codex, and Windsurf. Private library search, inline frames, and recording control as tools. Docs at clipy.online/docs/mcp.

Auth is one credential across all three: a personal API key with a read scope by default and an ingest scope for recording. Browser login grants both. The full integration reference, including the recording lifecycle and an honest list of what is not supported yet, lives at clipy.online/docs/agents.

What this actually changes

Once your agents record their own proof, a few things shift. Code review starts with a link, not a diff, and the diff becomes the thing you read only when the recording raises a question. Async handoffs get honest, because "done" now ships with evidence a teammate or a reviewing agent can check on their own time. And CI stops being a pass or fail signal only. A green build can now carry a watchable artifact of the exact user flow that passed, which is worth a great deal the day something regresses.

Two honest notes so you know the shape of the tool. Headless captures are silent by design, so the narration you read back comes from the agent's marks, which is why asserting them matters. And Clipy serves precomputed key moment frames rather than letting an agent grab an arbitrary screenshot at any timestamp, which keeps the cost bounded and the recording fast to read. Verification here means watching the clip and reading the transcript, summary, and verified marks. That is more than enough to answer "did it work," and it is a lot faster than the alternative.

Get started

Install it into your agent in one line and ask for proof on the next task:

npx @clipy/cli agents install claude

Then read the agent integration reference, or start from the overview of what agent readable recordings unlock. Your agent already fixed the bug. Now it can prove it, and another agent can confirm it, before the code ever reaches you.