Praison AI

Checkpoints

Shadow git checkpointing for file-level undo/restore

The checkpoint command manages file-level checkpoints using shadow git — save, list, diff, restore, and rewind workspace snapshots.

Quick Start

bash
# Save a checkpoint
praisonai checkpoint save "Before refactoring"

# One-liner undo after a bad run
praisonai run --restore last

Usage

Save Checkpoint

bash
praisonai checkpoint save "Checkpoint message"
praisonai checkpoint save "Checkpoint message" --allow-empty
praisonai checkpoint save "Checkpoint message" -w /path/to/project
FlagShortDescriptionDefault
--allow-emptyAllow a checkpoint even when no files have changedfalse
--workspace-wWorkspace directory to snapshotcurrent directory

Expected Output:

✅ Checkpoint saved: abc12345
   Message: Before refactoring
   Files changed: 3

List Checkpoints

bash
praisonai checkpoint list
praisonai checkpoint list --limit 10
praisonai checkpoint list -n 5 -w /path/to/project
FlagShortDescriptionDefault
--limit-nMaximum number of checkpoints to show20
--workspace-wWorkspace directorycurrent directory

Expected Output:

╭─ Checkpoints ────────────────────────────────────────────────────────────────╮
│  1. [abc12345] Before refactoring (2024-12-24 07:30:00)                     │
│  2. [def67890] Initial state (2024-12-24 07:25:00)                          │
╰──────────────────────────────────────────────────────────────────────────────╯

Show Diff

bash
praisonai checkpoint diff
praisonai checkpoint diff last
praisonai checkpoint diff abc12345
praisonai checkpoint diff abc12345 def67890
praisonai checkpoint diff last def67890
praisonai checkpoint diff -w /path/to/project
FlagShortDescriptionDefault
--workspace-wWorkspace directorycurrent directory

Both the from and to arguments accept a full id, short id, unique prefix, or the alias last / latest.

Restore Checkpoint

bash
praisonai checkpoint restore last
praisonai checkpoint restore abc12345
praisonai checkpoint restore --step 3
praisonai checkpoint restore abc1 -w /path/to/project
FlagShortDescriptionDefault
--stepRestore the per-step checkpoint tagged with this step index
--workspace-wWorkspace directorycurrent directory

A checkpoint id and --step are mutually exclusive — providing both returns Provide either a checkpoint id/'last' or --step N, not both.

Rewind Checkpoints

Rewind the workspace back N checkpoints from the latest. rewind is the shortest command for undoing the most recent checkpointed change — you don’t need to remember an id.

bash
praisonai checkpoint rewind            # undo the last checkpoint (steps=1)
praisonai checkpoint rewind 3          # step back 3 checkpoints from the latest
praisonai checkpoint rewind 2 -w /path/to/project
Argument / FlagShortDescriptionDefault
steps (positional)How many checkpoints to step back (must be >= 1)1
--workspace-wWorkspace directorycurrent directory

Expected Output:

✅ Rewound 1 checkpoint(s) to: abc12345

When to use rewind vs restore:

  • restore <id> — you know the exact checkpoint id and want to jump there.
  • rewind [steps] — you just want to undo the last N checkpoints without looking up ids (equivalent to restore on list_checkpoints()[steps]).

Errors:

$ praisonai checkpoint rewind 99
✗ Failed to rewind: Cannot rewind 99 step(s): only 3 checkpoint(s) available
  • Cannot rewind 5 step(s): only 2 checkpoint(s) available — history too short.
  • steps must be >= 1 — invalid input.

Delete Checkpoints

bash
praisonai checkpoint delete
praisonai checkpoint delete --yes
praisonai checkpoint delete -y -w /path/to/project
FlagShortDescriptionDefault
--yes-ySkip the interactive confirmation promptfalse
--workspace-wWorkspace directorycurrent directory

Omitting --yes prompts: Delete all checkpoints? [y/N].

Reference Aliases

Every subcommand that accepts a checkpoint reference (restore, diff, run --restore) supports these forms:

ReferenceResolves to
last or latestThe newest checkpoint (list is newest-first)
Full id (e.g. abc12345def67890…)Exact match
Short id (e.g. abc12345)Exact short-id match
Unique prefix (e.g. abc1)Matches if exactly one checkpoint starts with that prefix

Ambiguous prefix example:

$ praisonai checkpoint restore abc
Error: Ambiguous checkpoint reference: abc

Ambiguous prefixes are rejected so a workspace-mutating restore never targets the wrong checkpoint.

Python API

python
import asyncio
from praisonaiagents.checkpoints import CheckpointService

async def main():
    service = CheckpointService(
        workspace_dir="/path/to/project",
        max_file_size=2 * 1024 * 1024,   # 2 MB; 0 disables the cap
    )
    await service.initialize()

    # Save checkpoint (optionally tag with a step index)
    result = await service.save("Before changes")
    await service.save("After step 0", step=0)
    print(f"Saved: {result.checkpoint.short_id}")

    # List checkpoints
    checkpoints = await service.list_checkpoints()
    for cp in checkpoints:
        print(f"{cp.short_id}: {cp.message} (step={cp.step})")

    # Restore by id or step index
    await service.restore(result.checkpoint.id)
    await service.restore(step=0)

    # Rewind N checkpoints back from the latest (default 1)
    result = await service.rewind(1)
    print(f"Rewound to: {result.checkpoint.short_id}")
    await service.rewind(3)

asyncio.run(main())

max_file_size bytes-caps individual files staged into the shadow commit (default 2 MB; 0 disables). Oversized files stay on disk and appear in praisonai checkpoint diff as unstaged.

See Also