Skip to main content

​
Resume & Replay

When a run fails or you want to redo part of it, Gump offers two recovery modes with different trade-offs.

​
Resume

Continue where you left off. The worktree stays as-is, sessions are preserved. 
gump run --resume
Use resume when the run crashed unexpectedly (network issue, agent timeout, process killed) and you want to pick up from the last completed step. The agent can continue its session if session: reuse is configured. To resume a specific run: 
gump run --resume --run <uuid>

​
Replay

Start fresh from a specific step. The worktree is reset to the state before that step. 
gump run --replay --from-step impl
Use replay when you want a clean re-execution — maybe you changed the workflow YAML, adjusted a prompt, or want to try a different agent. The worktree is restored to a known good state (the snapshot commit before the target step).

​
Differences

AspectResumeReplay
WorktreeAs-is (diff from last attempt in place)Reset to pre-step commit
State bagReloaded, all outputs preservedReloaded, target step’s outputs cleared
Agent sessionsPreserved (resume possible)Lost (fresh session)
Retry countersResetReset
Use caseContinue after a crashClean re-execution from a known state

​
Limitations

Both resume and replay restore the code and the state bag. They do not restore:
  • Dependencies (if go.sum or package-lock.json changed externally)
  • Runtime versions (Go, Node, Rust updates between runs)
  • External state (databases, APIs, services)
  • Agent sessions (for replay — they’re lost because the worktree is reset)
Full environment reproducibility (via Docker or containers) is planned for a future release.

​
When to use which

The run crashed mid-step → --resume. The worktree has the partial work. The agent can continue. A gate keeps failing and you changed the prompt → --replay --from-step. Start the step fresh with the new prompt. You want to re-run with a different agent → --replay --from-step. The worktree resets and the new agent starts clean. The plan was bad and you want to start over → just run gump run again. A new run creates a new worktree from scratch.