codex-rewind

English · 简体中文

Documentation - Installation, rewind walkthrough, and command reference.

An unofficial distribution of OpenAI Codex CLI.

For what Codex CLI is, how to sign in, and how to use it, read the official README. Everything there applies here. This page only covers what this distribution adds.

Not affiliated with, endorsed by, or supported by OpenAI. Apache-2.0, same as upstream. Report problems here, not to OpenAI — and include the npm version, which is the only one that names the release. See Reporting a bug.

---

What this adds: rewind

Upstream Codex can take you back to an earlier point in a conversation. It cannot take your files back with it — so the model ends up reasoning from a conversation that predates the code sitting on disk.

This distribution adds the missing half. /rewind restores the workspace to how it looked at the prompt you pick, and /redo puts it back if you change your mind.

Follow the step-by-step guide below, with still screenshots you can read at your own pace.

▶ Earlier walkthrough and design discussion (22 min) — a deletion-recovery demo, why git is the wrong foundation, what the three buckets are, and where it stops.

/rewind     pick a prompt; the conversation and the files both return to it
/redo       undo that
/status     shows whether snapshots are on, and what they cost on disk

No git required, and it never touches your git state — no commits, no stashes, no index writes, nothing inside .git. It works in directories that are not repositories at all.

Install

npm install -g codex-rewind

The command is codexr, not codex, so this installs alongside the official build rather than replacing it.

codexr          # this distribution
codex           # the official one, if you have it

Ships prebuilt binaries for macOS, Linux and Windows on both x64 and arm64, the same targets as upstream. Node 16 or newer.

Removing it again is two commands, and leaves your conversations untouched — see Clean uninstall.

Releases are versioned <upstream>-rewind.<n> — 0.156.1-rewind.0 is built from upstream rust-v0.156.1, so the baseline each release carries is visible in its version number. Being semver prereleases, they are also skipped by version ranges: a ^0.156.1 dependency will never resolve to one by accident.

The baseline half is what codexr --version reports. The -rewind.<n> half lives only in the npm package. See Reporting a bug.

Enable it

Rewind is off by default. To try it on a single run, without changing any file:

codexr --enable file_snapshots

To keep it on, turn it on in /experimental, or:

# ~/.codex/config.toml
[features]
file_snapshots = true

It binds per session: enabling affects new sessions only, and disabling never stops a session that is already tracking. So a session either has snapshots for its whole life or has none — there is no half-tracked state to reason about.

Try your first rewind