Shadow Workspace

also known as Agent-Edit VCS, Shadow Git Checkpoints

Mirror the workspace into an isolated, version-controlled shadow where the agent makes and reverts edits, surfacing diffs for review and promoting only accepted changes to the real tree.

Context

An autonomous coding agent edits files in a developer's working tree. It needs to experiment — try an edit, run tests, back out, try another — and it gets things wrong. Editing the real tree in place means a bad run can corrupt uncommitted work, and there is no clean per-edit history to review or revert.

Problem

An agent that writes straight to the working tree gives the human no safe boundary: a wrong edit overwrites real work, a multi-step change is hard to review as a whole, and undoing one step without losing the others is fiddly. The agent needs room to make and unmake edits freely, while the human keeps a reviewable, revertible record and the real tree stays clean until changes are accepted.

Forces

An agent must experiment and recover from bad edits, but direct writes to the real tree risk corrupting the developer's uncommitted work.
Per-edit rollback and whole-change review need a version history, yet maintaining a parallel copy costs disk and bookkeeping.
The shadow must track the real tree closely enough that promoting accepted changes is clean, not a merge nightmare.

Example

A coding agent refactors a module across eight files. It works in a hidden checkpoint repo that snapshots each edit, so when step six breaks the build the developer rolls back just that step instead of the whole run. Once the diff looks right the agent promotes the change to the real working tree; had it looked wrong, discarding the shadow would have left the original files exactly as they were.

Diagram

flowchart TD real[Real working tree] -->|mirror| shadow[Version-controlled shadow] shadow --> edit[Agent edits + checkpoints] edit --> diff[Diffs for review] diff --> ok{Accept?} ok -->|yes| promote[Promote to real tree] ok -->|no| discard[Discard shadow]

Solution

Therefore:

Mirror the working tree into a shadow the agent edits instead of the real files — commonly a per-task hidden git repository that checkpoints every edit, or an in-memory overlay that tracks modifications without writing to disk. Each agent edit becomes a diff the human can inspect, and any step can be rolled back to a prior checkpoint without disturbing the others. When the change is accepted it is promoted to the real working tree; if rejected, the shadow is discarded and the real tree is untouched.

What this pattern forbids. The agent does not write directly to the real working tree; all edits land in the shadow first and may only be promoted after review, so a rejected or broken edit never reaches the developer's files.

And the patterns that stand alongside it, or against it —

alternative-toCompensating Action★★— Pair every irreversible-looking agent action with a compensating action that can undo or counteract it.
alternative-toDurable Workflow Snapshot★— Capture workflow execution state as a snapshot in a pluggable storage provider so a paused run can resume across deployments, process restarts, and host crashes.
complementsSynthetic Filesystem Overlay·— Project heterogeneous enterprise data sources into a single Unix-like tree exposed through filesystem primitives so the agent reuses path semantics it already knows instead of learning a bespoke API per source.
complementsSubagent Isolation★— Run subagents in isolated workspaces so their writes do not collide and parallelism is safe.