RETAKE / DOCUMENTATION

From a request
to a reviewed demo.

Tell your coding agent what the viewer should see. Retake drives a browser through the workflow, saves the recording and gives you a video to review.

The demo lives in a file. A YAML manifest holds the URL, actions and scene captions. Fix the interaction and record again, or change the presentation and render the existing take.

Retake records a web app in one browser tab. It is not a general desktop or native mobile screen recorder. You run it in a local workspace; your agent helps write and check the workflow.

Start with installation ↓Already installed? Review the loop →

01 / GET STARTED

Install & open the window

You need Node.js 20 or newer. Run these commands in your terminal, one at a time. The package bundles ffmpeg; setup downloads Chromium if it is missing.

Terminal · new workspace

npm install -g retake-demos
mkdir my-demos && cd my-demos
retake install
retake doctor
retake ui

Keep that terminal open, then open http://localhost:4310. This is the Retake window, not your app. Your app must be reachable at its own public or localhost URL.

retake install creates demos/, outputs/, .env and ignore rules. It attempts to register Retake with Claude Code and installs its recording skill. Read the terminal output: registration can fail even when the workspace was created.

Prefer not to install globally?

Use npx retake-demos install inside your workspace. The other commands on this page assume the global install. With npx, replace the retake prefix with npx retake-demos.

Source: README: Install · CLI setup and doctor

Connect your coding agent

MCP is the connection that lets an agent call Retake’s tools. You can also use the CLI before the tools are connected. Run the following inside the workspace you want to record into:

Terminal · print your client configuration

retake agent

The output contains the actual command, arguments and workspace path for your installation. Use that output rather than copying a guessed server path from a tutorial. Preserve any other MCP servers in your client configuration.

Claude Code

retake install attempts user-scope MCP registration through the Claude CLI. If it reports success, restart Claude Code. If the CLI was missing or registration failed, use the Claude Code registration command printed by retake agent, then restart.

Codex

retake agent prints a [mcp_servers.retake] block for ~/.codex/config.toml. Add the generated block without replacing unrelated settings, then restart Codex. The tool descriptions carry Retake’s workflow.

Cursor

retake agent prints JSON under mcpServers for .cursor/mcp.json or the equivalent MCP settings in your client. Merge the generated Retake entry, then reload or restart the client so it loads the server.

These are the configuration paths Retake’s CLI prints, not a claim that every client version has been tested. If your client uses a different registration UI, use the generated command, args and env there.

Copy this request to your coding agent

Help me connect Retake to this coding agent.
From my Retake workspace, run retake agent and use the configuration
it prints for this client. Preserve existing MCP servers and settings.
Tell me what changed and whether I need to restart.
Do not start my app or record anything yet.

A client session does not gain new tools mid-conversation. Restart it after setup. Outside the Retake window, starting your app requires explicit permission and the RETAKE_ALLOW_START=1 MCP environment setting. Leave that disabled unless you want it.

Source: CLI: install, agent and mcpServer · Tool permissions

Ask for your first demo

Start with one visible outcome. Give the agent a URL, the task and any action it must not confirm. You do not need to write YAML yourself.

Example prompt · replace the app URL and workflow

Use Retake to record my app at http://localhost:3000.
Show a new user creating a project and finding it in the dashboard.
Start with a silent preview. Keep the camera static.
Use a demo account. Hide account details and stop before any paid action.
Inspect the real page before choosing selectors. Validate and dry-run
before recording. Show me the preview and proof log for review.
Do not add narration until I approve the recording and its script.

This is an illustrative request, not a tested workflow for your app. The agent must inspect your actual routes and selectors. Ask it to save the manifest in demos/<name>.yaml, where the Retake window can find it.

Use the Retake window to watch progress and review the result. Ask your agent for a silent first take explicitly; the CLI records and renders according to the manifest’s settings.

Record, review & rerun

First prove the browser steps. Then record a silent first take, inspect it, and render presentation changes from the saved recording. The commands below use an existing, agent-authored manifest named demos/my-demo.yaml with name: my-demo. They do not create that file.

CLI examples are aligned with published Retake 0.14.1. Read the release’s CLI source. Before a silent take, set voiceover: false in the existing manifest and omit music. Music is an optional file string or object, not a boolean. run follows the manifest; it does not automatically force silence.

Terminal · validate, dry-run, record

retake validate demos/my-demo.yaml
retake dry demos/my-demo.yaml
retake run demos/my-demo.yaml --no-master
retake check outputs/my-demo

Validate checks the schema and warnings.
Dry-run visits the app and performs selectors and waits without recording. It can still change app state. Use safe test data.
Run records the browser and renders the take using the manifest’s settings.
Check checks the media and output files. A pass does not prove the story, privacy or visual result is correct.

Watch before you finish

Open demo.mp4 in the window. Read proof-log.md and inspect the scene stills. Watch the whole cut: can you see the action and its result, read the important text, and confirm there is no private data, including during transitions?

Your agent can use receipts to read step results and look to inspect frames. Neither replaces watching the exact final MP4. Hold delivery if an important check cannot be completed.

Terminal · after preview review and any render-only edits

retake render outputs/my-demo demos/my-demo.yaml --preset post-landscape --no-master
retake check outputs/my-demo

Watch this rendered file again before sharing it. render uses the saved take and the current manifest to produce a new cut; it does not record the browser again. The manifest must still describe the actions in that take.

Which kind of change?

Words, captions, cards, music, pacing or format: edit the presentation and re-render the existing take. Review the resulting MP4 before sharing it.

Clicks, routes, fixtures or visible page state: repair the manifest, validate and dry-run again, then record the browser again:

Terminal · check the changed flow and record again

retake validate demos/my-demo.yaml
retake dry demos/my-demo.yaml
retake run demos/my-demo.yaml --no-master
retake check outputs/my-demo

This run performs a new browser recording. Confirm that another take is wanted before running it, and keep any approved deliverable safe before changing its output.

Source: Published 0.14.1: run and render · run, render, receipts and look tools

Voiceover & captions

Choose voiceover, captions, both, or neither. They are separate presentation choices. A silent video can have captions; narration does not require visible captions.

Keep the first preview silent. Approve the recording, then read and approve a continuous narration script before speech is generated. For a silent CLI take, explicitly set voiceover: false and omit music in the existing manifest before running it. Do not assume the recording command overrides sound settings.

Voice choices depend on the version and provider configured in your workspace. Edge uses a speech service; local voices, where available, require their own model setup. Do not assume every voice supports your language or that every option runs without downloads or network access.

Example request · independent presentation choices

Keep this preview silent. Turn visible captions off for the final cut.
After I approve the recording, show me a continuous narration script.
Wait for my script and voice approval before generating any speech.
Use the existing take for narration and presentation changes.
Review the final MP4 for audio timing and a complete ending.

For manifest editing, captions: false disables visible captions. Do not use a voice setting as a substitute for script approval. Ask your agent to follow the current voice setup in your workspace rather than guessing a provider configuration.

Source: Published sound and caption settings · Caption controls

Find your files

Run commands from the same workspace. Keep the manifest in demos/ and preserve the raw take if you want to re-render later.

Workspace · typical output, not a command

demos/my-demo.yaml
outputs/my-demo/
  demo.mp4         # rendered video to review and share
  stills/          # scene images
  thumbnail.png    # poster
  proof-log.md     # step results, timing and failures
  take.json        # recording timeline used by the renderer

--no-master skips the optional archival master.mp4. Launch cuts and other output choices can add covers, GIFs or contact sheets. Do not expect every optional artifact in every run.

Rendered is not reviewed. Reviewed is not approved. Approval means a person accepted that exact file, not just its manifest or an earlier preview.

Source: README: output files

03 / WORK SAFELY

Privacy & provider costs

The workspace and rendering are local. That does not make the whole workflow offline or free: installation downloads packages and Chromium, recording contacts the target app, and your coding agent may send context to its provider under that provider’s plan.

Optional model-backed drafting, suggestions and visual judgments can use a configured provider. Visual checks can send frames to a model. Speech choices can need network access or model downloads. Confirm providers, data boundaries and any charges before enabling them. Local capture is not permission to use a paid model key.

Use a demo account. A login is saved once per site and every demo of that site signs in with it. When a demo needs one, the Retake window asks with a small form; without the window, save it in your own terminal. Do not paste passwords into agent chat.

Terminal · save a demo login for one site

retake login https://app.example.com

On a Mac the login is kept in your Keychain, not in a project file. The agent signs in with ${LOGIN_USER} and ${LOGIN_PASSWORD} marked secret: true in auth.setup, before the camera, and never sees the values. The session is kept in .auth/ and Retake signs in again by itself when it runs out. retake logins lists the saved sites; retake login <url> --forget removes one. Older demos that use ${APP_PASSWORD} from .env keep working.

For a login that needs a person, such as SSO or an SMS code, choose Sign in by hand in the window's form, or:

Terminal · human sign-in

retake login https://app.example.com --by-hand

A real browser opens. Sign in yourself, then press Enter in the terminal to keep the session. secret: true hides logged values, not pixels in the video. Omit unsafe screens or cover private regions and review navigation transitions. Never approve a paid action just to make a demo pass.

Source: README: login and secrets · Agent tools and visual checks

Troubleshooting

The agent cannot see Retake’s tools

Check setup output. Run retake agent from the correct workspace, apply the client’s generated configuration and restart the agent. Until then, the local CLI remains available.

The window or app does not open

Run retake ui in the workspace and keep its terminal alive. The default window is http://localhost:4310. Your app is a separate server. Check its actual URL and port; do not have an agent start a process without your permission.

Chromium or ffmpeg is missing

Run retake doctor. If Chromium is missing, follow its retake install guidance. ffmpeg is bundled with the package; doctor reports a missing binary separately. Read the error before repeating a recording.

A selector fails or the preview shows the wrong state

Read proof-log.md. Have the agent inspect the real page, fix the selector or wait for the visible result, then validate and dry-run. Do not keep recording a failing flow. A reusable workflow is not self-healing.

A render fails or does not show my changed workflow

Check that the output contains take.json and its saved recording, and that you supplied the correct manifest. Rendering changes the presentation of an existing recording; it cannot add a browser interaction that was never captured. For changed clicks, routes or page state, validate and dry-run the repaired manifest, then use retake run demos/my-demo.yaml --no-master to record again.

The video exists but is absent from the library

Check that its manifest still lives in demos/. Do not delete the manifest after rendering. retake heal can recover missing manifests from saved recordings; inspect what it proposes before applying recovery.

The workflow needs another window or a very long take

Retake records one tab. Its default keepInTab folds new-tab links into that tab, but true multi-window flows are outside this scope. Split long stories into short demos. The README notes an approximate 180-cursor-move limit per take and that macOS is used daily; Linux is not verified beyond CI.

Still blocked? Report an issue with the command, package version and a redacted error or proof log. Do not attach credentials, session files or private video frames. Known limits

Source reference

The CLI examples follow published Retake 0.14.1; the linked production guides also describe review practices and may evolve separately. Setup and recording examples are documentation, not proof that your app or client configuration has been tested.

READMEInstallation, workspace, login, outputs and limits.
CLI sourceActual commands, flags and generated client configuration.
MCP toolsTool behavior, recording review and permissions.
Recording skillThe agent’s recording and review method.

From a request to a reviewed demo.