Forks

Forking lets you branch from any point in a recorded run, change the input, and re-execute the agent to see how the path diverges. The forks commands manage that workflow.

Create a fork

Branch from a specific span and supply a modified input:

retrace forks create --trace <trace_id> --span <span_id> --input "modified prompt"

Replay a fork

Re-execute the agent along the forked path:

retrace forks replay <fork_id>
retrace forks replay <fork_id> --wait    # Block until the replay finishes

Diff a fork

Compare the original run against the forked result:

retrace forks diff <fork_id>
retrace forks diff <fork_id> --json

The diff highlights where the two runs first diverged and how their outputs differ.

Prove a fix

To confirm that a change actually fixed a run, re-run it and get a verdict (improved, regressed, or unchanged):

retrace traces verify-fix <trace_id>

To find the first step whose change flips the outcome:

retrace bisect --trace <trace_id> --substitutions subs.json

Next steps

• Evaluations — score forked runs.
• CI/CD — gate deploys with offline cassette replay.