# Agent Rollback > Git-like undo and rollback checkpoints for OpenAI Codex CLI. Snapshot, diff, and restore files before and after Codex edits. MCP server + Codex hooks for an automatic safety net. - **Type:** MCP server - **Install:** `agentstack add mcp-nainish-rai-agent-rollback` - **Verified:** Pending review - **Seller:** [Nainish-Rai](https://agentstack.voostack.com/s/nainish-rai) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Nainish-Rai](https://github.com/Nainish-Rai) - **Source:** https://github.com/Nainish-Rai/agent-rollback ## Install ```sh agentstack add mcp-nainish-rai-agent-rollback ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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) ```bash 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: ```bash 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 ```bash 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: ```bash 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: ```bash 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. ```bash # 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](https://github.com/openai/codex/issues/2788) ("History-linked checkpoints and file state restore"), [openai/codex#5082](https://github.com/openai/codex/issues/5082) ("Clicking 'Undo' on file changes should absolutely not be staging changes into git"), and [openai/codex#6449](https://github.com/openai/codex/issues/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?"](https://www.reddit.com/r/codex/comments/1o8tuiq/is_there_a_revertundo/). `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. ```bash 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: ```bash # 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) ```bash 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 ```bash 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: ```bash 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): ```bash npx skills add Nainish-Rai/agent-rollback --skill agent-rollback -g -y ``` Manage afterwards: ```bash 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](https://skills.sh) once at least one user installs it. **Manual install** (after `npm install -g agent-rollback`): ```bash # 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). ```text 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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-nainish-rai-agent-rollback - Seller: https://agentstack.voostack.com/s/nainish-rai - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.