ancha replay

ancha replay runs your current agent against one attempt’s saved world and seed. People answer from their recording while the conversation matches. The result shows the first different agent action and the checks whose outcomes changed.

ancha replay [options] <attempt>

Argument	Description
`attempt`	`<run-id>/<trial-directory>` or `latest/<trial-directory>`, for example `latest/trial-support-reply-1`.

Option	Description
`--agent <cmd>`	Command to run the agent. Defaults to the agent in your current `ancha.yaml`.
`--people <mode>`	`live` or `strict`. Controls what happens when people cannot answer from the recording. See below.
`--out <dir>`	Directory containing the recorded run. The replay is saved here as a new run. Default `.ancha/runs`.
`--pass-env <name>`	Give the agent this shell variable. Repeat for each variable.
`--inherit-env`	Give the agent the whole shell environment, including any real credentials it contains.

Global options such as --json, --config and --local also apply. See CLI overview.

Choose an attempt

Use a finished local ancha run attempt. Its directory is listed in scenes[].trialsDetail[].dir in ancha report <run-id> --json.

ancha report latest --json
ancha replay latest/trial-support-reply-1 --people strict --json

Replace trial-support-reply-1 with the directory from your run. To keep comparing against the same original attempt, use its run ID instead of latest: a replay writes a new run and updates latest. The original run must still have inputs.json with the saved case, and the attempt must have trace.jsonl and checks.json. Replay also reads people.jsonl when it exists. An older run without the saved case cannot be replayed. Replay uses the recorded scene and checks. It reads the agent settings from your current config, so you can edit the agent and replay the same attempt:

ancha replay run_example/trial-support-reply-1 --agent "node agent.mjs" --people strict

Replace run_example/trial-support-reply-1 with your original attempt. Use ancha explain or ancha report with the new run ID to inspect the replay.

People after a change

Mode	Behavior
`live`	Reuse recorded answers while the conversation matches. After a mismatch, people answer through a model. This needs `OPENROUTER_API_KEY`, a signed-in workspace, or a world server that can answer.
`strict`	Reuse recorded answers. If a person needs an answer the recording cannot supply, stop replaying their conversation and mark the replay invalid.

With people in the world, the default is live when a model is available and strict otherwise. A world without people defaults to live and needs no people model. A different agent write appears in diverged. It does not by itself make a strict replay invalid. When a person’s conversation no longer matches the recording, people.divergence explains why. A strict replay then has comparable: false, valid: false and invalidReason: "diverged", and exits 3. Do not use those check outcomes to judge the agent.

Output

With --json, replay prints NDJSON: run_started, trial_started, trial_finished, then replay_finished. The last event contains the comparison, rather than a run_finished event.

Field	Meaning
`replayOf`	Original attempt as `<run-id>/<trial-directory>`.
`runId`	New run containing the replay.
`peopleMode`	`live` or `strict`.
`diverged`	`null` if the agent’s writes match. Otherwise `{ atAction, recorded, now }`: the first difference, numbered from 1. A missing action is `null`.
`people`	`replayed` and `live` answer counts, and `divergence`: the first conversation mismatch, or `null`.
`comparable`	`false` when strict mode could not continue a person’s conversation.
`valid`	Whether the replay can be judged as an agent result.
`invalidReason`	Present when invalid: `diverged` for strict conversation replay, or `harness` for an execution problem.
`checks`	Each check’s `id`, `required` and `passed`, plus `was` when its recorded outcome is available.
`changed`	IDs of checks whose outcomes differ from the recording.
`next`	The `ancha explain` command for the new run.

The action comparison excludes GET and HEAD. It also excludes Slack methods ending in list, history, replies, info, test, members, lookupByEmail or open. See JSON events. ancha schema replay_finished prints the complete schema.

Exit codes

Code	Meaning
`0`	The replay is valid and its required checks pass.
`1`	The replay is valid but its verdict is `fail`.
`2`	Invalid arguments, an unavailable attempt, a config error, or live people without a model.
`3`	The replay is invalid: a strict conversation diverged or execution failed.

Get started

Guides

Concepts

Tools

CLI

Reference

Cloud

Help

ancha replay

Choose an attempt

People after a change

Output

Exit codes

​Choose an attempt

​People after a change

​Output

​Exit codes

Choose an attempt

People after a change

Output

Exit codes