AI Automation Patterns
Relevant source files
The following files were used as context for generating this wiki page:
AI Automation Patterns in the chkpt ecosystem define how AI agents (specifically within the Claude Code plugin and MCP server context) proactively protect user workspaces. By integrating with a content-addressable checkpoint system, these patterns ensure that risky operations are preceded by snapshots, and recovery is streamlined through structured "dry-run" and confirmation workflows.
These patterns govern the behavior of the chkpt skill, which acts as a workspace checkpoint assistant. The assistant monitors for specific triggers—such as large-scale refactoring or dependency changes—and suggests saving a checkpoint to ~/.chkpt/stores/<project_id>/ without polluting the user's Git history.
Sources: crates/chkpt-plugin/skills/chkpt/SKILL.md:10-18, README.md:9-16
Proactive Saving Patterns
The system identifies specific "Risky Operations" and "Milestones" where a checkpoint (chkpt save) should be suggested to the user.
Before Risky Operations
The assistant is designed to suggest a checkpoint before any operation that could cause workspace corruption or significant loss of state.
| Operation Category | Description |
|---|---|
| Large-scale Refactoring | Changing more than 5 files, renaming modules, or moving directories. |
| Deletion | Using rm, git rm, or any bulk file removal. |
| Dependency Changes | Modifying package.json, Cargo.toml, requirements.txt, or go.mod. |
| Risky Git Operations | Executing git rebase, git reset, or git merge with expected conflicts. |
| Database Migrations | Schema changes affecting application state. |
| Configuration Changes | Modifying environment files, build configs, or CI/CD pipelines. |
Sources: crates/chkpt-plugin/skills/chkpt/references/automation-patterns.md:5-13, crates/chkpt-cli/skills/chkpt/references/automation-patterns.md:5-13
After Milestones
Checkpoints are also recommended after achieving a "known-good" state to serve as a stable recovery point.
- Major Feature Completion: When a logical unit of work is functional.
- Successful Verification: After resolving complex build issues or when all tests pass.
Sources: crates/chkpt-plugin/skills/chkpt/references/automation-patterns.md:20-24, crates/chkpt-cli/skills/chkpt/references/automation-patterns.md:20-24
Decision Logic for Suggestions
The following diagram illustrates the decision flow used by the AI assistant when determining whether to trigger a checkpoint suggestion.
The assistant avoids "proactive noise" by skipping suggestions for minor edits (1-2 files), read-only browsing, or if the user recently declined a suggestion in the same session.
Sources: crates/chkpt-plugin/skills/chkpt/references/automation-patterns.md:40-45, crates/chkpt-cli/skills/chkpt/SKILL.md:25-30
Restore and Recovery Patterns
The chkpt restore command is suggested when changes result in repeated failures or when the user explicitly requests an "undo" or "rollback".
Safe Restore Workflow
To prevent accidental overwrites, the AI automation patterns enforce a strict multi-step restore process.
- Dry Run: The assistant executes
chkpt restore <id> --dry-runto identify changed and removed files. - Visualization: The results (e.g., "filesChanged", "filesRemoved") are shown to the user.
- Confirmation: The assistant asks for explicit approval via
AskUserQuestion. - Application: Only after approval is the actual restore executed.
Integration Architectures
The AI patterns are implemented across two primary modes depending on the environment:
Mode 1: MCP Plugin (Claude Code)
Uses 4 Model Context Protocol (MCP) tools: checkpoint_save, checkpoint_list, checkpoint_restore, and checkpoint_delete. These tools return JSON responses containing snapshot IDs and statistics.
Sources: crates/chkpt-plugin/skills/chkpt/SKILL.md:13-18
Mode 2: CLI Fallback
If MCP tools are unavailable, the assistant falls back to direct shell execution via the chkpt CLI.
| MCP Tool | CLI Equivalent |
|---|---|
checkpoint_save | chkpt save [-m <message>] |
checkpoint_list | chkpt list [--limit N] |
checkpoint_restore | chkpt restore <id> [--dry-run] |
checkpoint_delete | chkpt delete <id> |
Sources: crates/chkpt-plugin/skills/chkpt/SKILL.md:52-59, crates/chkpt-cli/skills/chkpt/SKILL.md:32-35
Store Inspection Pattern
When users need to debug or examine the internals of a checkpoint, the AI follows a structured "Store Inspection" pattern:
- Identify: List snapshots to find the correct
snapshot_id. - Locate: Resolve the workspace to a store path (e.g.,
~/.chkpt/stores/<project_id>/). - Query: Use SQLite queries against
catalog.sqliteto inspectsnapshot_filesorblob_index. - Verify: Access content-addressable storage in
packs/ortrees/.
Sources: crates/chkpt-plugin/skills/chkpt/SKILL.md:61-70, CLAUDE.md:12-18, crates/chkpt-core/src/config.rs:24-60
Summary
AI Automation Patterns in chkpt provide a safety net for developers by automating workspace snapshots. By codifying "risky" scenarios and enforcing a dry-run-first restore policy, the system ensures that AI-driven or human-initiated workspace modifications remain reversible without requiring manual Git management.