Turnback

rm -rf の後でも、AI コーディングエージェントの操作を元に戻せます。

Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Antigravity CLI に対応した、ひとつの元に戻す履歴です。

_{Turnback の実際の実行例です。エージェントは Claude Code のフックペイロードでシミュレートしています。rm -rf と Turnback の各行は実際のものです。python scripts/demo/make_demo.py で再現できます。}

理由

エージェントのチェックポイントが追跡するのは、エージェント独自の編集ツールによる変更です。Claude Code のドキュメントには、次のように明記されています："Checkpointing does not track files modified by Bash commands." そのため、エージェントが rm -rf、mv、コードジェネレーター、または git checkout -- . を実行すると、巻き戻してもファイルを復元できません。

Turnback は、すべてのシェルコマンドと編集の前に、ワークスペースのスナップショットを ~/.turnback 内のシャドー Git リポジトリに保存します。

• ターン全体を元に戻すことも、ターン内の特定のステップの直前に戻ることもできます。
• 最大 5 MB の追跡対象ファイル、未追跡ファイル、Git の無視対象ファイル（.env など）が対象です。
• turnback export --commit を実行しない限り、プロジェクトの .git には何も書き込まれません。また、フックがエージェントをブロックすることもありません。
• 6 つのエージェントでひとつの履歴を共有できます。MCP 経由で、エージェントは自分のターンを一覧表示して差分を確認し、2 段階で復元できます。まず計画を立て、その後に変更を適用します。

インストール

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、または単体の 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

Claude Code、Codex、OpenCode、Antigravity CLI で実機テスト済みです。Gemini CLI と Cursor は、ドキュメントに記載されたフックペイロードに基づくテストでカバーしています。エージェントごとの詳細はインストールを参照してください。

Claude Code の /rewind との比較

	/rewind	Turnback
エージェントの編集ツールによる変更	✅	✅
シェルコマンド（rm、mv、コード生成）によるファイル変更	❌	✅
未追跡ファイルと Git の無視対象ファイル	編集ツールが変更したファイルのみ	✅ 最大 5 MB
その他のエージェント	❌	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

エージェントを使わない場合

turnback run は任意のコマンドをターンとして記録するため、コードジェネレーター、codemod、フックのないエージェントにも同じように元に戻す機能を適用できます。blame で各行を書き込んだターンを確認し、recover で単一のファイルを復元できます。

log、search、report、compare、export を含むすべてのコマンド：コマンド。詳細：復元、MCP、対象範囲と制限。

動作の仕組み

変更を加えるツールの実行前に呼び出されるフックが、ターンのベースラインを取得します。シェルコマンドの実行前に呼び出されるフックはツリー全体を取得し、その後の編集では影響を受けるパスを取得します。ターンの終了時に結果を取得します。初期スナップショットは、インストール時とセッション開始時にバックグラウンドで準備されます。記録に失敗しても、フックは常にエージェントの続行を許可します。failed、skipped、または unprotected の状態は status で確認できます。

追跡対象のファイル、未追跡ファイル、Git の無視対象ファイルのうち、サイズが 5 MB 以下のものが対象です。ビルド出力と依存関係ディレクトリは除外されます。追加のルールは .turnbackignore で gitignore 構文を使って指定できます。グローバルルールは ~/.turnback/config.json に {"exclude":["pattern"]} として記述します。

ファイル数が 100k を超える、またはサイズが 2 GB を超えるワークスペースは edits-only モードに切り替わります。このモードでは、編集ツールが変更したパスのみがスナップショットに記録され、シェルコマンドは unprotected として記録され、復元時には記録されたパスのみが対象になります。7 日より前のターンと、直近 50 ターンの範囲外にあるターンは、使用中のワークスペースだけでなく、すべてのワークスペースで、1 日に最大 1 回、自動的にクリーンアップされます。削除されたワークスペースのデータは、30 日間アイドル状態が続いた後に削除されます。保持するには、~/.turnback/config.json に {"autoClean": false} を設定してください。

貢献

good first issue のラベルが付いた課題は規模が小さく、変更対象のファイルが記載されています。また、より多くのエージェントへの対応も歓迎します。CONTRIBUTING.mdとアーキテクチャの概要から始めてください。質問やアイデアはディスカッションにお寄せください。

貢献者

マージされたすべてのプルリクエストは、リリースノートに記載されます。

開発

モジュール	内容
src/cli/	main.ts：CLI とフックのエントリーポイント（dist/cli.js としてビルド）；args.ts：引数の解析
src/core/	recorder.ts：イベントごとのスナップショットルール；store.ts：ジャーナル、スナップショット、ターン、ステップ、マーク、ステータス、gc；restore.ts：復元の計画と実行、元に戻す、やり直す；format.ts：テキスト出力；quote.ts：シェルで安全な引数；journal.ts、lock.ts、config.ts、types.ts
src/git/	shadow.ts：シャドウ Git リポジトリのラッパー
src/workspace/	workspace.ts：ワークスペースのスキャンと除外ルール
src/agents/	adapters.ts：各エージェントのフックペイロードから HookEvent への変換；install.ts：エージェントごとのフックと 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 を実行し、turnback の代わりに node dist/cli.js を使ってください。

リリース

package.json と server.json の 2 つのバージョンフィールドに同じバージョンを設定してコミットし、v<version> タグをプッシュします。Publish ワークフローはバージョンが一致していることを確認し、テストを実行して、信頼されたパブリッシングを通じて npm に公開します（プロベナンスは自動的に付与されます）。また、server.json を MCP レジストリに 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 を使って手動で 1 回公開します。その後にタグをプッシュすると、バージョンがすでに存在するため npm への公開はスキップされ、MCP レジストリへの公開のみが行われます。それ以降のタグでは、両方が実行されます。

ライセンス

MIT