Turnback

为 AI 编码 Agent 提供撤销功能，即使执行了 rm -rf 也能恢复。

为 Claude Code、Codex、Cursor、Gemini CLI、OpenCode 和 Antigravity CLI 提供统一的撤销历史记录。

_{这是一次真实的 Turnback 运行。Agent 使用 Claude Code 的钩子负载进行模拟；rm -rf 和 Turnback 的每一行输出都是真实的。运行 python scripts/demo/make_demo.py 即可重现。}

为什么使用

Agent 检查点会记录 Agent 自己的编辑工具所做的修改。Claude Code 的文档对此有明确说明："检查点不会跟踪通过 Bash 命令修改的文件。" 因此，当 Agent 执行 rm -rf、mv、代码生成器或 git checkout -- . 时，回退无法恢复这些文件。

Turnback 会在每次执行 shell 命令和编辑之前，将工作区快照保存到 ~/.turnback 下的影子 git 仓库中：

• 撤销整个轮次，或回到其中某个步骤之前。
• 跟踪文件、未跟踪文件以及被 git 忽略的文件（例如 .env）均可恢复，文件大小上限为 5 MB。
• 除非运行 turnback export --commit，否则不会向项目的 .git 写入任何内容；钩子也绝不会阻止 Agent。
• 六种 Agent 共用一份历史记录。通过 MCP，Agent 可以列出自己的轮次、查看差异，并分两步恢复：先制定计划，再进行更改。

安装

在 Claude Code 中：

claude plugin marketplace add MFaizR77/turnback
claude plugin install turnback@turnback

然后使用 /turnback:turns、/turnback:diff-turn、/turnback:undo 和 /turnback:report。

在 Codex 中（下一次 npm 发布时提供）：

codex plugin marketplace add MFaizR77/turnback
codex plugin add turnback@turnback

启动新会话，在 /hooks 中检查并信任 Turnback 的钩子，然后使用 $turnback:turns、$turnback:diff-turn、$turnback:undo 和 $turnback:report。

插件需要 Turnback 0.9.1 或更高版本。要从检出目录试用尚未发布的插件更改，请参阅本地测试。

对于 Codex、Cursor、Gemini CLI、OpenCode、Antigravity CLI，或单独使用命令行（需要 Node.js 22+ 和 Git 2.25+）：

npm install -g turnback
turnback install all            # user-level hooks and MCP for every agent
turnback install codex --project  # or one agent, in this project only

Turnback 已在 Claude Code、Codex、OpenCode 和 Antigravity CLI 中进行实时测试；Gemini CLI 和 Cursor 则通过基于其文档所述钩子负载构建的测试进行验证。各 Agent 的详细信息请参阅：安装。

与 Claude Code 的 /rewind 对比

	/rewind	Turnback
Agent 编辑工具所做的修改	✅	✅
shell 命令更改的文件（rm、mv、代码生成）	❌	✅
未跟踪文件和被 git 忽略的文件	仅编辑工具更改的文件	✅，最大 5 MB
其他 Agent	❌	Codex、Cursor、Gemini CLI、OpenCode、Antigravity CLI
回到某个轮次内的指定位置	❌	✅ --before-step
回退对话	✅	❌，仅限文件

两者可以配合使用：用 /rewind 回退对话，用 Turnback 恢复文件。

日常使用

turnback --help                     # commands, options, and quick-start examples
turnback list                       # recent turns with their prompts
turnback diff <turn>                # what a turn changed
turnback undo --dry-run             # show the plan
turnback undo --yes                 # undo the latest turn
turnback redo --yes                 # changed your mind
turnback steps <turn>               # each edit and shell command in a turn
turnback restore <turn> --before-step 3 --yes
turnback mark "before migration"    # a checkpoint of your own
turnback run -- npm run codegen     # any command as an undoable turn, no agent needed
turnback recover src/app.ts         # bring back one file (or a folder) an agent deleted turns ago
turnback blame src/auth.ts          # which turn and prompt wrote each line
turnback report --pr --apply        # add which prompts wrote this branch to its pull request
turnback du                         # Turnback's disk use for every workspace
turnback ui                         # timeline in the browser

不使用 Agent

turnback run 会将任意命令记录为一个轮次，因此代码生成器、codemod 或没有钩子的 Agent 也能获得同样的撤销能力。blame 会显示每一行由哪个轮次写入，recover 则可以恢复单个文件：

包括 log、search、report、compare 和 export 在内的所有命令：命令。更多信息：恢复、MCP、范围与限制。

工作原理

修改类工具运行前的钩子会记录本轮的基线。Shell 命令运行前的钩子会捕获整个目录树；之后的编辑则会捕获受影响的路径。本轮结束时会记录结果。安装时和会话开始时，会在后台预热初始快照。记录失败时，钩子始终会允许 Agent 继续；failed、skipped 或 unprotected 状态可通过 status 查看。

会跟踪大小不超过 5 MB 的已跟踪、未跟踪和被 Git 忽略的文件。构建输出和依赖目录会被排除。额外规则在 .turnbackignore 中使用 gitignore 语法；全局规则写入 ~/.turnback/config.json，格式为 {"exclude":["pattern"]}。

文件数超过 100k 或大小超过 2 GB 的工作区会切换到 edits-only 模式：只为编辑工具触及的路径创建快照，Shell 命令会记录为 unprotected，还原时也只会操作已记录的路径。超过 7 天且不在最近 50 轮范围内的轮次会自动清理；清理频率最高为每天一次，适用于所有工作区，而不仅是当前使用的工作区。工作区被删除后，其数据会在闲置 30 天后删除；如需保留，请在 ~/.turnback/config.json 中设置 {"autoClean": false}。

参与贡献

标记为 good first issue 的问题规模较小，并会说明涉及哪些文件；也欢迎支持更多 Agent。请从 CONTRIBUTING.md 和架构概览开始。问题和想法请发到 Discussions。

贡献者

每个合并的拉取请求都会在发行说明中致谢。

开发

模块	内容
src/cli/	main.ts：CLI 和钩子入口（构建为 dist/cli.js）；args.ts：参数解析
src/core/	recorder.ts：各事件的快照规则；store.ts：日志、快照、轮次、步骤、标记、状态、gc；restore.ts：还原计划与执行、撤销、重做；format.ts：文本输出；quote.ts：Shell 安全参数；journal.ts、lock.ts、config.ts、types.ts
src/git/	shadow.ts：影子 Git 仓库封装
src/workspace/	workspace.ts：工作区扫描与排除规则
src/agents/	adapters.ts：各 Agent 的钩子负载 → HookEvent；install.ts：为各 Agent 安装钩子和 MCP；opencode-plugin.ts：生成的 OpenCode 插件
src/mcp/	server.ts：stdio MCP 服务
src/ui/	server.ts：供 turnback ui 使用的只读本地服务；page.ts：其单页界面

npm run check
npm run bench

基准测试会创建一个包含 10k 个文件的临时仓库，并报告延迟，但不会将其设为严格的 CI 门槛。CI 会在 Windows、macOS 和 Linux × Node 22/24 上运行测试和基准测试。

从克隆的仓库开始，运行 npm ci && npm run build，并使用 node dist/cli.js 代替 turnback。

发布

在 package.json 和 server.json 的两个版本字段中设置相同版本，提交，然后推送 v<version> 标签。Publish 工作流会检查版本是否一致、运行测试、通过可信发布发布到 npm（自动附加来源证明），并将 server.json 发布到 MCP registry，名称为 io.github.MFaizR77/turnback。

还要更新 src/core/config.ts、两个插件清单，以及 .claude-plugin/marketplace.json 和 .agents/plugins/marketplace.json 中的 npm 版本范围。

npm 可信发布在 npmjs.com 的软件包页面上配置（仓库为 MFaizR77/turnback，工作流为 publish.yml），因此需要先创建软件包。所以首个版本需手动运行一次 npm publish --access public 发布；之后再推送其标签时，会跳过 npm（该版本已存在），只发布到 MCP registry。后续标签会同时执行两项发布。

许可证

MIT