# Record and replay

A recording keeps everything your app did during a session: renders, screens, store changes, requests, errors and metrics. Replay it later and the Inspector, Performance and Analytics screens all work on it as if the app were running.

## Record a session

In Studio, press **Record session** in the device panel’s **Capture** menu. From the terminal:

```shell
squiggle record                          # until you press Ctrl-C
squiggle record checkout --duration 60   # named, for 60 seconds
squiggle record -o ./repro.sqrec         # to a file of your choice
```

Recordings are `.sqrec` files in `.squiggle/recordings/`. They aren’t videos: they hold what the app did, so they stay small and every tool can read them. `squiggle record` works while Studio is open. When an agent runs a program, a recording starts on its own, so a failure already comes with its replay.

## Replay it in Studio

Open a recording on the Replay screen. You get a timeline to scrub, play at ×1, ×2, ×4 or as fast as possible, with markers where the screen changed. Under the timeline, a lane for each metric the recording has (renders per second, CPU, memory, frame rate, event-loop lag) shows its value at the playhead. Beside it, a list of events (screen changes, taps, errors, logs, requests, long tasks) highlights where you are; click one to jump there.

Click a component in the graph to see, at that moment, how often it had rendered, why it last rendered, and which props, state or context keys changed. A recording keeps which keys changed, not their values.

## Share and follow up

- The Performance and Analytics buttons on the Replay screen open the run the recording was made in. The Performance timeline moves with the replay’s playhead.
- **Copy report** copies the cause, the stack, the numbers and the steps that led there as Markdown, ready for a ticket.
- **Make flow** turns the taps and screen changes into a draft flow in `incidents/`. Add the assert that should hold, and the bug has a test.

## Replay from the terminal

```shell
squiggle replay                          # list recordings
squiggle replay checkout                 # replay one
squiggle replay checkout --speed 2
```

There is no device to wait for, so a replay runs as fast as possible unless you set `--speed`.

> **Recordings stay on your Mac**
>
> `.squiggle/recordings/` is ignored by git. To keep a recording, attach it to the ticket or bug it belongs to.

## More

- [Incident capture](https://squiggle.sh/docs/replay/incidents): Studio saves the seconds before a crash, error or slowdown.
- [Check recordings offline](https://squiggle.sh/docs/replay/offline): Assert a flow against a recording, or compare two.

To turn a recording into a flow from the terminal, see [Record and crawl](https://squiggle.sh/docs/flows/record).