Checkpoints - PraisonAI

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

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 --step 3
praisonai checkpoint restore abc1 -w /path/to/project

Flag	Short	Description	Default
`--step`		Restore the per-step checkpoint tagged with this step index
`--workspace`	`-w`	Workspace directory	current 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.

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 / Flag	Short	Description	Default
`steps` (positional)		How many checkpoints to step back (must be `>= 1`)	`1`
`--workspace`	`-w`	Workspace directory	current 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]).

steps must be >= 1. Passing 0 or a negative value is rejected by the CLI before the service runs.

rewind can reach shadow-git commits older than max_checkpoints. The max_checkpoints limit only trims the in-memory listing — the underlying shadow git retains every commit, so rewind N still works even if N > max_checkpoints.

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

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

​Quick Start

​Usage

​Save Checkpoint

​List Checkpoints

​Show Diff

​Restore Checkpoint

​Rewind Checkpoints

​Delete Checkpoints

​Reference Aliases

​Python API

​See Also

Quick Start

Usage

Save Checkpoint

List Checkpoints

Show Diff

Restore Checkpoint

Rewind Checkpoints

Delete Checkpoints

Reference Aliases

Python API

See Also