fabricatio-checkpoint

MIT

Worktree checkpointing via shadow Git repositories for fabricatio workflows. Save, diff, rollback individual files, or reset entire directories — without interfering with any existing Git repository.

Installation

pip install fabricatio[checkpoint]

For a full installation with all fabricatio components:

pip install fabricatio[full]

Overview

fabricatio-checkpoint maintains a bare Git shadow repository for each tracked worktree directory. It stages and commits file changes behind the scenes, enabling:

• Checkpoints — save worktree state at any point with a message
• Selective rollback — restore individual files to a previous commit without touching others
• Full reset — revert the entire worktree to a prior checkpoint
• Diffs — retrieve file-level changes between any commit and the current state
• Status — list modified, added, or deleted files since the last checkpoint

The shadow repositories live under ~/.fabricatio-checkpoint/ by default and never touch any existing .git directory.

Key Types

CheckpointService

Manages the lifecycle of shadow repositories. Created once per process via the singleton helper.

from fabricatio_checkpoint.inited_service import get_checkpoint_service

svc = get_checkpoint_service()
store = svc.get_store("/path/to/project")

CheckPointStore

A shadow repository bound to one worktree directory. Backed by a bare Git repo (Rust implementation via PyO3).

store = svc.get_store("/path/to/project")

cid = store.save("snapshot before refactor")
store.rollback(cid, "src/main.py")
store.reset(cid)
print(store.get_file_diff(cid, "src/main.py"))

Checkpoint (Capability Mixin)

A UseLLM-compatible mixin for use within fabricatio agent roles.

from fabricatio_checkpoint.capabilities.checkpoint import Checkpoint

class MyAgent(Checkpoint, SomeLLMRole):
    worktree_dir = Path("/path/to/project")

agent = MyAgent().mount_checkpoint_store()
cid = agent.save_checkpoint("before editing")
agent.rollback(cid, "config.toml")

prune_stores(stores_root)

Free function: deletes shadow repositories under stores_root whose worktree directories no longer exist.

from fabricatio_checkpoint.rust import prune_stores

prune_stores(Path.home() / ".fabricatio-checkpoint")

CLI

The package ships a ckpt command (requires pip install fabricatio-checkpoint[cli]):

ckpt --workspace /path/to/project save "checkpoint message"
ckpt --workspace /path/to/project reset <commit_id>
ckpt --workspace /path/to/project diff
ckpt --workspace /path/to/project ls
ckpt workspaces

Configuration

All options below are read through the fabricatio configuration chain (see the Configuration Guide). Set them under the [ext.checkpoint] table in fabricatio.toml, equivalently under [tool.fabricatio.ext.checkpoint] in pyproject.toml, or via FABRICATIO_EXT__CHECKPOINT__<FIELD_UPPER> environment variables.

[ext.checkpoint]
checkpoint_dir = "~/.fabricatio-checkpoint"
cache_size = 100

Access at runtime: from fabricatio_checkpoint.config import checkpoint_config.

Dependencies

• fabricatio-core — core interfaces and config system

No additional Python dependencies required for basic use. The optional [cli] extra adds typer.

License

MIT — see LICENSE