Quick answer: run clipy recheck <id> --url <start-url> and Clipy replays a recorded workflow against the app as it is today. It reads the recording's clicks, page changes and scrolls, drives Chrome for Clipy through the same steps in its own background window, and saves a frame after each one. You get a step-by-step report (matched, control not found, different screen and so on) plus a new Clipy link with every frame, ready for a pull request or a regression check.
- One command, one answer: did the recorded workflow still work after the fix, the redesign or the dependency bump, and if not, at which step.
- Proof you can share: the frames upload as a new Clipy recording with a watch link and an
.areccontext document;report.jsonandreport.mdstay on your machine. - Safe by default: clicks replay by recorded label, never raw position, and irreversible controls (delete, pay, send, submit) are left alone unless you pass
--allow-destructive. - CI ready:
--fail-on-divergencesets a non-zero exit when today's UI no longer matches. - Shipped October 31, 2026 in the Clipy CLI. See the changelog entry.
Why do recorded workflows stop working without anyone noticing?
A screen recording is a snapshot of how the app behaved on one afternoon. That is exactly why it works so well for bug reports: you show the problem the way you would show it to a teammate sitting next to you, you say what you expected, and you share the link. Your coding agent reads the transcript, the key-moment frames and the clicked element labels from the same link, and it has the whole story. If you have not tried that loop yet, giving Claude Code a recorded bug reproduction walks through it.
The app keeps moving after the recording ends. A fix lands. A designer renames a button. A route gets a new path. A banner shows up over the toolbar. The recording still says "click Export CSV", and nobody knows whether that step still exists until someone tries it by hand. Across a team's recorded bugs and walkthroughs, that drift adds up quietly.
clipy recheck treats a recording as something you can run again, not only watch. Hand it to your agent and "does this still work?" gets a concrete answer, with a frame for every step.
What does a re-check look like on a real bug?
Here is a scenario most product teams will recognise. Last Tuesday you hit a bug in your reporting app. You opened the Clipy Chrome extension and recorded it: open Reports, open the Q3 revenue report, open Filters, type a region, click Apply, click Export CSV. The CSV came back with every row instead of the filtered ones. On the watch page's Summary tab you filled in What did you expect to happen?: "The CSV has only the filtered Q3 rows." You pasted the link into Claude Code, it read the .arec, found the bug in the export query and opened a pull request.
In the same week, design shipped a refreshed Reports page. Before you merge, you want to know two things: does the fixed flow still run, and did the redesign break any step of it? So you tell your agent: "Re-check this recording on staging."
A careful agent looks at the plan first. --plan lists the steps it would replay, without opening a browser:
$ clipy recheck 7hq2mz4kd0pe --plan
Re-check plan for Export CSV ignores the Q3 filter (7 steps)
1 0:00 start https://app.example.com/reports
2 0:04 click link "Q3 revenue"
3 0:05 navigate https://app.example.com/reports/:id
4 0:09 click button "Filters"
5 0:13 type (could not map: typed values are never captured in a recording, so typing is not replayed)
6 0:18 click button "Apply"
7 0:22 click button "Export CSV"
Expected result: The CSV has only the filtered Q3 rows.Step 5 is already marked: Clipy never captures typed values, so passwords stay private, and the plan marks the step up front. Then the agent runs it against staging:
$ clipy recheck 7hq2mz4kd0pe --url https://staging.example.com/reports --out ./recheck
Chrome for Clipy ready on port 9333
step 1/7 matched: the start page is on the recorded route
step 2/7 matched: clicked link "Q3 revenue"
step 3/7 matched: the page reached the recorded route
step 4/7 matched: clicked button "Filters"
step 5/7 unmapped: could not map step: typed values are never captured in a recording, so typing is not replayed
step 6/7 matched: clicked button "Apply"
step 7/7 control_not_found: no visible control named "Export CSV"Notice what happened with the hosts. The recording was made on app.example.com; the re-check ran on staging.example.com. Clipy mapped the recorded paths onto the staging host, checked each route there, and would not click anything on any other host. Then it wrote the report:
# Re-check: Export CSV ignores the Q3 filter
Today's UI diverges from the recording, first at step 7.
7 steps: 5 matched, 0 replayed, 1 control not found, 0 different screen, 0 error, 1 could not map.
- Original recording: https://clipy.online/video/7hq2mz4kd0pe
- Re-check recording: https://clipy.online/video/r4w9xk2t8bnc
- Re-check agent context: https://clipy.online/video/r4w9xk2t8bnc.arec
- Recorded on https://app.example.com, re-checked on https://staging.example.com (recorded paths checked on the re-check host; nothing is clicked on any other host)
- Frames: /home/you/app/recheck/frames
**Expected result (from the original recording):** The CSV has only the filtered Q3 rows.
Compare it with the last frame.
| # | At | Step | Result | Detail |
|---|----|------|--------|--------|
| 1 | 0:00 | start on https://app.example.com/reports | matched | the start page is on the recorded route |
| 2 | 0:04 | click link "Q3 revenue" | matched | clicked link "Q3 revenue" |
| 3 | 0:05 | go to https://app.example.com/reports/:id | matched | the page reached the recorded route |
| 4 | 0:09 | click button "Filters" | matched | clicked button "Filters" |
| 5 | 0:13 | type (value not captured) | could not map step | typed values are never captured in a recording, so typing is not replayed |
| 6 | 0:18 | click button "Apply" | matched | clicked button "Apply" |
| 7 | 0:22 | click button "Export CSV" | control not found | no visible control named "Export CSV". Nearby: "Download CSV", "Share", "Schedule" |That last row is the useful part. The flow works through step 6 on the redesigned page. Step 7 failed because there is no control named "Export CSV" any more, and the report lists what is there now: "Download CSV". That is a rename from the redesign, not a regression in the fix. Your agent can say so in one sentence, link the re-check recording so you can see the new toolbar, and suggest the next move: record a fresh take of the flow on staging, which becomes the baseline for the next re-check.
What do the step results mean?
Every step comes back with exactly one result and a plain-language reason. The six results are the same in the terminal, in report.md and in report.json:
| Result | What it means |
|---|---|
| matched | The page was on the recorded route and the labelled control was found and clicked, or the page reached the recorded route. |
| replayed | A scroll, replayed in the recorded direction. The recording keeps the direction, not the distance. |
| control not found | No visible control has the recorded label. The report names the controls that are there now, which usually reveals the rename. |
| different screen | The page is on another route, or the control is covered (a dialog, a banner) or disabled. Nothing is clicked. |
| error | The step threw. The reason says what went wrong. |
| could not map step | Typing, an unlabelled or right click, a drag, a label shared by several controls with nothing to choose between them, or a control that reads as irreversible. |
The summary rolls those up into one verdict. matches means every step that could be checked worked. diverged means at least one control was missing or the screen was different, and the report names the first step where that happened. incomplete means not enough of the recording could be replayed to say either way. A step that could not be mapped is never counted as a pass, so an agent reading the JSON cannot accidentally report a skipped step as working.
When the original recording has an expected result, the report shows it at the top. You and your agent compare it with the frame from the last step: the re-check puts what should happen and what the app shows today side by side, and leaves that judgment to the person or agent reading it.
What will a re-check never do?
A re-check clicks for real, in a Chrome that is signed in to your apps. So the rules about what it clicks were designed first, not bolted on.
- No clicking by coordinates. Clicks are replayed by the recorded element label only, matched against each control's own accessible name. A recorded "Cancel" will not click a "Cancel plan" button, and a label hidden inside some other button does not count. Position is used only to choose between two controls with the same name.
- No irreversible actions by default. Controls whose names read as irreversible (delete, pay, send, submit and similar) are checked at plan time and again on the live control, and they are not clicked. Their steps come back as could not map. Pass
--allow-destructivewhen you are on staging or a test account and want them replayed. - No wandering to other sites. A recorded page is opened directly only on the recording's own host. With an origin mapping (production recorded, staging re-checked), clicks happen only on the replay host, so a staging page that redirects back to production is reported as a different screen.
- No clicks on covered or disabled controls. If a dialog sits over the button, or the button is disabled, the step is a different screen and nothing is pressed.
- No taking over your browser. The re-check opens its own background window in Chrome for Clipy, never a tab you or another agent are using, and closes it (plus any tab the site opened) when it finishes or when you press Ctrl-C.
Clipy never replays typed values, so passwords stay private.
How do you use a re-check as proof on a pull request?
The frames from every step upload as one new Clipy recording, named "Re-check:" plus the original's title. Each frame carries a caption with the step number, the result and the reason, and those captions become the recording's timestamped narration, so the watch page reads like a walkthrough of the replay. The report links both the watch page and the .arec context document.
That makes it a natural fit for the proof step at the end of agent work. Your agent fixes the bug, re-checks the original recording, and puts two links in the pull request description: the bug as it was reported and the same workflow replayed on the fixed build. Reviewers open the watch link with no signup to watch; other agents read the .arec. If you already ask agents for proof, recording proof of an agent's UI fix covers the wider pattern, and the proof docs cover clipy proof for screenshots and existing videos.
The report files are written before the upload, so a network hiccup never costs you the result. --no-upload keeps everything local when the frames show something that should not leave your machine.
Can a re-check run as a regression check?
Yes. Add --fail-on-divergence and the command exits with code 4 unless the verdict is matches. Add --json and the full report goes to stdout: the verdict, the first diverging step, each step's expected and observed state, the original key-moment frame URL next to the new screenshot path, and the links to the re-check recording.
clipy recheck 7hq2mz4kd0pe \
--url https://staging.example.com/reports \
--fail-on-divergence --json > recheck.jsonPick the recordings that matter most (sign-up, checkout on a test account, the export your biggest customer relies on) and re-check them before a release, in a pre-merge script, or in any job that can reach a running Chrome for Clipy. When a run fails, the JSON tells you whether a control was renamed, a route moved or a dialog got in the way, and the frames show it.
A few knobs exist for slower apps: --settle-ms sets how long to wait after each action, --nav-timeout-ms how long a navigation step waits for the recorded route, and --max-steps caps the replay (up to 50 steps).
How do you set up clipy recheck?
Three commands get an agent ready:
npx @clipy/cli setup claude # or codex, cursor, windsurf, opencode
clipy chrome start # sign in to your app once in that window
clipy recheck <id> --plan # see the steps first, no browserclipy setup signs you in, installs the Clipy skill and registers the MCP server for the agent you name. The skill already teaches the agent when to re-check: when you ask whether a recorded flow still works, or before it replays recorded steps on its own. Chrome for Clipy is the agent-owned Chrome that the CLI drives; sign in once to the apps your workflows need and it remembers. The re-check also uses Playwright (the same one Chrome for Clipy sessions use) and ffmpeg for the upload. Full flags are in the CLI docs, and the agents guide covers Claude Code, Codex, Cursor and the rest.
The recording needs click or navigation data, which is what Clipy captures from the Chrome extension, Chrome for Clipy, and the apps for Mac and Windows. Every one of those takes already carries the interaction timeline with element labels that the re-check replays.
Where does recheck fit in the Clipy agent workflow?
Record your screen, say what you want, share one link: people and agents both get the full context. The AREC format is what makes that link readable by agents: transcript, key moments with frames, clicked element labels and the expected result, in one document. The same timeline that told your agent what you clicked now lets clipy recheck check whether those clicks still lead where they used to.
So a recording is no longer only a record of the past. It is a bug report on day one, the fix's proof on day three, and a regression check every release after that. More on the agent side of Clipy is on the for agents page.
Frequently asked questions
What does clipy recheck need from a recording?
Click or navigation data. Recordings from the Chrome extension, Chrome for Clipy, and the Mac and Windows apps carry an interaction timeline with element labels, page routes and scrolls, and that is what the re-check replays. It also reads the key moments and transcript, and the expected result when the recording has one.
Does it click by screen position?
No. Clicks are replayed by the recorded element label only, matched against each control's own accessible name. Position is used only to choose between two controls with the same name. A click with no recorded label is reported as could not map step and is never clicked.
Will it delete or buy something in my app?
Not on its own. Controls whose names read as irreversible, such as delete, pay, send or submit, are skipped and reported as could not map step. Pass --allow-destructive only on a site where those actions are safe, like staging or a test account.
Can I re-check on staging or localhost instead of production?
Yes. Pass the staging or localhost page as --url. The recorded paths are checked on that host, and nothing is clicked on any other host, so a redirect back to production shows up as a different screen.
How do I use it in CI?
Add --fail-on-divergence. The command exits with code 4 unless the verdict is matches, so a diverged or incomplete run fails the job. Add --json to get the full report on stdout, including summary.verdict and summary.firstDivergence.
Who can watch the re-check recording?
Anyone you share it with. The frames upload as a normal Clipy recording with a watch page and an .arec context document, shared like any other Clipy link, with no signup to watch. Your agent reads the .arec, your reviewer opens the watch link.
Next time a fix ships or a page gets redesigned, do not wonder whether last week's recording still holds. Ask your agent to re-check it and read the answer step by step. Clipy is free to start with a 7-day free trial, no card needed: get the apps and the extension, run npx @clipy/cli setup claude, and record the workflow you care about most.