---
title: Replay a session on another model
description: Re-run a recorded session's prompts against another model, gear or route profile in a scratch workspace with venom replay, and compare turns, tokens, cost, tools and a check command.
section: automation
order: 90
audience: [user, operator]
sources: [cli/src/replay.ts]
features: [automation.replay]
---

`venom replay` answers "would a cheaper model have done this as well?" with your own work. It takes a saved session, replays its user prompts against another model, gear or route profile in a fresh scratch workspace, then prints original against replay: turns, tokens (in, cached, out), dollar estimate, tool calls by name, files changed, and the result of a check command. Your working tree is never written.

## Example {#example}

```bash
venom replay latest --gear eco --dry-run                  # the plan and the cost estimate, no model call
venom replay latest --gear eco --check "npm test" --max-usd 0.50
venom replay 01a1359f --model qwen3:8b --check "npm test"  # a local model needs no cap
```

## Reference {#reference}

```text
venom replay <session> [--model <id>] [--gear <name>] [--profile <p>] [--thinking <level>]
                       [--mode <mode>] [--from <ref>] [--check "<cmd>"] [--max-usd <n>] [--dry-run] [--json] [--keep]
```

| Flag | Default | What it does |
|---|---|---|
| `<session>` | required | A session id, an id prefix, `latest`, or a session `.jsonl` path. |
| `--model`, `-m <id>` | the gear's, else `VENOM_MODEL`, else `venom-default` | The replay's model. |
| `--gear <name>` | none | A gear: its model, thinking, route profile and mode. |
| `--profile <name>` | none | The orchestrator route profile (`x-venom-profile`). |
| `--thinking <lvl>` | the model's | `off`, `minimal`, `low`, `medium`, `high` or `xhigh`. |
| `--mode <mode>` | `yolo` (bash sandboxed) | The permission mode in the scratch workspace. |
| `--from <ref>` | HEAD plus uncommitted changes | Start the workspace at this commit. |
| `--check "<cmd>"` | none | Run this in the workspace afterwards; pass is exit 0. |
| `--max-usd <n>` | none | Stop when the replay's list-price cost reaches this. Required for a paid target (a priced model, a cloud alias, an upstream off your network). |
| `--dry-run`, `-n` | off | Print the prompts, target, budget and estimate; call no model. |
| `--json` | off | Machine-readable plan or outcome. |
| `--keep` | off | Keep the scratch workspace and print its path. |

The scratch workspace is a git worktree at HEAD plus your uncommitted changes, or a copy of the directory outside git. The upstream is `VENOM_BASE_URL` (default the local orchestrator, `http://localhost:8787/v1`). Hooks, plugins, MCP servers and subagents are off in the replay, and images in prompts are not replayed.

Exit status: 0 done; 1 the replay stopped early or `--check` failed; 2 bad arguments or a missing cap.

## Troubleshooting {#troubleshooting}

| Message | What to do |
|---|---|
| `which session?` | Pass an id, prefix, `latest` or a `.jsonl` path. |
| Exit 2 asking for `--max-usd` | The target is paid. Run `--dry-run` for the estimate, then set a cap. |
| The replay diverges early | Replays send the same prompts, not the same answers; a different model takes different paths. Compare with `--check`, not turn by turn. |

## Related

- [Code review](/docs/automation/review.md) can judge the replay's diff if you keep the workspace with `--keep`.
