> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pikopod.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Replay gate

> Gate builds offline on recorded traffic against frozen baselines.

```bash theme={null}
pikopod replay --ci
pikopod replay --ci examplepay --handoff replay.json
```

```text theme={null}
examplepay: 37 recordings gated (1 pre-warmup skipped) — 0 finding(s)
clean — no drift against frozen baselines
```

`replay --ci` reads each recorded response from `<data_dir>/recordings/<upstream>.ndjson` and diffs it against its frozen baseline family, entirely offline. No network, no provider account, no running agent.

## What it compares

Each JSON recording is matched to its `(method, template, status class)` family and diffed the same way live traffic is: fields added or removed, types changed, values outside the known set, a field arriving null, a status code moving within its class. Findings are deduplicated per method, template, kind, field and detail.

```text theme={null}
examplepay: 37 recordings gated (1 pre-warmup skipped) — 2 finding(s)
  DRIFT field_removed    GET /charges/{id}  refunded_at string
  DRIFT type_changed     GET /charges/{id}  amount string

drift found — failing the gate (exit 1)
```

## What it skips

* Recordings whose family is not frozen yet. They are counted as pre-warmup skipped.
* Non-JSON recordings.
* New values on fields listed in `volatile_fields`. Presence, type and nullability of those fields are still checked.

## Exit codes

| Exit | When                                                                                                |
| ---- | --------------------------------------------------------------------------------------------------- |
| `0`  | Every gated recording matched.                                                                      |
| `1`  | Drift found.                                                                                        |
| `2`  | No baselines or no recordings for an upstream, which is a tool problem, never conflated with drift. |

## In CI

The gate needs the `data_dir` the agent wrote, or a copy of it. Ship the `baselines/` and `recordings/` directories as an artifact, or mount the volume read-only:

```bash theme={null}
./pikopod replay --ci --handoff replay.json
./pikopod pr comment --handoff replay.json
```

The handoff is `{"source":"replay-ci","records":n,"findings":[…]}`. See [CI integration](/gate/ci-integration).

## Recordings as scenarios

For a regression suite that does not need the agent's data at all, turn a traffic window into an ordinary scenario pack and commit it:

```bash theme={null}
pikopod scenario from-recordings examplepay --last 20 --name checkout-flow
```

See [Generated packs](/scenarios/generated-packs).