File Snapshot Module

Shadow git repository for file change tracking and one-click undo

Track file changes in a hidden git repo so agents can snapshot, diff, and restore workspace files without touching your real repository.

from praisonaiagents import Agent, AutonomyConfig

agent = Agent(
    name="coder",
    instructions="Snapshot files before autonomous edits",
    autonomy=AutonomyConfig(track_changes=True, snapshot=True),
)

agent.start("Refactor the module")

The user approves autonomous edits; shadow-git snapshots let the agent diff, undo, or redo workspace changes safely.

Quick Start

1. Simple Usage

   Turn on change tracking and the pre-run snapshot so undo() has something to restore:

   from praisonaiagents import Agent, AutonomyConfig
   
   agent = Agent(
       name="Refactorer",
       instructions="Edit files carefully.",
       autonomy=AutonomyConfig(level="full_auto", track_changes=True, snapshot=True),
   )
   
   agent.start("Rename getUserName to getUserEmail in src/user.js")
   agent.diff()   # see what changed
   agent.undo()   # restore pre-run state

2. With Configuration

   Use AutonomyConfig for explicit control, or call FileSnapshot directly:

   from praisonaiagents import Agent
   from praisonaiagents import AutonomyConfig
   from praisonaiagents.snapshot import FileSnapshot
   
   agent = Agent(
       name="Editor",
       autonomy=AutonomyConfig(level="full_auto", track_changes=True, snapshot=True),
   )
   
   # Or standalone — no agent required
   snapshot = FileSnapshot(project_path=".")
   info = snapshot.track(message="Before refactor")
   # ... edit files ...
   snapshot.restore(info.commit_hash)

3. Re-root After a Workspace

   Agent.__init__ roots change tracking at os.getcwd(). Attach a per-session directory later, then call set_snapshot_root() so undo() restores the right place:

   from praisonaiagents import Agent, AutonomyConfig
   
   agent = Agent(
       name="Editor",
       instructions="Edit files carefully.",
       autonomy=AutonomyConfig(track_changes=True, snapshot=True),
   )
   
   # Later — once you know the workspace the tools will actually write to
   agent.set_snapshot_root("/tmp/session-42/workspace")
   
   agent.start("Rename getUserName in src/user.js")
   agent.undo()  # restores /tmp/session-42/workspace, not process cwd

snapshot vs track_changes

The two fields are independent — undo() needs both.

Re-rooting Change Tracking

set_snapshot_root(project_path) re-roots undo/redo/diff at a directory known only after construction — the moment a bot, gateway, or custom wrapper attaches a per-chat Workspace.

Returns bool — True when a snapshot manager is rooted at the given path, False if construction failed (e.g. git unavailable).

Bot / Gateway Workspaces

Bots and gateways call Agent.set_snapshot_root(workspace.root) from apply_bot_smart_defaults() immediately after attaching the per-chat Workspace. So /undo in a Slack, Discord, or Telegram chat reverts files in that chat’s workspace — never the gateway’s process cwd.

Custom wrappers that attach a workspace after Agent.__init__ should do the same:

from praisonaiagents import Agent, AutonomyConfig

agent = Agent(name="assistant", autonomy=AutonomyConfig(track_changes=True, snapshot=True))
# ... attach your workspace ...
agent.set_snapshot_root(str(workspace.root))

See Bot Gateway for how the gateway wires this automatically.

How It Works

Git Subprocess Guard

Every git call made by FileSnapshot and the GitWorktreeAdapter is time-limited and non-interactive, so a stuck git can never block an agent turn.

Added in PraisonAI PR #6172. The Gateway Subprocess Guard uses the same pattern.

Restore Guarantees

restore() (and agent.undo()) rebuilds the project to exactly the target snapshot’s tree:

Common Patterns

Selective restore

from praisonaiagents.snapshot import FileSnapshot

snapshot = FileSnapshot(project_path="/my/project")
initial = snapshot.track(message="Checkpoint")

# ... changes across many files ...

snapshot.restore(initial.commit_hash, files=["src/config.py", "src/utils.py"])

List recent snapshots

for info in snapshot.list_snapshots(limit=10):
    print(f"{info.commit_hash[:8]} — {info.message} ({info.files_changed} files)")

Best Practices

Related