Agent Rollback

agent-rollback: codex undo, revert, and rollback checkpoints

> Last updated: 2026-06-11 · Version: 1.0.1 · Node: >= 20 · License: MIT

agent-rollback is the undo button for OpenAI Codex CLI. It captures content-addressed snapshots of your workspace before, during, and after any Codex run, so you can restore any file — or the entire project — in one command. It works with or without a Git repo, exposes an MCP server and a Codex hook for automatic checkpoints, and is the only tool purpose-built for codex undo, codex rollback, and codex checkpoint outside of git stash workarounds.

A Node.js CLI (agent-rollback / short alias arb), an MCP server for Codex / Claude Code / Cursor, and a Codex hook. MIT-licensed, 100% local — no telemetry, no cloud sync.

Search aliases users use to find this tool: Codex undo, Codex revert, Codex checkpoint, Codex rollback, Codex snapshot, Codex backup, Codex diff, Codex restore, Codex file history, Codex safety net, Codex MCP, Codex time travel, AI code undo, agent snapshot.

[](https://www.npmjs.com/package/agent-rollback) [](https://nodejs.org) [](./LICENSE) [](https://www.npmjs.com/package/agent-rollback) [](https://github.com/Nainish-Rai/agent-rollback/stargazers) [](https://developers.openai.com/codex/cli) [](https://modelcontextprotocol.io)

> Structured data (schema.org JSON-LD for AI engines, Knowledge Graph, and npm codex undo SERP eligibility) lives at [/schema.json](./schema.json) in the repo root. It's a real file, parsed and shipped in the npm tarball, and read by crawlers that look for it.

Contents

• [30-second start](#30-second-start)
• [Step 0 — Install (one line)](#step-0--install-one-line)
• [Step 1 — Initialize a repo](#step-1--initialize-a-repo)
• [Step 2 — Ask the agent what it can do](#step-2--ask-the-agent-what-it-can-do)
• [Step 3 — Create a checkpoint, then do something risky](#step-3--create-a-checkpoint-then-do-something-risky)
• [Step 4 — Browse checkpoints](#step-4--browse-checkpoints)
• [Step 5 — Made a mess? Roll back](#step-5--made-a-mess-roll-back)
• [Step 6 — See what changed](#step-6--see-what-changed)
• [Why](#why)
• [Install](#install)
• [AI agent skill](#ai-agent-skill)
• [Usage](#usage)
• [Manual checkpoints](#manual-checkpoints)
• [Run Codex with rollback](#run-codex-with-rollback)
• [Codex hooks (auto-checkpoints)](#codex-hooks-auto-checkpoints)
• [List, show, diff](#list-show-diff)
• [Restore, pin, prune, undo](#restore-pin-prune-undo)
• [Terminal browser (TUI)](#terminal-browser-tui)
• [Operation log](#operation-log)
• [Replay from a checkpoint](#replay-from-a-checkpoint)
• [MCP server](#mcp-server)
• [Storage model](#storage-model)
• [Chat with Codex — MCP usage examples](#chat-with-codex--natural-language-examples)
• [Integration references](#integration-references)
• [FAQ — Codex undo, revert, and rollback](#faq--codex-undo-revert-and-rollback)
• [Development](#development)
• [Current boundaries](#current-boundaries)
• [License](#license)

30-second start: codex undo in 30 seconds

The full user flow, in order. From "never heard of it" to "rolled back a bad Codex edit" in about 30 seconds of typing.

agent-rollback is the full command. arb is a 3-char alias for when you're in a hurry. They do exactly the same thing.

Step 0 — Install (one line)

curl -fsSL https://raw.githubusercontent.com/Nainish-Rai/agent-rollback/main/scripts/install.sh | bash -s -- --all

This installs the agent-rollback (and arb) binary globally, registers the MCP server in ~/.codex/config.toml, and installs the agent skill for 18+ agents. Verify it worked:

agent-rollback --help   # see all subcommands
arb --help              # short alias, same output

If you'd rather use npm only (no MCP, no skill), drop the --all flag — or run npm install -g agent-rollback instead.

Step 1 — Initialize a repo

mkdir demo && cd demo && git init
agent-rollback init         # or: arb init

This creates .agent-rollback/ in the project. All your snapshots will live here. (You can ignore it in your .gitignore; it's yours, not your repo's.)

Step 2 — Ask the agent what it can do

Open Codex in this repo and just say:

> You: "what can you do for checkpoints?"

Codex reads the installed SKILL.md and lists the full surface — create, list, show, diff, revert, undo, pin, prune, replay, tui — with one-line examples. No memorization needed.

Step 3 — Create a checkpoint, then do something risky

> You: "make a checkpoint called 'green tests' and refactor the auth module"

> Codex: "Created cp-183544-green-tests-ed96. Refactoring auth module now. If I make a mess, just say 'go back'."

Step 4 — Browse checkpoints

> You: "show me checkpoints"

> Codex: > `` > • cp-183544-green-tests-ed96 12 sec ago green tests > • cp-cold-start-deadbeef 1 min ago cold start > 2 checkpoints, ~0.4 MB on disk. > ``

Or from the CLI:

agent-rollback list              # or: arb list
agent-rollback list --json       # machine-readable
agent-rollback tui               # interactive terminal browser

Step 5 — Made a mess? Roll back

> You: "go to the last checkpoint"

> Codex: "Reverted to cp-183544-green-tests-ed96. 4 files restored, safety checkpoint cp-...-safety-... created automatically."

Or from the CLI:

agent-rollback revert cp-183544-green-tests-ed96 --yes   # or: arb revert ...
agent-rollback undo 1 --yes                              # undo the last N

Step 6 — See what changed

> You: "what did the refactor change vs the green tests checkpoint?"

> Codex: > `` > 3 files changed in src/auth/: > src/auth/login.js (+42, -18) > src/auth/token.js (+12, -4) > src/auth/index.js (+3, -0) > Want me to revert just those, or roll back the whole checkpoint? > ``

That's the whole loop. Everything below is optional depth.

How to undo a Codex change in 4 commands

The fastest path. Use this section as a cheatsheet when Codex has already done the damage.

# 1. install (or: npm install -g agent-rollback)
curl -fsSL https://raw.githubusercontent.com/Nainish-Rai/agent-rollback/main/scripts/install.sh | bash -s -- --all

# 2. initialize the store inside your repo
agent-rollback init         # or: arb init

# 3. (optional) take a checkpoint, then let Codex run
agent-rollback checkpoint "green tests"
agent-rollback run codex "refactor the auth module"

# 4. made a mess? roll back
agent-rollback list
agent-rollback revert cp- --yes   # or: agent-rollback undo 1 --yes

For the natural-language version (works in a Codex chat), just say:

> "go to last checkpoint", "show me checkpoints", "what did the > refactor change?" — the MCP server handles the rest.

agent-rollback vs the alternatives

How agent-rollback compares to other options a developer might reach for when Codex has edited too much:

| Tool | License | Codex-native | MCP server | Hooks | Per-op undo | Local-only | | ----------------------------- | -------- | ------------ | ---------- | ----- | ----------- | ---------- | | agent-rollback (this) | MIT | Yes | Yes (9 tools) | Yes (auto + manual) | Yes (op revert) | Yes | | pi-rollback (npm) | n/a | Adapter | No | No | No | Yes | | agentame (npm) | n/a | Adapter | No | No | Yes (API-call layer) | Yes | | A386official/diffback (GH) | MIT | Adapter | No | No | No | Yes | | codex-revert (mcpmarket) | n/a | Claude-only | Skill | No | No | Yes | | Built-in codex /rewind (proposed) | n/a | Yes | No | n/a | n/a | Yes | | git stash | GPLv2 | Manual | No | No | No | Yes | | Editor Cmd+Z | n/a | n/a | No | No | No | Yes |

When to use what:

• agent-rollback — the moment a Codex session drifts out of scope,

or for any pre-commit AI work. MCP-native, hook-native, per-op undo.

• git stash / git restore — only when you've already made a

commit or have uncommitted work you want to set aside. Doesn't help with the "Codex edited 7 files in 2 minutes" case.

• Editor Cmd+Z — fine inside a single file, useless across a

multi-file Codex run, and lost when you close the editor.

• pi-rollback / diffback — similar idea, fewer primitives

(no MCP server, no Codex hook, no op log, no TUI).

• agentame — different layer: API-call rollback, approval gates.

Not for file edits.

Why this exists: codex safety net for AI-edited code

OpenAI Codex CLI does not ship a built-in undo. The feature has been requested since 2024 — see openai/codex#2788 ("History-linked checkpoints and file state restore"), openai/codex#5082 ("Clicking 'Undo' on file changes should absolutely not be staging changes into git"), and openai/codex#6449 ("Code and context rollback") for the canonical threads — and git stash workarounds are widely cited as fragile (no auto-trigger, no operation-level undo, no MCP surface). See also the community pain thread r/codex: "Is there a revert/undo?".

agent-rollback is the agent snapshot layer: a CLI, an MCP server, a Codex hook, and a SKILL.md that give any AI agent the ability to checkpoint, list, diff, revert, pin, prune, undo, and replay its own workspace.

Codex (and any agent that edits files) will eventually make a change you didn't want. agent-rollback gives you:

• Before/after snapshots of the working tree, content-addressed and

deduped, so they cost ~zero disk.

• Selective restore: pin a known-good checkpoint, prune noise, and

jump back in one command.

• Operation log: every revert records which files it touched, so you

can revert a single bad operation without losing later unrelated edits.

• Agent-native surface: an MCP server, a Codex hook, and a SKILL.md

so any agent (Codex, Claude Code, Cursor, etc.) can use it without you being in the loop.

• Three ways to use it: a CLI (agent-rollback / arb), an MCP server

any agent can call, or a Codex hook that auto-snapshots on every prompt and tool use.

Install

Pick one of three paths.

1. One-click script (recommended)

Detects your platform, checks Node >= 20, installs globally, and verifies the binary. Idempotent and safe to re-run.

curl -fsSL https://raw.githubusercontent.com/Nainish-Rai/agent-rollback/main/scripts/install.sh | bash

Options (append after bash -s --):

| Flag | Effect | | ---------------- | ----------------------------------------------------------------------- | | --all | Install binary + agent skill + register MCP server in Codex (--with-skill --with-mcp). | | --with-skill | Also install the agent skill globally via npx skills add. | | --with-mcp | Also register the MCP server in ~/.codex/config.toml (auto-merged, idempotent, with backup). | | --version 0.1.2| Pin a specific version instead of latest. | | --uninstall | Remove the global install and the MCP block from Codex config. | | --dry-run | Print what would happen; make no changes. | | --no-color | Disable ANSI colors. |

What --with-mcp does:

• Adds this block to ~/.codex/config.toml (respects $CODEX_HOME if set):

``toml [mcp_servers.agent-rollback] command = "agent-rollback" args = ["mcp"] ``

• Backs up any existing config to config.toml.bak. first.
• Skips silently if the block is already present (safe to re-run).
• --uninstall removes the same block as part of cleanup.

Examples:

# install + skill + MCP in one shot
curl -fsSL https://raw.githubusercontent.com/Nainish-Rai/agent-rollback/main/scripts/install.sh | bash -s -- --all

# just the binary + skill
curl -fsSL https://raw.githubusercontent.com/Nainish-Rai/agent-rollback/main/scripts/install.sh | bash -s -- --with-skill

# just the binary + MCP server registration
curl -fsSL https://raw.githubusercontent.com/Nainish-Rai/agent-rollback/main/scripts/install.sh | bash -s -- --with-mcp

# preview only
curl -fsSL https://raw.githubusercontent.com/Nainish-Rai/agent-rollback/main/scripts/install.sh | bash -s -- --dry-run

# remove later (also strips the MCP block)
curl -fsSL https://raw.githubusercontent.com/Nainish-Rai/agent-rollback/main/scripts/install.sh | bash -s -- --uninstall

2. npm (published package)

npm install -g agent-rollback

Requires Node.js >= 20. Adds two commands to your PATH:

• agent-rollback — the full name, what you'll see in docs and code
• arb — a 3-char short alias, perfect for muscle memory and tight loops

Both are identical; pick whichever you type faster.

> Why arb and not ar? > > ar is the BSD/GNU archive tool that ships with every Unix-like > system at /usr/bin/ar. On any shell where /usr/bin is searched > before npm's global bin (cloud shells, cron, some terminal emulators, > shells launched without nvm initialized), the system ar shadows our > binary and ar --help shows the archive tool's usage instead of ours. > arb (agent-rollback) is a 3-char name that doesn't collide with > anything. The installer detects the shadow and prints a note.

3. From source

git clone https://github.com/Nainish-Rai/agent-rollback.git
cd agent-rollback
npm install
npm link        # exposes `agent-rollback` / `arb` globally

Or run it directly without linking:

node ./bin/agent-rollback.js --help

AI agent skill

A SKILL.md ships in the package at skills/agent-rollback/SKILL.md. It teaches AI agents (Codex CLI, Claude Code, Cursor, Gemini CLI, Windsurf, Copilot, Cline, ...) how to use both the MCP server and the ar CLI.

One-line install (works for 18+ agents):

npx skills add Nainish-Rai/agent-rollback --skill agent-rollback -g -y

Manage afterwards:

npx skills list                 # what's installed
npx skills find "rollback"      # discover more
npx skills update               # pull latest
npx skills remove agent-rollback

After install the skill appears in the agent's slash menu and triggers automatically on rollback / undo / revert / restore / "what changed" / "I broke something" phrases — no need to name the tool.

The skill is also discoverable on skills.sh once at least one user installs it.

Manual install (after npm install -g agent-rollback):

# Codex CLI
mkdir -p ~/.codex/skills
ln -s "$(npm root -g)/agent-rollback/skills/agent-rollback" ~/.codex/skills/

# Claude Code
mkdir -p ~/.claude/skills
ln -s "$(npm root -g)/agent-rollback/skills/agent-rollback" ~/.claude/skills/

# Cursor (project-only)
mkdir -p .cursor/skills
ln -s "$(npm root -g)/agent-rollback/skills/agent-rollback" .cursor/skills/

Usage — codex checkpoint, revert, and undo commands

All commands accept --cwd , --store , --json (for agents/CI), --no-input, and --yes (skip confirmations).

agent-rollback init
agent-rollback init codex
agent-rollback checkpoint [label]
agent-rollback list
agent-rollback show 
agent-rollback diff  [to-id]
agent-rollback pin  [label]
agent-rollback unpin 
agent-rollback prune [--older-than ] [--keep-last ] --yes
agent-rollback undo [count] --yes
agent-rollback log
agent-rollbac

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Nainish-Rai](https://github.com/Nainish-Rai)
- **Source:** [Nainish-Rai/agent-rollback](https://github.com/Nainish-Rai/agent-rollback)
- **License:** MIT

Install and usage instructions live in the source repository linked above.