> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videodb.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Record & Replay
> Record a desktop workflow once and compile it into a reusable skill that an AI agent can follow later
Complete source code, installation guide, and troubleshooting
## What Is It?
Record & Replay turns a workflow you perform on your desktop into instructions an AI agent can reuse. It supports macOS and Windows.
You demonstrate the task once while the app records the desktop interactions. It then combines the action log with optional visual context from VideoDB and compiles the result into a structured, human-readable agent skill.
The result is not a fixed macro. The generated skill describes the task, starting state, inputs, actions, and checks an agent needs to repeat it. Values such as search terms, dates, choices, and file paths can become inputs instead of being copied as fixed values.
**The Idea**: Show the workflow once, let Record & Replay turn the demonstration into a reusable skill, then give that skill to your agent for future runs.
## Why Use Record & Replay?
### Demonstrate the Real Workflow
Perform the task in the app you already use. Record & Replay captures desktop accessibility events and can include screen video as visual reference.
### Move Beyond One-Off Recordings
The compiler turns the demonstration into `SKILL.md` and `SKILL.json` files with steps, expected inputs, verification guidance, and an execution strategy.
### Keep Recording Without Video
Native accessibility hooks capture workflows on macOS and Windows. If full screen capture is unavailable, Record & Replay can still compile from accessibility events alone.
## How It Works
Ask your agent to start recording a named workflow. A short lead-in can give you time to switch from the agent to the app where the task will happen.
Complete the workflow yourself. Native accessibility hooks capture the actions and interface metadata. When screen capture is available, VideoDB adds visual context.
The compiler combines the event log and available visual context, identifies reusable inputs, and generates structured and human-readable skill files.
By default, the generated `SKILL.md` is installed in `~/.codex/skills/`. You can point the installer at another global skills directory for agents that consume the same skill format.
**Human-in-the-loop recording**: You perform the demonstration yourself. Record & Replay creates the skill, but it does not include a standalone replay engine—the agent that consumes the skill performs the workflow later.
## What the Skill Contains
A readable sequence of actions that explains how to complete the demonstrated workflow.
Values such as search queries, dates, dropdown choices, and file paths can be represented as inputs rather than copied as fixed values.
The generated skill includes checks and guidance that help the consuming agent confirm whether the workflow succeeded.
Each structured skill records a preferred execution strategy, such as browser, desktop app, terminal, file system, or a hybrid workflow.
## Getting Started
**Prerequisites**
* Python 3.10+
* [uv](https://docs.astral.sh/uv/) package manager
* A [VideoDB API key](https://console.videodb.io/auth?utm_source=docs_videodb_io\&utm_medium=docs_link\&utm_campaign=console_auth\&utm_content=docs_link\&id=docs)
```bash theme={null}
git clone https://github.com/video-db/open-record-replay.git
cd open-record-replay
uv sync
```
Create a `.env` file in the project root:
```env theme={null}
VIDEODB_API_KEY=your_VIDEODB_API_KEY
```
Add the server to your MCP client configuration:
```json theme={null}
{
"mcpServers": {
"videodb-record-replay": {
"command": "uv",
"args": ["run", "python", "server.py"],
"cwd": "/path/to/open-record-replay"
}
}
}
```
Restart your MCP client so the Record & Replay tools and skill resources become available.
## Record Your First Workflow
Recording is guided by your agent:
1. Ask the agent to record a named workflow.
2. Switch to the target app and perform the task.
3. Return to the MCP client and ask the agent to stop recording.
4. Ask it to compile the recording into a skill.
5. Confirm the global `SKILL.md` path reported by the agent.
Use a short lead-in before the workflow begins and trim the end of the recording if you need time to switch back to your MCP client. This keeps navigation to and from the client out of the generated instructions.
## Platform Notes
Screen Recording, Microphone, Accessibility, and Input Monitoring permissions may be required. Run the permission helper before recording:
```bash theme={null}
uv run python scripts/smoke_macos_hook.py --prompt-permissions
```
Record & Replay uses Windows UI Automation. No additional setup is required beyond the standard installation.
***
Tool reference, skill output details, platform setup, and troubleshooting
## Related Tutorials
Give coding agents real-time screen and audio context
Record, inspect, and search autonomous agent activity
Learn how VideoDB desktop capture works