Fixing Roo Code Checkpoints That Fail Silently and Won't Let You Restore a Previous State

The Problem

Roo Code's checkpoint feature is meant to snapshot the workspace automatically around each step the agent takes, so a user can restore to a point before a particular change if the agent went in the wrong direction. On some projects this works exactly as expected. On others, the checkpoint list in the task view stays empty even after several tool calls that clearly changed files, or clicking "Restore" appears to do nothing — the files on disk look unchanged. Occasionally the opposite happens: a restore reverts more than intended, including a manual edit the user made directly in the editor between two of the agent's steps.

Why It Happens

Checkpoints are tracked by a separate, internal shadow git repository — not the project's own .git

Roo Code doesn't create checkpoint commits inside the project's actual git history. It maintains its own hidden shadow repository, stored outside the workspace in the extension's own data, that it commits to independently every time it takes a snapshot. This design choice exists specifically so checkpoints don't pollute or interfere with the project's real commit history — but it also means checkpoint behavior depends on this separate repository being initialized and functioning correctly, which is a detail entirely invisible from looking at the project's own .git folder.

A git executable that's missing, misconfigured, or too old breaks the shadow repository silently

Because the shadow repository is itself a real git repository under the hood, creating and committing to it depends on a working git command being reachable from the environment VS Code is running in. If git isn't installed, isn't on the PATH that extension host process sees (which isn't always the same PATH as an interactive shell), or is an old version missing a feature the checkpoint logic relies on, checkpoint creation can fail quietly in the background without a clearly surfaced error dialog interrupting the task.

A workspace that is itself already a large or unusual git repository can make shadow-repo operations slow or inconsistent

A workspace with a very large .git history, large binary assets tracked directly instead of through something like Git LFS, or nested repositories (a vendored dependency or submodule with its own .git directory inside the workspace) can make the shadow repository's own snapshot operations slow enough to time out, or confused about which directory boundary it's actually supposed to be tracking — producing checkpoints that silently cover less of the workspace than intended.

A restore only reverts files the shadow repository actually tracked, which can diverge from what the user assumes was being watched

If a large generated directory, a dependency folder, or any other path was effectively invisible to the shadow repository — because it was ignored, because it exceeded a size threshold, or because it simply wasn't touched by the specific tool calls between two checkpoints — restoring to an earlier checkpoint won't touch that path either, which can look like "restore did nothing" for the specific file the user was watching, even while it correctly reverted everything else.

The Fix

1. Confirm git itself is reachable from the same environment the extension host runs in, not just from a terminal

# Run from VS Code's own integrated terminal, not a separate system terminal,
# since the extension host's PATH can differ from an external shell's:
git --version
which git

Checking git's availability specifically from inside VS Code's own terminal, rather than a separate terminal application, rules out the common case where git is installed and working everywhere else but isn't actually visible to the process VS Code (and therefore the Roo Code extension) is running in.

2. Check the Roo Code output/logs channel for checkpoint-related errors rather than assuming silence means success

VS Code Command Palette -> "Output: Show Output Channels" -> select the Roo Code channel

A checkpoint operation that fails due to a git error, a permissions issue, or a timeout typically does log something to the extension's own output channel even when nothing visibly interrupts the chat view, so checking it directly turns "checkpoints just don't seem to work" into a specific, actionable error message.

3. For a workspace with an unusually large or complex git history, test checkpoints in a minimal reproduction first

# Clone a small, clean subset of the project (or start a fresh minimal repo)
# and confirm checkpoints work there before assuming the feature itself is broken
mkdir /tmp/checkpoint-test && cd /tmp/checkpoint-test && git init

Reproducing the behavior against a small, simple repository isolates whether the problem is the checkpoint feature itself or something specific to the current workspace's size, history, or nested-repository structure — and if checkpoints work fine in the minimal case, the fix is addressing whatever makes the real project's repository unusual (large tracked binaries, nested .git folders, an oversized history) rather than the extension.

4. Treat a restore's actual scope as "what the shadow repo tracked," and verify independently for anything outside normal source files

# After a restore, diff the actual working tree against the project's own git
# to see concretely what changed versus what the user expected to change
git status
git diff

Running the project's own git status and git diff immediately after a checkpoint restore shows exactly what the operation actually touched, which replaces an assumption about what "should have" been restored with a concrete list — and makes it immediately clear whether a specific path was simply never part of what the shadow repository was snapshotting in the first place.

Why This Works

Each step targets a different link in the same chain: checkpoints depend on a separate, hidden git repository working correctly, which in turn depends on a reachable git executable, reasonable performance on the workspace's actual file structure, and a scope that matches what the user assumes is being tracked. Verifying git's reachability from inside VS Code itself and checking the extension's own logs turn a silent failure into a diagnosable one. Reproducing against a minimal repository separates a workspace-specific git problem from an extension bug. And diffing the actual result of a restore against assumptions replaces "it didn't do what I expected" with a concrete, verifiable answer about what the shadow repository was actually watching.

Conclusion

A Roo Code checkpoint that seems to fail silently, or a restore that seems to do too little or too much, is almost never a flaw in the restore mechanism itself — it's a reflection of whether the separate shadow git repository backing checkpoints was able to initialize and snapshot the workspace correctly in the first place. Confirm git is reachable from VS Code's own process, check the extension's output channel for the specific error silence was hiding, isolate the problem with a minimal repository if the workspace itself is large or unusual, and verify a restore's actual effect with the project's own git tooling rather than assuming the shadow repository was tracking everything the user expected it to.