> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# Record and replay
> Do the thing once on your desktop, and turn it into a reusable skill
Record and replay solves one specific problem: **you know how to do it, but explaining it is harder than doing it**. Some workflows are fiddly, depend on exact UI positions, and take longer to describe than to perform. So perform it once, with the expert watching, and turn that into a skill.
## Activation
`profy-record-and-replay` is `user_selectable: true` with `requires: { desktop_connected: true }`. Enable it in the plugin panel and run Profy Desktop.
**Native event-stream recording is macOS-only.** Calling it elsewhere returns:
```
Native event stream recording (profy-event-tap) is only available on macOS.
On Windows/Linux, use CUA Driver recording instead (cua-recording skill).
```
The capture depends on the macOS event tap (the `profy-event-tap` native binary), which has no cross-platform equivalent.
## Three tools
| Tool | Purpose |
| --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `event_stream_start` | Begin recording; returns `sessionId`, `eventsPath`, `metadataPath`, `maxDurationMinutes`, `audioRecording` |
| `event_stream_stop` | End and finalize; returns final metadata including event count and `audioTranscriptPath` |
| `event_stream_status` | Whether a recording is currently active |
## What gets captured
Three streams run in parallel, all written to `~/.profy/recordings/{sessionId}/`:
| Stream | File | Notes |
| --------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Events | `events.jsonl` | One event per line: app name, window title, action type, details |
| Screenshots + AX tree | `snapshots/{timestamp}-{trigger}.png` + `.json` | Every **10s**, with a **2s** minimum interval; near-identical consecutive frames are deduplicated |
| Voice narration | Audio + transcript | Starts automatically when the mic is available; degrades gracefully if denied |
| Session metadata | `session.json` | Start/end time, end reason, total event count |
**Recording captures the whole desktop, not just the current app.** All apps, all windows, every click and keystroke. Switching apps or minimizing the chat does not interrupt it — only `event_stream_stop` or the **30-minute timeout** ends a session.
Which means: avoid unrelated private activity while recording, and be especially careful with password entry.
## Voice narration is the most valuable stream
With events alone, the expert sees "clicked at (840, 312)" and has no idea why. The transcript is timestamped, so aligning it with events supplies the missing layer:
> "Now I'm filtering this column out, because last quarter's data doesn't count toward the total."
A narrated recording distills into a skill **with decision criteria**. An unnarrated one distills into **steps replayed in order**. That is a large difference. So: **talk while you work**.
If mic permission is denied, recording proceeds without that stream.
## The standard flow
"I'm going to record something — turn it into a skill." The expert calls `event_stream_start` and then **ends its turn**.
Switch to the target app and complete the workflow normally. An overlay indicates recording is active. Say your reasoning out loud throughout.
The expert calls `event_stream_stop` and reads the events, snapshots, and transcript.
The recording contains everything that happened, including your detours, misclicks, and the window you glanced at. The expert summarizes the workflow it understood and turns it into a skill **only after you confirm**.
The skill lands in your global skill library (`user/*`) and is available in any expert's conversation.
**The expert ends its turn during recording rather than waiting.** This is a hard design constraint: you cannot demonstrate anything while the model holds the turn, and polling both burns tokens and blocks the very thing being recorded. So the expert appearing to "stop" is correct — it is waiting for you to come back.
## Skills bundled with the plugin
Beyond recording itself, the plugin ships app-specific skills used to interpret particular interfaces during replay:
`record-replay` (recording-to-skill methodology), `cua-driver` (driver-layer reference), `cua-recording` (the cross-platform driver recording path), `app-clock`, `app-numbers`, `app-spotify`, `app-notion`, `app-music`, `app-iphone-mirroring`.
## Failures and what to do
| Symptom | Cause | Fix |
| ---------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `only available on macOS` | Not on macOS | Use the `cua-recording` skill and the driver recording path |
| `Capture process exited with code N` | The event tap never attached — almost always denied Accessibility permission | System Settings → Privacy & Security → Accessibility, enable Profy, then start again |
| `A recording is already in progress` | Only one recording at a time | Call `event_stream_stop` first |
| `No active recording to stop.` | No session running | Start one first |
| `recorder tools require the Profy Desktop app` | Sidecar not connected | Launch the desktop app |
| Recorded, but zero events | Another face of the permission problem | Same as above — check Accessibility |
| The distilled skill has the wrong steps | The recording included detours | Say which parts to drop at step 4, or record a clean take |
Start calls `waitUntilCapturing()` and only reports success once the tap is genuinely attached. That check exists because a denied permission used to produce a confident "started" with an empty session, which is far harder to diagnose than an error.
## How it differs from Chrome workflow reuse
Both attack repetitive work, but at different scopes:
| | Record and replay | Chrome workflows (AT2T) |
| -------- | ------------------------------------ | ----------------------------------------------- |
| Scope | The whole macOS desktop, across apps | Inside Chrome only |
| Output | A skill (natural language + steps) | A template (structured steps, zero-LLM replay) |
| Trigger | You explicitly ask to record | The expert calls `match_workflow` automatically |
| Best for | Cross-app flows, native apps | Repetitive operations on one site |
## Keep reading
The layer that executes during replay
Workflow reuse inside the browser
The three ownership tracks for skills
All 28 built-in plugins and their activation conditions