File Snapshot Module

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(file_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

Simple Usage

Enable change tracking on an autonomous agent — full_auto turns on snapshots automatically:

from praisonaiagents import Agent

agent = Agent(
    name="Refactorer",
    instructions="Edit files carefully.",
    autonomy="full_auto",
)

agent.start("Rename getUserName to getUserEmail in src/user.js")
agent.diff()   # see what changed
agent.undo()   # restore pre-run state

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),
)

# Or standalone — no agent required
snapshot = FileSnapshot(project_path=".")
info = snapshot.track(message="Before refactor")
# ... edit files ...
snapshot.restore(info.commit_hash)

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),
)

# 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

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.

Behaviour	Detail
Path resolution	`project_path` is normalised via `os.path.abspath()` — relative paths resolve against process cwd
No-op on same root	Called with the current root → returns `True` immediately and keeps the existing manager
Re-root clears stacks	Called with a new root → creates a fresh `FileSnapshot` and clears the undo/redo stacks
Preserves `snapshot_dir`	Reuses `autonomy_config["snapshot_dir"]` if set, so a custom shadow-repo base survives re-rooting
Silent fallback	If `FileSnapshot(...)` fails (git missing, permission error), returns `False` and logs at DEBUG — never raises
Thread-safe	Uses the agent’s snapshot lock when clearing the stacks

Parameter	Type	Description
`project_path`	`str`	Directory to root change tracking at. Absolute-normalised; relative paths resolve against cwd.

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

Re-rooting clears the undo/redo stacks — they belong to the previous root. The old shadow repo is orphaned (still on disk under ~/.praisonai/snapshots/), and only future changes are tracked at the new root.

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))
# ... attach your workspace ...
agent.set_snapshot_root(str(workspace.root))

See Bot Gateway for how the gateway wires this automatically.

How It Works

Component	Role
Shadow git	Hidden repo under `~/.praisonai/snapshots/` (honours `PRAISONAI_HOME`) — never affects your project git
`track()`	Commits current file state; returns `SnapshotInfo` with hash
`diff()`	Compares two snapshots or snapshot vs working tree
`restore()`	Checks out files from a snapshot; optional file list for partial restore
Agent helpers	`agent.undo()`, `agent.redo()`, `agent.diff()` when `track_changes=True`

Git must be available on PATH. If shadow-repo init fails, tracking is skipped silently and undo() returns False.

Restore Guarantees

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

Case	Behaviour
File exists in snapshot, missing in project	Restored from shadow git
File exists in project, not in snapshot	Removed — no leak from a later snapshot
File was deleted before the snapshot	Stays deleted — deletion is recorded, not resurrected
File is ignored (`.env`, `venv`, `node_modules`, `.gitignore` matches)	Preserved untouched — the snapshot never tracked it, so restore never prunes it
`files=[...]` selective restore	Only the listed files are touched; project prune step is skipped

The ignored-file guarantee is what makes agent.undo() safe to call in projects that keep secrets in .env. Both _sync_files() and restore() build their exclusion set from _build_ignore_patterns(), so a file the snapshot never tracked can never be pruned by a restore.

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

Prefer agent undo for autonomous runs

When using autonomy="full_auto", call agent.undo() rather than manual restore() — the agent maintains an undo/redo stack across iterations.

Snapshot before risky edits

Call track(message=...) (or run the agent once) before bulk refactors so you have a named rollback point.

Respects .gitignore

The shadow repo honours .gitignore patterns plus built-in defaults (.git, __pycache__, node_modules, venv, .venv, .pytest_cache, .mypy_cache). Ignored files are neither snapshotted nor pruned by restore(). A .env file that lives outside version control survives every undo() / restore().

Clean up when finished

Call snapshot.cleanup() to remove the shadow repository if you no longer need history for a project.

Re-root after attaching a workspace

Agent.__init__ roots the snapshot at os.getcwd(). If you attach a Workspace (or any per-session root) later, call agent.set_snapshot_root(str(workspace.root)) immediately — otherwise agent.undo() restores files in the wrong directory. Re-rooting clears the undo/redo stacks; rooting at the current directory is a no-op.

File Editing

Safe find-and-replace tools agents use before snapshots capture the result

Autonomy Loop

Configure track_changes and autonomous file-editing levels

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

File Snapshot Module

Quick Start

Re-rooting Change Tracking

Bot / Gateway Workspaces

How It Works

Restore Guarantees

Common Patterns

Selective restore

List recent snapshots

Best Practices

File Editing

Autonomy Loop

​Quick Start

​Re-rooting Change Tracking

​Bot / Gateway Workspaces

​How It Works

​Restore Guarantees

​Common Patterns

​Selective restore

​List recent snapshots

​Best Practices

​Related

File Editing

Autonomy Loop

Quick Start

Re-rooting Change Tracking

Bot / Gateway Workspaces

How It Works

Restore Guarantees

Common Patterns

Selective restore

List recent snapshots

Best Practices

Related