Skip to content
Docs menu

Replay a session on another model

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.

View .md

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

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

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

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.
  • Code review can judge the replay's diff if you keep the workspace with --keep.