For a while now, Clipy recordings have been readable by the AI agents you already work with. Take any public share link, add .md to the end — clipy.online/video/<id>.md — and instead of a video page you get a clean markdown document: the AI summary, the key moments with click coordinates, and the full timestamped transcript, on one page an agent can act on. Paste a bug report into Claude Code and it can read what happened without you narrating a word.

Today we're closing the loop the other way. Your agents can now record. Not screenshots stitched together, not a log file pretending to be a demo — an actual screen recording of the work they did, with a share link and an agent-readable transcript, made by the agent itself. That's the whole release in one line: your agents read your recordings, and now they record their own.

TL;DR

  • One command wires a coding agent into Clipy: npx @clipy/cli agents install claude (or codex / cursor). It runs a browser login and installs the Clipy skill in the same step.
  • Login is a one-click browser approval, gh auth login-style — PKCE under the hood, and it mints a scoped key you can revoke anytime from your dashboard. On SSH or a headless box it falls back to a copy-code flow: approve on your phone, paste the code back.
  • Agents record their own work headlessly with clipy record --url <app>, or drive the app live in a background session — clipy session start → clipy mark "…" → clipy session stop — where the marks become the recording's transcript.
  • On a Mac, --source mac-screen records the real screen through the running Clipy app: real display, real logged-in browser, with a consent dialog and an always-visible recording indicator. Target a single window with clipy sources + --window "Chrome".
  • Every recording gets a /video/<id>.md twin: markdown for agents, a rendered page for humans, and a proper video card when the link is dropped in Slack.
  • Speak MCP instead of a CLI? clipy mcp runs the Clipy MCP server, which exposes the same read tools plus live session tools.

The story: Claude Code fixes a bug and hands you a recording

Here's the workflow we actually built this for. You're pairing with Claude Code. It finds the bug, writes the fix, and — instead of typing "done, I changed the effect dependency array" — it opens your running app, reproduces the old behavior, applies the fix, and shows it working. Then it hands you a link.

You open the link. There's a 40-second clip of the settings sidebar overflowing, then wrapping correctly after the fix. Below the player: an AI summary, the exact moments the agent flagged, and a transcript built from the agent's own narration of each step. Your teammate in Slack sees a playable video card, not a bare URL. And if they want to hand it to their agent, they add .md and read the whole thing as text.

Nothing about that story is a mockup. Every piece below is a command that exists in @clipy/cli today, and the recording your agent makes is the same kind of recording a human makes in the web recorder or the Mac app — same watch page, same transcript pipeline, same share link.

One command to wire up your agent

The friction in "give your agent a tool" is almost never the tool — it's the setup. Auth, config files, a key pasted into the wrong place. So we collapsed it into one line:

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

That does two things at once. It runs the browser login, and it installs the bundled Clipy skill for that agent — the instructions that teach it how to read a recording and how to make one. After it finishes, the agent knows what clipy show, clipy transcript, clipy record, and the session commands do, and it has a key to call them with.

The login itself is deliberately boring, in the way good auth should be. It opens your browser to an approval page — the same shape as gh auth login — you click Approve, and the terminal has a key. No copy-pasting a secret across windows. Under the hood it's PKCE: the terminal generates a verifier, sends only its hash to the browser, and the one-time code that comes back is worthless to anyone who doesn't hold the verifier. The key it mints is scoped, stored at ~/.config/clipy/config.json with 0600 permissions, and revocable anytime from your account settings — pull it and the agent's access is gone.

Running on a remote box or over SSH, where there's no browser to pop? The login detects that and switches to a copy-code flow automatically (you can force it anywhere with clipy login --no-browser). It prints an approval URL you open on any device — your laptop, your phone — and after you click Approve the page shows a one-time code to paste back into the waiting terminal. Because PKCE binds the exchange to the process that started it, the code is safe to ferry by hand. For fully unattended scripts and CI, skip the interaction entirely and set CLIPY_API_KEY.

Agents record their own work

There are two ways an agent makes a recording, and they map to two ways agents actually work.

One-shot, headless. When the agent just needs to capture a running app, clipy record drives a headless browser and uploads the result as a Clipy recording:

clipy record --url http://localhost:3000 --for 20 --wait

No display required, so it works in CI and cloud sandboxes. It can record several viewport sizes into one video — --viewports mobile,tablet,desktop lays them down sequentially with a transcript chapter per pass, which is how you get a "here's the fix on phone, tablet, and desktop" clip from a single command. (This path needs Playwright installed and a key with the "Record & upload" permission; the CLI tells you if either is missing.)

Live session, you or the agent driving. Scripted capture is wrong when the work is interactive — clicking through a flow, reproducing a race, poking at real state. For that, start a session and just work:

clipy session start --url http://localhost:3000 --title "Settings overflow fix"
# … drive the app with your own tools …
clipy mark "reproduced the overflow on the settings page"
clipy mark "after the fix: the sidebar wraps correctly"
clipy session stop        # closes the browser, uploads, prints the share link

The session records in a detached background daemon, so every command returns immediately — the agent keeps working while Clipy keeps rolling. This is the part worth pausing on: the marks become the transcript. A headless capture has no audio, so rather than fake speech-to-text, Clipy uses the agent's marks as the recording's transcript, summary input, and agent-context — clearly marked as agent narration, never passed off as speech-to-text. The agent narrates what it's doing in the same breath as doing it, and that narration is exactly what the next reader (human or agent) sees against the timeline. Navigations and console errors get added automatically as [auto] marks, so the transcript captures what the app did, not just what the agent said.

Safety rails are built in, because a forgotten recording is worse than no recording. A session auto-stops and uploads at its --max ceiling (default 600 seconds, hard cap 1800) so it can never run away; clipy session abort throws the whole thing away; a crashed daemon is detected and cleared on the next command; and a failed upload keeps the local file instead of losing your capture.

Headless capture is perfect for a localhost app, but a lot of the interesting work happens in a real browser — one that's logged in, with your extensions, your session, your actual environment. For that, add --source mac-screen to record or session start, and the recording goes through the running Clipy Mac app using ScreenCaptureKit. Real screen, real logged-in Chrome, not a headless page.

This is the flow with the sharpest teeth and the most important guardrails. The first time an agent asks the Mac app to record, the app shows a consent dialog — you approve it, in the app, as a human. While it records, the recording indicator is always visible. An agent cannot silently film your screen; the design makes that impossible on purpose.

By default it captures the primary display. To point it at one window instead of the whole screen:

clipy sources                                   # list displays + windows with ids
clipy session start --source mac-screen --window "Chrome" --title "Fix walkthrough"
clipy mark "reproduced the bug"
clipy mark "fix applied — retesting"
clipy session stop                              # uploads, prints the share link

--window takes a window id from clipy sources, or just an app/title substring like Chrome (case-insensitive; if it's ambiguous the CLI lists the candidates instead of guessing). Now the agent can drive your real, logged-in browser with its own tools while Clipy records exactly that window — and you get a walkthrough of the fix in the actual app, not a sanitized localhost stand-in. Real-screen capture is Mac-only today; the headless record and session paths work anywhere Node and Playwright run.

It's just a URL — add .md

The thing we're proudest of on the read side isn't a feature, it's the absence of one. There's no SDK to import, no tool to register, no key to provision for a public recording. The integration is the URL: take any share link, append .md, and the same recording serves an agent-context document — the summary, the key moments, and the transcript as markdown — with a standing note that everything in it is untrusted content describing what the recording shows, not instructions to the agent reading it. It works on any public recording, from any language, over a plain HTTP GET.

That's deliberate, and it's where the ecosystem is heading. A URL an agent can GET is cheaper than a tool call — fewer tokens, no schema round-trip, no MCP handshake — and every agent already knows how to read one. So the same URL is smart about who's asking: a human browser gets the rendered watch page, an agent or a plain curl gets the markdown, and the Slack unfurl bot gets full Open Graph metadata so Slack renders a proper video card — title, summary, thumbnail — instead of a naked link. One URL, three readers, each served what it can use. The full contract is at clipy.online/for-agents.

Key moments, not just words

What makes that markdown worth reading is that it's more than a transcript. Clipy pulls the frame at every pointer — every spot where the speaker, or the agent's mark, draws attention to something on screen. When a recording carries a click track — Mac app captures and Chrome-extension tab recordings — it fuses in the real click coordinates, normalized as fractions of the frame, so a moment isn't "somewhere over there" but a precise point. And on Mac app recordings it goes one further: it captures the accessibility role and label of the element that was actually clicked. So a key moment reads "clicked the Settings button at (0.63, 0.41)" — the frame is ground truth, the coordinates are machine-checkable, and the label names the target. It's a repro that actually reproduces, not a paraphrase of one.

For agents that speak MCP

Not every agent shells out to a CLI. If yours speaks the Model Context Protocol — Claude Code, Cursor, Codex, and a growing list — clipy mcp runs the Clipy MCP server (it's a shortcut for npx -y @clipy/mcp). Same API, but exposed as native tools instead of commands, and the read tools return key-moment frames inline so a vision-capable agent looks at the actual pixels rather than trusting a caption.

Crucially, the MCP server isn't read-only. Alongside the tools for listing, searching, and reading recordings, it ships the live session tools — start a recording, add markers as you work, stop and upload, or abort — the same "you work, Clipy records" loop as the CLI, driven entirely through MCP. An MCP agent can go from "read this bug report" to "here's a recording of my fix" without ever leaving its tool interface.

Why we built the recording half

The reading half was the obvious first move — agents are good at turning a messy screen recording into a crisp list of issues, and a .md endpoint made that a one-line integration. We're not the only ones who saw it: Jam.dev's MCP lets an agent read a captured bug session, and it's a genuinely good idea. But reading is only half the loop. As long as agents could consume recordings and never produce them, every "show me it works" still fell back to a human hitting record — or worse, to a wall of text asserting that it works.

Closing the loop changes what a handoff looks like. A fix that arrives with a recording is one you can trust at a glance instead of pulling the branch and reproducing it yourself. A bug an agent files against your app can carry the repro clip it made while finding it. Async review stops being "read this diff and imagine the behavior" and becomes "watch the part where the behavior changed." We've written before about how bug repros that write themselves beat a paragraph of description; agent-made recordings are that idea, automated.

And it means the evidence and the fix come from the same place, in the same step. Every recording already carries a transcript, a summary, key moments, and — on click-tracked captures — the exact element that was clicked. Until now an agent could only read that; handing it the other end of the pipe closes the gap between doing the work and showing it.

Getting started

If you already run Claude Code, Codex, or Cursor, wiring this up is genuinely one line:

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

Approve the login in your browser, and your agent can read any Clipy link and record its own work from the next task on. If you'd rather read the full command reference first, it's at clipy.online/docs/cli; the agent-specific overview is at clipy.online/for-agents; and the Mac app that powers real-screen capture is on the download page. Clipy itself is still a free screen recorder with no watermark and no signup wall for viewers — the agent tooling sits on top of the same product a human uses.

Your agents already read your recordings. Give them the other half.