CLI: Add /rewind checkpoint restore that reverts both chat context and Codex-applied code edits

Also related to #2948.

This is also a duplicate of #9344, but that issue hasn't received any upvotes. I think this is a better articulation of the feature, so I'm going to close #9344 in favor of this one.

This is something I really miss coming from other tools (i.e. Cursor, Claude Code), would greatly appreciate to have this implemented

Can we distinguish between an "undo" feature and a "restore conversation to this point" feature?

My understanding is that a true "undo" might be more complex to implement reliably, since it would need to reverse prior actions and state changes. In contrast, "restore conversation to this point" seems more like a context management operation, where the conversation state is reverted to an earlier message and everything after that point is ignored.

I can implement the restore logic on my side, but I’m unsure about the correct approach to trimming the context. Specifically, how should I prevent messages after the restore point from being included in the next request? Should those messages simply be removed from the message history before sending the next prompt?

@etraut-openai
please consider providing more context management options.
Claude code at least has restore conversation (restore conversation without trying to restore any code changes)

Editing context past messages would be highly appreciated

@BorisMolch Codex CLI already has a 'restore conversation' feature by double-tapping Esc -- BUT this is different than proper undo/rewind. This issue is for undo/rewind feature that may or may not be coupled with 'restore conversation' feature.

@BorisMolch Codex CLI already has a 'restore conversation' feature by double-tapping Esc. This issue is for undo/rewind feature that may or may not be coupled with 'restore conversation' feature.

Thank you. indeed already possible, will give it another go.
So far the ux is clunky I can't easily restore conversation in a nice flow.

Thank you. indeed already possible, will give it another go. So far the ux is clunky I can't easily restore conversation in a nice flow.

I would search for issue on this and if no satisfactory issues exists, create a new one for improving the UX of conversation restore. You might be able to contribute.

I don't get it. So is there "rewind" feature in Codex CLI or not? E.g. i am used to Claude code. I can REWIND changes OR conversation OR both. I don't care about the damn conversation rewind :) It's important that i can revert / rewind the changes agent made if things go sideways! So is this possible or not? If it is not possible, do not promote double ESC, because reverting conversation is more or less useless. Ask Codex to implement the revert feature if it is not available already, otherwise document it, i cannot find it in docs.

I don't get it. So is there "rewind" feature in Codex CLI or not? E.g. i am used to Claude code. I can REWIND changes OR conversation OR both. I don't care about the damn conversation rewind :) It's important that i can revert / rewind the changes agent made if things go sideways! So is this possible or not? If it is not possible, do not promote double ESC, because reverting conversation is more or less useless. Ask Codex to implement the revert feature if it is not available already, otherwise document it, i cannot find it in docs.

No - the rewind or undo does NOT exist in Codex CLI. Hence this issue. We really need it. Give an upvote if you can.

I think if we're gonna have a rewind/undo feature there should be a toggle for doing it in version control. Every apply_patch can be a commit, and every undo can be a rebase dropping that commit or cherry pick that commit into a stash (undo + redo). The way it appears to currently work is Codex is tracking changes separately from VC. Codex already does not track when an agent uses cat << EOF ... EOF > some_file or any command that edits a file outside of apply_patch, so it makes sense to start with apply_patch -> commit -m "{stable apply_patch identifier}". That would enable you to resume a conversation inside a worktree and restore all of the "undo" points for that conversation.

"Undo" eventually becomes an invalid operation as the codebase evolves, so if it's scoped to a worktree under a specific commit hash, when you eventually PR+squash/merge that worktree and delete the branch you no longer need the undo tracking. It would use version control with good stewardship. That's how I envision a good rewind/undo feature. And as a toggle, for folks using Perforce or other centralized SCM they can just toggle that off and do the double diff tracking like it currently works.

the rewind function should not be like the "undo" and needs to ONLY revert to a previous position in the agent's context. The files on the disk should not have any relation. This confusion is probably why the "undo" in Codex was buggy and difficult to maintain, as you are conflating two separate asks together.

the rewind function should not be like the "undo" and needs to ONLY revert to a previous position in the agent's context. The files on the disk should not have any relation. This confusion is probably why the "undo" in Codex was buggy and difficult to maintain, as you are conflating two separate asks together.

I was aware of this, and the issue mentions an already available feature for this (double -Esc).

The issue is specifically for both conversation as well as file changes revert, for good reason.

I think this is a really important feature to implement. OpenCode seems to have it working really well. It enables a kind of workflow where you can let the model implement stuff, start reviewing and then sometimes decide it's less work to revert, adapt your prompt and let it do it again than letting it adapt 20 things.

Plus one-ing this. It would be a very convenient feature to have. It feels very intuitive in Claude Code and Cursor. Reverting code and conversation to last checkpoint. It should act similar to double escape, but instead of just restoring conversation, it should also restore the files the agent has touched since that point in time.

I understand the user case about conversation restore, but code restore? Aren't folks using this in a git tracked repo?
Adding features like these just bloat the product. Am I missing any specific usecase that users are seeing here?

Also forking from a past history is a great feature!

@rrajpuro This is meant to be a quality of life feature. Making the agent remember to checkpoint with git is context polluting. This feature will maintain the checkpoints out of the agent's context.

The /rewind feature is needed, for returning to a previous point in the conversation with the agent, and needs to have NOTHING to do with the state of the codebase of recent changes to it.

Hard disagree. When you ask codex "Why is this slow", it investigates and start writing code. Then we might have to say "Revert this code". But it would be more convenient if we can just go back in that point in time and correct the prompt to "Why is this slow, only investigate, do not write code".

@suparious what you are saying already exists, double press Esc.

When you open codex in a repo, you must start from a clean git tree. This is best practices and proper hygene.
Asking Codex "why is this slow" is ignorant to prompt engineering, but if that is how you want to behave, at leas you can see what it did in your git tree, and simply revert the changes yourself.

I noramlly start CLodex by asking it to have "research this repository, and when you are ready, let's have a back and fourth conversation, before we get started." or similar.

I also always engineer in "COMMIT but do not PUSH" in the context too. That way I am always the gatekeeper for changes to go into the repository.

Being ignorant with Codex, and expecting it to un-change the code, is ridiculous expectation to have. The agent harness should have absolutley nothing to do with the state of your codebase.

Being ignorant with Codex, and expecting it to un-change the code, is ridiculous expectation to have. The agent harness should have absolutley nothing to do with the state of your codebase.

I find it confusing that you are accusing someone of being ignorant of codex when you don't seem to be aware that plan mode exists(?).

Also what do you mean by the agent harness having nothing to do with the state of the codebase when its sole purpose is to modify the state of the codebase? I can't really understand your reasoning.

> Being ignorant with Codex, and expecting it to un-change the code, is ridiculous expectation to have. The agent harness should have absolutley nothing to do with the state of your codebase. I find it confusing that you are accusing someone of being ignorant of codex when you don't seem to be aware that plan mode exists(?). Also what do you mean by the agent harness having nothing to do with the state of the codebase when its sole purpose is to modify the state of the codebase? I can't really understand your reasoning.

The agent harness, in this case Codex, exists as an interface to talk to the LLM provider.
The harness has tools, like shell-exec, that can leverage the underlying BASH, which then let's it con commands on your machine, like making and editing files, it can also make commits.

Expecting it to use your system commands and tools, and then be able to undo everything, is asking the harness to do alot more than it was created for. Using /rewind to return you to a previous state of the conversation, is the real feature, and apparently it exists in Codex as double escape.

The user is responsible to manage the state of the codebase. You can instruct Codex to always test before conmitting and to never push - this is my preferred workflow. Other people may just YOLO and get Codex to test, commit and push.

Bloating up the agent harness to help people that don't want to use or understand git, so that they can roll-back all changes to the system, is not something that I would ever want in my agent harness. That would be more like an Agent OS, which would include a agent harness as it's core component.

I bet in 2-3 years from now, all this will be moot, and Codex will have it's own OS.

Didn't mean to offend anyone here. Just trying to put my view out here.

1. rewind conversation to restore conversation to a previous state - needed (Its already implemented. Press ESC twice).
2. fork directly from a transcript - useful (possible by forking first and then rewinding using ESCx2)
3. Managing code - reinventing git which is already really good at it.

I think its a workflow behavior. When working on a project (coding or not) I always initialize git. When implementing features ask LLM to work on a feature branch and commit along the way. What I meant from bloating the harness was that if you were to implement something similar to git it is challenging. On the surface it looks easy but it isn't. Just read git internals if you are interested. The biggest challenge with making something really good is following KISS principles and UNIX philosophies.

Bloating the harness is one of the main reason why harnesses like https://pi.dev/ (https://github.com/badlogic/pi-mono/tree/main) exist.

I am not using codex just to code. I am using it for EVERYTHING, and I think many more people have also figured out that agentic AI tools like codex can make day to day activities such a breeze. Suggesting that I git track every folder in my PC is ridiculous. I don't see why a quick undo thing that THIS ISSUE IS SPECIFICALLY FOR is being hijacked by people who do not want it. Talking about philosophies and principles and bloat over practicality and joy of use is very retarded. Maybe this features gets implemented, maybe it doesn't in this repo, but whichever harness is leading at the end, will have this feature! Signing off.

So, how do I roll back? It's my first time using Codex after Claude Code, and that problem simply doesn't exist there.

So, how do I roll back? It's my first time using Codex after Claude Code, and that problem simply doesn't exist there.

To my knowledge, the simplest ways to revert the changes back is to either track it through git and revert manually, or ask the agent. The easiest way is to just ask the agent to revert changes back based on tracked git state or without it. Agents remember exactly what they change and can revert it back instantly.

The problem with asking the agents is that you have to rely on them to have perfect memory and context, and to not make mistakes. So it is not safe, nor controlled. A /rewind feature would solve that problem.

Definitely need this in the Codex App GUI. I just made some styling changes that I needed to rollback. I used a prompt to roll them back, since there doesn't seem to be an option to restore a previous state.

This feature should have high priority. So far I've been telling Codex to ignore previous prompt in chat thread when I realized I need to make a correction by pressing Esc.

Thanks for keeping this issue open and for the prior context that the old undo implementation had correctness problems. I took a pass through the current app-server/core rollback path and wanted to sketch a design that preserves the existing conversation-only rollback semantics while adding a safer workspace-restore primitive.

My main takeaway is that this feature would be safer as a new checkpoint/workspace-restore primitive rather than as a behavior change to thread/rollback.

Today thread/rollback is explicitly conversation-only:

• ThreadRollbackParams says it only modifies thread history and does not revert local file changes.
• core Op::ThreadRollback has the same contract.
• the implementation reconstructs persisted rollout history and appends a ThreadRolledBack marker; it does not touch the workspace.

That existing contract is useful and should probably stay intact. The missing piece seems to be a separate "restore workspace to the state associated with this turn/checkpoint" flow that clients can compose with conversation rollback.

Proposed shape

I’d suggest adding a two-phase app-server/core API, for example:

• thread/checkpoint/preview
• thread/checkpoint/restore

or:

• thread/restore/preview
• thread/restore/apply

The target should probably be a targetTurnId / checkpoint id rather than only numTurns, since the UI affordance users expect is "restore to this message/checkpoint".

A preview response should classify each affected file before anything is written:

{
  threadId,
  targetTurnId,
  files: [
    {
      path,
      status: "clean" | "conflict" | "unsupported",
      reason?: string,
      reverseDiff?: string,
      currentHash?: string,
      expectedHash?: string
    }
  ],
  unsupportedMutations: [],
  warnings: []
}

Then restore/apply should re-check the same invariants before writing.

Safety rules

The important constraint is not just "undo Codex changes", but "do not overwrite user changes made after the checkpoint".

A safe apply path could be:

1. collect Codex-authored workspace mutations after the target turn
2. compute the reverse changes in reverse chronological order
3. for each file, verify that the current content still matches Codex's expected after-state
4. apply automatically only when that check passes
5. mark diverged files as conflicts and require explicit user confirmation / manual resolution
6. report unsupported mutations clearly instead of claiming a complete restore

This complements git rather than replacing it: git remains the source of truth for tracked committed work, while this feature covers Codex-authored transient changes, including untracked/gitignored files and prompt iteration workflows where users do not want to commit after every agent turn.

Implementation levels

A minimal V1 could support only apply_patch-backed changes. The repo already persists PatchApplyEnd events and FileChange data, and TurnDiffTracker already tracks per-turn apply_patch diffs. That said, this should be presented as limited because shell/unified_exec/MCP tool calls can mutate files without a durable structured mutation record.

For a complete solution, Codex may need a persisted per-turn workspace mutation record, something like:

type WorkspaceMutation = {
  turnId: string
  toolCallId: string
  source: "apply_patch" | "exec" | "mcp" | "restore"
  path: string
  before: FileSnapshot
  after: FileSnapshot
  exact: boolean
}

type FileSnapshot =
  | { kind: "missing" }
  | { kind: "text", hash: string, blobRef?: string }
  | { kind: "binary", hash: string, blobRef?: string }

For large or binary files, the rollout probably should not inline full contents; a thread-local sidecar blob store keyed by hash would be safer.

Why this matters across surfaces

This feature seems like it belongs below the client UI layer. If the backend exposes preview/apply semantics, CLI/TUI/App/IDE clients can present different UX while sharing the same restore safety model.

Open questions

• Should the first supported version be apply_patch-only, or would that be too easy to misunderstand as a complete checkpoint restore?
• Should restore be allowed to restore workspace only, conversation only, or both, via an explicit mode?
• Should unsupported shell-created mutations be treated as hard blockers by default?
• Where should before/after blobs live so rollout files do not become large or sensitive?
• Would maintainers prefer a design issue/RFC first before any prototype PR?

Per the contribution guidelines, I’m not opening a PR without maintainer direction. If this direction is useful, I’d be happy to help narrow it into a smaller RFC or a focused prototype once the team has a preferred protocol shape and V1 scope.

I think that lack of support to /rewind, for conversation at least, is a big missing feature specially because of emerging patterns leveraging on this feature which are currently possible on claude code

I introduced the /rewind command on my fork (it forks conversation at a given checkpoint, without undoing code changes), but opening PRs are restricted. Here is a preview of the changes I have done: https://github.com/openai/codex/compare/main...fedemagnani:feat/rewind?expand=1

That said, this should be presented as limited because shell/unified_exec/MCP tool calls can mutate files without a durable structured mutation record.

Even easier, any time a command is executed or a MCP tool is called:

# before agent event
git diff --binary > /tmp/before.patch

# agent mutates workspace here

# after agent event
git diff --binary > /tmp/after.patch

# agent-owned repo patch
git diff --no-index --binary /tmp/before.patch /tmp/after.patch > /tmp/agent-event.patch

That last command gives you, with zero commits made, regardless of staging state, the precise edit at that moment. Store that in the rollout log or some database for that thread.

Now when you rewind in a loop:

if git apply --check -3 -R /tmp/agent-event.patch; then
  git apply -3 -R /tmp/agent-event.patch
  echo "rollback applied"
else
  echo "rollback refused: conflicts or overlapping user edits"
  exit 1
fi

The solution to /rewind, /undo, and anything that attempts to mutate workspace files needs to use git, full stop. Git already has all the tools to do this. And to avoid rollback refused:, don't make edits inside the agent's worktree, and don't let 2 agents operate in the same worktree at the same time.

This also kinda falls apart if you use subagents. Imagine having a subagent that made some edits, then gets archived. You'd have to essentially never archive agents, and use a tree of agents in storage to reconstruct the patches as a flat list, and intentionally decide if you want to rollback all of the subagent conversations. It's a Herculean engineering effort. I can see why /thread/(checkpoint|restore) only operates on a thread's chat history and not on file changes.

If we use commits, we can actually differentiate user edits from agent edits by storing the index in codex. Keep staging clean, each edit stages itself and commits, store the index in Codex somewhere. That keeps storage very lightweight, rollbacks atomic, choose to include subagent edits even if the subagent is archived, preserve user edits by always excluding them from agent commits and rebasing around them, etc. This to me is the cleanest solution. You can even commit the agent changes using a hidden ref without touching the dirty worktree (user edits worked around with a hidden ref).

If we want to "complement git", we need to actually use git, and decide what we're willing to give up to make /rewind either be reliable or keep the tree clean.

I built a small local helper that may be useful as a stopgap for the workspace-safety part of this request: trace-to-skill@0.1.71 now has a pre-agent checkpoint command.

npx trace-to-skill@0.1.71 checkpoint . --output .trace-to-skill/checkpoints/before-codex

Important scope note: this does not implement Codex /rewind, does not rewind conversation state, and does not auto-restore files. It creates a local bundle before agent work: git status, staged/unstaged binary diffs, restore notes, and copied blobs for dirty/untracked files. Gitignored files are excluded unless --include-ignored is explicitly passed.

The intent is to cover the practical "bookmark my workspace before an agent touches it" need, including untracked files that a normal commit/stash flow can miss. Release/proof: https://github.com/grnbtqdbyx-create/trace-to-skill/releases/tag/v0.1.71

Codex /rewind using Hooks

This hook creates a Git stash checkpoint before each prompt when the working tree is dirty. Sending checkpoint-rewind restores the latest checkpoint without changing the staged index and keeps the replaced work in a temporary safety stash. Starting a new session removes old checkpoint and safety stashes.

Almost zero token use: checkpoint-rewind runs locally and blocks the prompt before model execution, while successful Git output is suppressed.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "while stash=$(git stash list --format='%gd %s' | grep -Em1 '\\[CODEX:(CHECKPOINT|REWIND-SAFETY)\\]' | cut -d' ' -f1) && [ -n \"$stash\" ]; do git stash drop \"$stash\" >/dev/null; done"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "if grep -Eq '\"prompt\"[[:space:]]*:[[:space:]]*\"checkpoint-rewind\"'; then checkpoint=$(git stash list --format='%gd %s' | grep -m1 '\\[CODEX:CHECKPOINT\\]' | cut -d' ' -f1); if [ -n \"$checkpoint\" ]; then index_tree=$(git write-tree) || exit 1; if [ -n \"$(git status --porcelain)\" ]; then git stash push -u -m '[CODEX:REWIND-SAFETY]' >/dev/null; checkpoint=$(git stash list --format='%gd %s' | grep -m1 '\\[CODEX:CHECKPOINT\\]' | cut -d' ' -f1); fi; git stash pop \"$checkpoint\" >/dev/null && git read-tree \"$index_tree\"; fi; printf '%s\\n' '{\"decision\":\"block\",\"reason\":\"Checkpoint rewind handled by Git hook.\"}'; elif [ -n \"$(git status --porcelain)\" ]; then git stash push -u -m '[CODEX:CHECKPOINT]' >/dev/null && git stash apply --index stash@{0} >/dev/null; fi"
          }
        ]
      }
    ]
  }
}

Please prioritize this request; the rewind command is crucial. Since switching from Claude Code to Codex, I have to commit to Git after every single turn in the conversation, which is a huge hassle.

+1. This is essential for long-running agent sessions.

Codex needs a Claude Code-style rewind with explicit options:

• restore conversation only;
• restore code only;
• restore both conversation and code.

A discoverable /rewind command would also be much clearer than relying only on the hidden Esc Esc shortcut.