Checkpoints

Shadow git checkpointing for file-level undo/restore

The checkpoint command manages file-level checkpoints using shadow git.

All checkpoint subcommands respect checkpoints.storage_dir from your project config (agents.yaml). This means praisonai checkpoint list, restore, and diff operate on the same store as praisonai code --checkpoints sessions and praisonai run auto-checkpoints.

# agents.yaml
checkpoints:
  storage_dir: ./.praisonai/checkpoints   # optional

Quick Start

# Save a checkpoint
praisonai checkpoint save "Before refactoring"

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

Usage

Save Checkpoint

praisonai checkpoint save "Checkpoint message"
praisonai checkpoint save "Checkpoint message" --allow-empty
praisonai checkpoint save "Checkpoint message" -w /path/to/project

Flag	Short	Description	Default
--allow-empty		Allow a checkpoint even when no files have changed	false
--workspace	-w	Workspace directory to snapshot	current directory

Expected Output:

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

List Checkpoints

praisonai checkpoint list
praisonai checkpoint list --limit 10
praisonai checkpoint list -n 5 -w /path/to/project

Flag	Short	Description	Default
--limit	-n	Maximum number of checkpoints to show	20
--workspace	-w	Workspace directory	current 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

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

Flag	Short	Description	Default
--workspace	-w	Workspace directory	current directory

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

Restore Checkpoint

praisonai checkpoint restore last
praisonai checkpoint restore abc12345
praisonai checkpoint restore abc1 -w /path/to/project

Flag	Short	Description	Default
--workspace	-w	Workspace directory	current directory

Delete Checkpoints

praisonai checkpoint delete
praisonai checkpoint delete --yes
praisonai checkpoint delete -y -w /path/to/project

Flag	Short	Description	Default
--yes	-y	Skip the interactive confirmation prompt	false
--workspace	-w	Workspace directory	current 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:

Reference	Resolves to
last or latest	The 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

import asyncio
from praisonaiagents.checkpoints import CheckpointService

async def main():
    service = CheckpointService(workspace_dir="/path/to/project")
    await service.initialize()
    
    # Save checkpoint
    result = await service.save("Before changes")
    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}")
    
    # Restore
    await service.restore(result.checkpoint.id)

asyncio.run(main())

---

See Also

• Shadow Git Checkpointing Feature
• Run command — Checkpoint & Rewind — --restore and --no-checkpoint flags