Checkpoints

Checkpoints are Nexgile Code’s free undo. As the agent works, every file change it makes is captured in a shadow git repository — a separate repository kept in Nx IDE’s own storage, one per task, completely independent of your project’s git. Your git log, staging area, and branches are never touched. If a task goes sideways, you restore any earlier state with one click and keep working from there.

Checkpoints are what make it reasonable to let the agent edit with auto-approve on: writes become cheap to grant because they are cheap to take back.

What gets captured

• Agent-initiated file changes in your workspace — every create, edit, and delete the agent performs is snapshotted into the shadow repository, and a Checkpoint row appears in the chat at that point in the conversation.
• The snapshot covers your working tree state, so restoring returns files exactly as they were — including files you had edited manually before that point in the task.

What is not captured:

• Terminal side-effects. A command the agent ran — npm install, a database migration, a file created by echo or a script, a deleted directory — is not part of any checkpoint. Restoring rewinds the agent’s file edits only. Undo command effects manually.
• Anything outside the workspace. The shadow repository tracks the open folder.

Caution

“Restore” is not “revert everything that happened.” If the agent ran commands, check the terminal history and undo those effects yourself. This is the single most important limitation to internalize.

Restoring a checkpoint

Each Checkpoint row in the chat has a restore control (the history icon) with two options:

Option	What it does
Restore Files	Puts your project files back to the snapshot taken at this point. The conversation is untouched — useful for a quick “what did the code look like then?” or to discard later edits while keeping the discussion.
Restore Files & Task	Puts files back and deletes all conversation messages after this point. You continue the task from that state, as if the later steps never happened. Requires a confirmation click — this action cannot be undone.

Restore Files & Task is the “rewind and take a different path” move: restore, then re-prompt with better instructions. The agent’s context now matches the restored files, so it won’t be confused by changes that no longer exist.

Diffing checkpoints

Checkpoints double as a step-by-step audit trail:

• View Diff (on a Checkpoint row) — the changes made in that step, compared with the previous checkpoint.
• View All Changes — everything changed since the task began.
• View Changes Since This Checkpoint — what has changed between that point and your current files.

Diffs open in Nx IDE’s standard diff viewer. “What exactly did the agent change in step 4?” is one click, without touching your project git.

Requirements and limits

Checkpoints need a few conditions to work:

• git must be installed and on your PATH. The shadow repository is a real git repository.
• A folder must be open — a single loose file has nothing to snapshot against.
• No nested git repositories. If another .git exists inside your workspace (for example a vendored repo or a submodule checkout), checkpoints are disabled with an explicit error naming the offending path. Remove or relocate the nested repository to re-enable them.
• Not in unscoped personal folders. Checkpoints refuse to run when the workspace is your home, Desktop, Documents, or Downloads folder — open a real project folder instead.

If initialization is slow, the chat shows a “Still initializing checkpoint…” notice; you can raise the timeout or disable checkpoints in settings.

Settings

Open Settings → Checkpoints:

Setting	Key	Default	Range
Enable automatic checkpoints	enableCheckpoints	On	—
Checkpoint initialization timeout (seconds)	checkpointTimeout	15	10–60

Raise the timeout for very large workspaces where the first snapshot takes longer to build; disable checkpoints entirely only if you have a workflow reason (for example, an enormous monorepo where snapshot time is noticeable and you commit constantly anyway).

Checkpoints vs. your project git

The two are complements, not substitutes:

Use checkpoints for	Use project git for
Undoing agent steps mid-task	Milestones you want to keep
Comparing what changed at each agent step	Sharing work with your team
Fast experiments — “let it try; restore if wrong”	Anything that must survive beyond the task
Recovering without dirtying your git history	Code review and CI

A clean working tree before a big task is still worth having: it makes your own git diff review of the final result trivial. But you no longer need defensive WIP commits before every agent run — that ritual is what checkpoints replace.

Tip

For high-stakes work, use both: start from a clean tree, let checkpoints cover the mid-task risk, then review the full diff and commit through your normal process — or hand the commit step to a mode built for it. See Using Modes.

A typical recovery, end to end

1. You ask for a refactor; the agent edits six files across four checkpoints.
2. The result compiles, but step 3’s change took an approach you don’t want. Click View Diff on checkpoint 3 to confirm that’s where it went wrong.
3. Open the restore control on checkpoint 2 and choose Restore Files & Task, then confirm. Files are back to the end of step 2; the conversation now ends there too.
4. Re-prompt with a sharper instruction: “Continue, but keep the existing interface — change only the implementation.”
5. The agent proceeds from the restored state. Total cost of the wrong turn: two clicks and one sentence.

Related

• Auto-Approving Actions
• Human-in-the-Loop Playbook
• How the Agent Works
• Troubleshooting