claudeers.
// Developer Tools

oops

Agent 的 Ctrl+Z:一键精准撤销/重做。Ctrl+Z for Agent: precise undo & redo in one step. Works inside Claude Code, Codex, Gemini CLI and Cursor CLI.

// Developer Tools[ cli ][ api ][ claude ]#claude#ai-tools#claude-code#cli#codex#coding-agent#cursor#developer-tools#devtools◷ MIT$open-sourceupdated about 1 month ago
Actively maintained
99/100
last commit about 1 month ago
last release about 1 month ago
releases 2
open issues 0
// star history

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up oops (release-binary project) into my current project.
Found on https://claudeers.com/oops
Repo: https://github.com/lintsinghua/oops
Homepage/docs: —
Detected install method: release-binary → inspect the README
Category: devtools. Platforms: cli, api.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
active; community-verified: false. Confirm the source before running anything.
// or install directly (release-binary)

Grab the latest release asset from GitHub.

# download a build from https://github.com/lintsinghua/oops/releases
// or clone
git clone https://github.com/lintsinghua/oops

// compatibility

Platformscli, api
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageGo

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

oops

Agent 的 Ctrl+Z:一键精准撤销/重做
Claude Code、Codex、Gemini、Cursor 对文件做的任何改动都能撤销,rm -rf 也不例外。

English · 简体中文

Agent 改乱了你的项目?一句 /oops,一键回到对话前。

  • 整轮撤回:Agent 一轮改了 30 个文件?一条命令,全部还原。
  • 你的改动不丢:自动区分 Agent 与你的修改,只撤回 Agent 的部分。
  • 随时反悔:撤回、重做都支持,完整时间线前后自由切换。
  • 不碰 .git:独立快照,Git 历史一行不改。
  • 在 Agent 里直接用:通过 hook 接入 Claude Code、Codex、Gemini CLI、Cursor CLI,无需切换工具,在对话中输入 /oops 即可撤回。

两个场景:在 Claude Code 里用 /oops 撤销,以及在完整时间线里撤销和重做。

curl -fsSL https://raw.githubusercontent.com/lintsinghua/oops/main/install.sh | sh
oops init                         # 一次接好本机所有 Agent,之后就不用管了

为什么需要 oops

编程 Agent 已经可以自己执行 shell 命令了。有时候那条命令是 rm -rf、git clean -fdx,或者对四十个文件跑一遍 sed -i,而被改的文件从来没提交过。

Agent 自带的保护网在这些场景下并不够用:

  • Codex 原本有 /undo,2026 年 4 月被移除(#8804、PR #19481)。要求恢复它的 openai/codex#9203“Please make /undo back”至今仍是 open 状态,有 480 个赞、93 条评论。原帖的场景是:Codex 误删了没进 git 的文件,误改了还没提交的内容。相关的 /rewind 需求(#11626)也有 227 个赞。
  • Claude Code 的检查点不追踪通过 Bash 做的修改(rm、mv、cp),不恢复后台 subagent 的编辑,每个会话只保留最近 100 个检查点。auto mode 下 Agent 经常用 Bash 改文件,于是 /rewind 可能报告成功、实际什么都没恢复(anthropics/claude-code#87575)。
  • Gemini CLI 的检查点默认关闭,只在 write_file / replace 之前快照;/restore 会对整个影子仓库执行 git restore 加 git clean,连你自己的改动也一起冲掉。

issue 数据截至 2026-10-14。

oops 工作在更底层的文件系统。不管 Agent 用的是自带的 Edit 工具、sed、Python heredoc 还是 rm -rf,也不管文件有没有进 git,这一轮都能撤回。

一键安装

不论哪种方式,装完都运行 oops init。

脚本

优先用这个。它从 GitHub Releases 下载本机对应的压缩包(macOS、Linux、Windows · amd64 / arm64),用 checksums.txt 核对 SHA-256,再把二进制装到 ~/.local/bin。校验失败时以非零状态退出,不会覆盖已经装好的文件。不需要 sudo。

macOS 和 Linux:

curl -fsSL https://raw.githubusercontent.com/lintsinghua/oops/main/install.sh | sh
oops init

Windows(PowerShell):

irm https://raw.githubusercontent.com/lintsinghua/oops/main/install.ps1 | iex
oops init

OOPS_VERSION 指定版本(0.1.0 或 v0.1.0,默认最新 release)。OOPS_INSTALL_DIR 改安装目录。目录不在 PATH 里时,脚本会打印一行可以加进去的命令。再跑一次就是升级,并打印 upgraded from X to Y。

卸载:

oops init --undo
oops gc --all --global
rm -f "${OOPS_INSTALL_DIR:-$HOME/.local/bin}/oops"

Windows(PowerShell):

oops init --undo
oops gc --all --global
Remove-Item -Force "$env:USERPROFILE\.local\bin\oops.exe"

Homebrew

brew install lintsinghua/tap/oops
oops init

卸载:

oops init --undo
oops gc --all --global
brew uninstall oops

npm

npm 上的包名 oops 已被占用,所以这里发布的是 @lintsinghua/oops。

npm i -g @lintsinghua/oops
oops init

npx 同样可用:

npx @lintsinghua/oops init

主包通过 optionalDependencies 带上每个平台一个包(例如 @lintsinghua/oops-linux-x64),包里直接放二进制,并写好 os 和 cpu。npm 只会装上匹配的那一个。postinstall 不会再下载文件。

卸载:

oops init --undo
oops gc --all --global
npm uninstall -g @lintsinghua/oops

Go

go install github.com/lintsinghua/oops/cmd/oops@latest
oops init

卸载:

oops init --undo
oops gc --all --global
rm -f "$(go env GOPATH)/bin/oops"

30 秒上手

$ oops init

  oops keeps a snapshot before every agent turn, so you can undo it.

  Found 3 agents
    ● Claude Code   ~/.claude/settings.json
    ● Codex         ~/.codex/hooks.json
    ● Gemini CLI    ~/.gemini/settings.json
    ○ Cursor CLI    not found

  Connect all 3? [Y/n/e] ⏎

  ✓ Claude Code   connected · /oops ready
  ✓ Codex         connected · open Codex and run /hooks once to trust oops
  ✓ Gemini CLI    connected

  You're protected.
  When an agent breaks something, just type: oops

就这样。之后照常工作,oops 运行时不会输出任何东西。

出事的时候,只需要敲一个词:

$ oops

时间线随即打开,默认选中最近一轮,右侧预览撤销后会发生什么。按 Enter,确认,完成。

$ oops undo
✓ Undid turn #42 · claude · "clean up the build scripts"

  restored  39 files   src/ (38), .env
  removed    1 file    scripts/build.mjs
  reverted   1 file    package.json

  Changed your mind? oops redo

在 Claude Code 里也可以直接输入 /oops。它在本地执行,不会发给模型,不消耗 token。Claude Code 会把这段回复显示成 hook 拦截(“operation blocked by hook”)。以 ✓ oops 开头的那一行是结果,不是报错。

不想用了?oops init --undo 只移除 oops 自己写入的配置,其他设置一行不动。

命令

你只需要记住 oops。其余命令是给熟练用户和脚本用的快捷方式。

命令作用
oops打开时间线:选中一轮 → 预览 → 撤销
oops undo [turn]撤销最近一轮或指定的一轮;--file <path> 只撤销部分文件
oops rewind <turn>回到某一轮开始之前(撤销该轮及之后的所有轮)
oops redo撤回最近一次 undo、rewind 或 restore
oops restore <path>… --at <turn>取回某一轮开始之前的文件版本
oops list最近的轮:Agent、时间、prompt 摘要、改动文件数
oops show [turn]查看某一轮改了什么
oops diff [turn]查看某一轮的 diff(--stat、--name-only、--reverse)
oops init接入本机的 Agent(--project、--print、--undo)
oops run -- <cmd>保护任何没有 hooks 的工具
oops snap [-m msg]立即保存一个检查点
oops doctor检查一切是否正常
oops gc回收快照占用的空间

undo、rewind、redo、restore、snap、gc 支持 -n/--dry-run。list、show、diff、undo -n、doctor、snap、gc 支持 --json(带 schema_version)。show --json 包含文件列表。退出码:0 成功 · 1 错误 · 2 需要确认 · 3 部分完成(冲突文件被保留)· 4 没有可操作的目标 · 130 被中断。字段见 docs/schema.md。

支持的 Agent

Agent接入方式一轮的边界会话内说明
Claude Code~/.claude/settings.json 中的 hooks提交 prompt → Stop/oops本地执行,不耗 token。Claude 显示为 “operation blocked by hook”;✓ oops 那一行是结果
Codex~/.codex/hooks.json提交 prompt → Stop / 中断prompt hook 里带有这段文字时的 /oops需在 /hooks 中信任一次。非交互运行用 codex exec --dangerously-bypass-hook-trust。不会安装 !oops
Gemini CLI~/.gemini/settings.jsonBeforeAgent → AfterAgentBeforeAgent 带上 prompt 时的 /oops与 Gemini 自带检查点可共存。没有单独的 slash hook
Cursor CLI~/.cursor/hooks.json提交 prompt → stop!oops-p 模式建议用 oops run -- cursor-agent
其他任意工具oops run -- <cmd>整个会话,静默 3 秒自动切分—Aider、opencode、自研 harness
脚本oops snap手动检查点—

oops init --project 会写入项目级配置(如 .claude/settings.json),团队成员拉下仓库即可共享。

v0.2 计划支持:GitHub Copilot CLI、opencode、Qwen Code、Amp、Goose。申请支持新的 Agent →

工作原理

 Agent 一轮开始 ──► oops hook 要等快照 "pre" 落盘才返回
        … Agent 编辑文件、跑 sed、rm -rf、git clean …
 Agent 一轮结束 ──► oops hook 要等快照 "post" 落盘才返回

 oops undo ──► 对这一轮改过的每个文件:
                 还是 Agent 留下的样子?      → 还原成 "pre" 版本
                 之后被你(或别人)改过?    → 保留,并告诉你原因
  • 按轮快照。Agent 的 hooks 标出一轮的开始和结束,oops 在这两个时刻给工作区拍快照;两者之差就是这一轮做的全部改动,不管是哪个工具改的。
  • 增量、内容寻址。借助 stat 缓存,只读取和哈希有变化的文件。内容去重、zstd 压缩、不可变——数据模型借鉴 git(blob、tree),但不使用 git 存储。
  • 你的改动是安全的。撤销时对每个文件比较三个状态:轮前、轮后、现在。这一轮之后被你(或别的 Agent)改过的文件会被保留并列出,不会被覆盖。文件只在内容与基线不同时保留:基线是 post 快照,或者最近一次 undo / redo 写下的字节。mtime 落在 Stop 和 post 快照完成之间并不足以保留,因为 NTFS 上刚写完的文件时间戳可能仍落在这段窗口里,而内容并没有变。--force 可以强制覆盖,被覆盖的版本会先保存下来。
  • 撤销也能撤销。每次 undo、rewind、restore 之前都先拍一张安全快照,oops redo 一定能回到原样。
  • 不打扰。hook 进程永远 exit 0,没有常驻进程。轮次开始的 hook 会等 pre 快照落盘才返回,后面的修改不会被当成撤销要恢复的原件。轮次结束的 hook 先把这一轮标成已结束,等 post 快照落盘后才返回。脱离的进程只做保留清理,不再负责 Agent 正在等的那张快照。oops undo 会等一张 Stop 已经排队、但扫描中途被打断的快照最多 5 秒,而不会把这一轮当成仍在运行。下一轮会等这张 post 快照(最多 30 秒,超时后由等待的进程自己写完),轮次边界不会错。如果上一轮还开着,pre hook 会先按当时的目录树把它收完,再存新的 pre 快照。之后才跑完的扫描不会覆盖这张 post。轮次结束的进程如果在扫描中途退出,任务文件还在,下一条命令会把这一轮写完。hook 只在回答 /oops 时写 stdout;Claude Code 上,快照不完整或有文件大到没存下内容时,还会输出一条 systemMessage。其他 Agent 在下一次执行 oops 时看到同一条提示。同一个原因只提示一次。硬超时默认 10 秒,从这次扫描开始计时,超时只把快照标成 partial,hook 照常返回。
  • 不碰你的仓库。快照数据不会写进工作区。不写 .git,不建分支,不 stash。例外是 oops init --project:它会写入 Agent 自己的项目配置,例如 .claude/settings.json。快照在 ~/.local/share/oops(Windows 为 %LOCALAPPDATA%\oops)。OOPS_HOME 可以改数据目录。
  • 收录范围。没被 gitignore 的文件(含未跟踪文件),再加上即使被 gitignore 也受保护的文件(.env、.env.*、.envrc、*.local、*.local.*、.dev.vars、local.settings.json)。被 gitignore 的路径即使曾经 git add -f 也会跳过。node_modules/、.venv/、target/ 等重目录自动跳过。dist/ 和 build/ 只在同时命中 gitignore 规则时跳过。可用 .oopsignore(gitignore 语法)调整。超过 50 MB 的文件只记录元数据不存内容。oops doctor、oops show 和下一条命令会说明它们未受保护。

详见 docs/how-it-works.md

与 Agent 自带检查点的对比

oops 不取代 Agent 自带的检查点,而是补上它们覆盖不到的地方。推荐组合使用:对话用 Agent 的 /rewind,文件用 oops undo。

Claude Code /rewindCodexGemini CLI /restoreoops
有内置撤销✓已移除(2026-04)需手动开启✓
通过 shell 做的修改(rm、mv、sed)✗—只在 write_file / replace 前快照✓
后台 subagent 的编辑✗——本轮结束前已写到磁盘的文件
未跟踪和被 gitignore 的文件(.env)———✓
保留你在这一轮之后的改动——✗(整库 restore + clean)✓
跨 Agent 的统一时间线✗✗✗✓
独立于 Agent 会话✗(按会话)——✓
历史保留每会话 100 个,约 30 天——500 轮或 30 天
回滚对话✓—✓✗(不在目标内)

✓ 支持 · ✗ 不支持 · — 不适用或文档未说明。来源:Claude Code 检查点文档、openai/codex PR #19481、Gemini CLI 检查点。Claude Code 的 SubagentStop 会被记录,且不会把这一轮拆开。文件要在父轮的 post 快照时已经在磁盘上,才会被覆盖到。

FAQ

会拖慢 Agent 吗?

oops 的设计目标就是不拖慢。Codex 上一版 /undo 被移除,原因之一就是快照给用户带来了问题,所以这是 oops 的第一条规矩:快照是增量的(只重读 size、mtime 或 mode 变化的文件),被排除的目录直接剪掉不遍历,每次快照有硬超时(默认 10 秒)——超时后快照标记为 partial,hook 返回。轮次结束的 hook 要等 post 快照落盘才返回。轮次开始的 hook 要等 pre 快照落盘才返回。

2026-10-14 用 OOPS_PERF=1 go test -count=1 -timeout 45m -run TestHookVisibleLatency ./internal/engine/ 测得(internal/engine/perf_test.go)。夹具是分布在 200 个目录里的 N 个互不相同的 32 字节文件。p50 是 21 个样本里排序后的第 11 个,p95 是第 20 个(nearest-rank)。机器:4 vCPU(KVM 上的 Intel Xeon,每核 1 线程),16 GB 内存,256 GB virtio 磁盘(/dev/vdc 上的 ext4;客户机把这块盘报告成机械盘),Linux 6.12.94+ x86_64。

这一轮 harness 测到 turn-end 在 1 万文件是 112 ms / 127 ms、10 万文件是 1.00 s / 1.11 s,turn-start 是 99 ms / 153 ms 和 0.89 s / 0.99 s。同一种目录上的设计测量更高:Stop 在 1 万文件约 180 ms,Stop 在 10 万文件约 1.4 s,Start 在 10 万文件约 1.2 s。QA 测到 1 万文件的 Start 是 p50 174 ms / p95 240 ms,高于这一轮。下面每个格子取更高的数。高于这一轮 p95 时,公布的 p50 和 p95 都用这个数。

Agent 等待轮次结束 hook 返回的时间。 post 快照在这个进程里完成。TestHookVisibleLatency 编译 ./cmd/oops,先走一轮冷启动,等已排队的快照落盘,再计时 21 次 oops hook claude turn-end 从进程启动到退出。进程在快照落盘之后才退出。

文件数Agent 等待 turn-end hook 返回,p50Agent 等待 turn-end hook 返回,p95
10,000180 ms180 ms
100,0001.4 s1.4 s

Agent 等待轮次开始 hook 返回的时间。 pre 快照在这个进程里完成,hook 要等快照落盘才返回。方法和上面的 turn-end 表相同,计时的是上一张 post 快照已经结束后的 oops hook claude turn-start,所以这段等待是 pre 快照加上进程启动。

文件数Agent 等待 turn-start hook 返回,p50Agent 等待 turn-start hook 返回,p95
10,000174 ms240 ms
100,0001.2 s1.2 s

公布的 1 万文件 post 快照 p50 是 180 ms。默认 10 秒超时会把快照标成 partial,hook 仍然返回。如果上一张 post 快照在扫描中途被杀掉,turn-start hook 会先等剩下的任务,上限 30 秒(TestWaitPendingBounded)。任务已经完成时,这段额外等待不到 50 ms。进程死掉不会丢掉这一轮:任务文件会留到后面的命令把 post 快照写完(TestCrashedChildFinishesTurn)。2026-10-13 的进程内热 Capture(不含进程启动)是 1 万文件 82 ms / 91 ms、10 万文件 0.82 s / 3.5 s(TestHotCapturePercentiles)。上面两张表是更晚一次测量,记的是 Agent 实际等待的时间。

冷启动和扫描时的内存。 TestColdStart10k 计时的是对 10,000 个文件、合计 300,000,000 字节做的第一次进程内 Capture。这台机器上是 0.69 s(PRD 在 Linux 上的上限是 3 s)。TestScanRSS100k 在扫描 100,000 个文件时采样 VmRSS,峰值 119.5 MiB,即 125,341,696 字节(PRD 上限是 150 MB)。测于 2026-10-13。这两个数各是一次采样,不是百分位。

存了什么?存在哪里?

工作区的文件内容(去重并压缩),以及一个小型 SQLite 数据库,记录每一轮的元数据:Agent、时间、改动的文件、prompt 的首行(最多存 200 字符,常见密钥会被脱敏;设置 privacy.record_prompts = false 可完全关闭)。数据在 ~/.local/share/oops(Windows 是 %LOCALAPPDATA%\oops)。Unix 上新建的数据目录是 0700,对象文件是 0600。Windows 上数据目录会设成只给当前用户的 ACL。每张 post 快照之后会自动保留最近 500 轮或 30 天,并在单个工作区超过 2 GB 或全局超过 10 GB 时删掉最旧的轮。oops gc 可以手动做同样的清理。oops gc --all 删除当前工作区的快照。oops gc --all --global 删除所有工作区。一小时内新建、且已无引用的对象会先留着。

快照里有我的 .env,这样安全吗?

这是有意为之——.env 被删是最让人头疼的损失之一。数据永远不离开你的机器,只有你的用户可以读取。如果不想保存某个文件,把它写进 .oopsignore。威胁模型见 SECURITY.md。

和 git 是什么关系?

git 管的是你决定保留的历史,oops 管的是两次提交之间的那几分钟。它覆盖未跟踪和被忽略的文件,不需要提交,也从不碰你的仓库:不写 .git,不建分支,不 stash。在不是 git 仓库的目录里也能用。

能撤销数据库改动、网络请求或安装的包吗?

不能。oops 只恢复工作区内的文件。工作区之外的副作用(数据库、网络请求、全局安装、磁盘其他位置的文件)oops 无法撤销。

会回滚 Agent 的对话吗?

不会,那是 Agent 自己的事(Claude Code 的 /rewind 就做得很好)。对话交给 Agent,文件交给 oops。

Agent 这一轮之后我又改了文件怎么办?

oops 会保留你的版本,并告诉你跳过了哪些文件、为什么(退出码 3)。如果你确实想把 Agent 的改动也撤掉,输出里会给出完整命令(带 --force),你的版本会先被保存。

会联网吗?

这些命令不会主动联网。没有遥测,也没有账号。oops version 只打印编译进去的版本、提交和构建日期。唯一的网络请求是 oops version --check,它读取 GitHub 上的最新 release。

支持 Windows 吗?

CI 在 Linux、macOS、Windows 上跑同一条 go test -race ./...,其中包含共用的端到端场景(删除、修改、重命名、权限、符号链接、Unicode 文件名、空目录、.env、大文件、dry-run JSON)。

怎么卸载?

oops init --undo 移除 hooks(其他设置不受影响),oops gc --all --global 删除所有快照。然后按安装一节里你所用方式的命令删掉二进制。

参与贡献

欢迎提交 bug、Agent 适配器和文档修正。请先阅读 CONTRIBUTING.md:开发环境、make test、Conventional Commits、DCO 签名,以及新增 Agent 适配器的模板。提交 bug 时请附上 oops doctor --json 的输出。

安全问题请通过 GitHub Security Advisories 私下报告,详见 SECURITY.md。

许可证

MIT

致谢

感谢 Linux.Do

// faq

What is oops?

Agent 的 Ctrl+Z:一键精准撤销/重做。Ctrl+Z for Agent: precise undo & redo in one step. Works inside Claude Code, Codex, Gemini CLI and Cursor CLI.. It is open-source on GitHub.

Is oops free to use?

oops is open-source under the MIT license, so it is free to use.

What category does oops belong to?

oops is listed under devtools in the Claudeers registry of Claude-compatible tools.

34 views
★ 15 stars
unclaimed
updated about 1 month ago

// embed badge

oops on Claudeers
[![Claudeers](https://claudeers.com/api/badge/oops.svg)](https://claudeers.com/oops)

// retro hit counter

oops hit counter
[![Hits](https://claudeers.com/api/counter/oops.svg)](https://claudeers.com/oops)

// reviews

// guestbook

0/500

// related in Developer Tools

🔓

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…

// devtoolsaffaan-m/⟨JavaScript⟩★ 307,864◷ MIT[ claude ]
🔓

Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.

// devtoolsDietrichGebert/⟨JavaScript⟩★ 187,728◷ MIT[ claude ]
🔓

AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…

// devtoolssafishamsi/⟨Python⟩★ 147,800◷ MIT[ claude ]
🔓

Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA

// devtoolsgarrytan/⟨TypeScript⟩★ 140,465◷ MIT[ claude ]
→ see how oops connects across the ecosystem