Relevant source files

The following files were used as context for generating this wiki page: - [crates/chkpt-plugin/skills/chkpt/SKILL.md](https://github.com/syi0808/chkpt/blob/main/crates/chkpt-plugin/skills/chkpt/SKILL.md) - [crates/chkpt-plugin/README.md](https://github.com/syi0808/chkpt/blob/main/crates/chkpt-plugin/README.md) - [CLAUDE.md](https://github.com/syi0808/chkpt/blob/main/CLAUDE.md) - [README.md](https://github.com/syi0808/chkpt/blob/main/README.md) - [crates/chkpt-plugin/skills/chkpt/references/cli-commands.md](https://github.com/syi0808/chkpt/blob/main/crates/chkpt-plugin/skills/chkpt/references/cli-commands.md) - [crates/chkpt-plugin/skills/chkpt/references/automation-patterns.md](https://github.com/syi0808/chkpt/blob/main/crates/chkpt-plugin/skills/chkpt/references/automation-patterns.md)

# Claude Code Plugin The Claude Code Plugin is an integration for the `chkpt` system designed to provide fast, content-addressable workspace snapshots directly within the Claude Code environment. It enables AI agents and developers to save, restore, and manage workspace states without affecting the Git history, serving as a "save game" mechanism for code refactors, dependency updates, or risky operations. Sources: [README.md:3-8](), [crates/chkpt-plugin/README.md:1-5]() The plugin consists of two primary components: an Model Context Protocol (MCP) server providing specialized tools, and an automation skill (`/chkpt:chkpt`) that guides Claude's behavior for proactive workspace protection. Sources: [crates/chkpt-plugin/README.md:11-20](), [CLAUDE.md:15-20]() ## Core Components and Architecture The plugin architecture leverages the MCP (Model Context Protocol) to expose the underlying Rust-based `chkpt-core` functionality to Claude Code. ### MCP Tools The plugin provides four primary tools that Claude can invoke to manage checkpoints. All tools require a `workspace_path` parameter to identify the target project. | Tool | Description | Key Parameters | |------|-------------|----------------| | `checkpoint_save` | Saves a workspace snapshot | `workspace_path`, `message` (optional) | | `checkpoint_list` | Lists available checkpoints | `workspace_path`, `limit` (optional) | | `checkpoint_restore` | Restores workspace to a snapshot | `workspace_path`, `snapshot_id`, `dry_run` (bool) | | `checkpoint_delete` | Deletes a specific snapshot | `workspace_path`, `snapshot_id` | Sources: [crates/chkpt-plugin/skills/chkpt/SKILL.md:16-19](), [crates/chkpt-plugin/README.md:13-18]() ### Automation Skill (`/chkpt:chkpt`) The automation skill defines how Claude should interact with the user and the workspace. It operates in three distinct modes: 1. **Proactive Automation**: Monitoring for risky operations (like large refactors or dependency changes) to suggest saves. 2. **Direct Operations**: Executing user-requested commands with safety checks (e.g., forced dry-runs before restoration). 3. **Store Inspection**: Debugging and examining the internal SQLite catalog and blob storage. Sources: [crates/chkpt-plugin/skills/chkpt/SKILL.md:24-58]() ## Operational Workflows The following diagrams illustrate the logic implemented within the plugin's skill definitions. ### Safety-First Restore Workflow The plugin enforces a mandatory dry-run and user confirmation phase before any destructive restoration occurs. ```mermaid flowchart TD Start[User requests restore] --> DryRun[Invoke checkpoint_restore with dry_run: true] DryRun --> ShowChanges[Display file changes/removals to User] ShowChanges --> Confirm{User Approved?} Confirm -- No --> End[Abort Restore] Confirm -- Yes --> FinalRestore[Invoke checkpoint_restore with dry_run: false] FinalRestore --> Success[Report success and stats] ``` Sources: [crates/chkpt-plugin/skills/chkpt/SKILL.md:43-46](), [crates/chkpt-plugin/skills/chkpt/references/cli-commands.md:52-70]() ### Proactive Protection Logic The skill identifies "risky operations" to prevent data loss during AI-driven workspace modifications. ```mermaid sequenceDiagram participant Claude as Claude Code participant Plugin as chkpt Plugin participant User as User Claude->>Claude: Detects risky op (e.g., rm -rf, large refactor) Claude->>User: Inform why a checkpoint is helpful Claude->>User: Propose saving "before: " alt User Agrees User-->>Claude: OK Claude->>Plugin: checkpoint_save(path, msg) Plugin-->>Claude: snapshot_id, stats Claude->>User: Snapshot saved. Proceeding with operation. else User Declines User-->>Claude: No Claude->>User: Proceeding without saving. end ``` Sources: [crates/chkpt-plugin/skills/chkpt/SKILL.md:26-34](), [crates/chkpt-plugin/skills/chkpt/references/automation-patterns.md:3-23]() ## Automation Patterns The plugin uses specific heuristics to determine when to intervene. These patterns are defined in the project's reference documentation. ### Risky Operation Triggers Claude is instructed to suggest a `chkpt save` when detecting: * **Large-scale refactoring**: Changing more than 5 files or renaming modules. * **File Deletion**: Bulk removal or `git rm` operations. * **Dependency Changes**: Modifications to `package.json`, `Cargo.toml`, or `go.mod`. * **Risky Git Actions**: Operations like `git rebase` or `git reset`. * **Infrastructure Changes**: Database migrations or CI/CD pipeline edits. Sources: [crates/chkpt-plugin/skills/chkpt/references/automation-patterns.md:5-18]() ### Milestone Recognition The plugin suggests saves after significant progress: * Feature completion. * Successful build after resolving errors. * Passing all test suites. Sources: [crates/chkpt-plugin/skills/chkpt/references/automation-patterns.md:25-33]() ## Technical Implementation Details The plugin interacts with the local filesystem through a standard layout located in `~/.chkpt/stores/`. ### Storage Backend * **Deduplication**: Uses content-addressed storage (BLAKE3 or XXH3-128 hashing). * **Compression**: Data is compressed using zstd or LZ4. * **Metadata**: Managed via a SQLite index (`catalog.sqlite`) for incremental change detection. Sources: [crates/chkpt-plugin/README.md:25-30](), [CLAUDE.md:6-10]() ### CLI Fallback If MCP tools are unavailable, the skill is configured to fall back to direct CLI commands: ```bash chkpt save -m "message" chkpt list --limit 10 chkpt restore --dry-run chkpt delete ``` Sources: [crates/chkpt-plugin/skills/chkpt/SKILL.md:50-58](), [crates/chkpt-plugin/skills/chkpt/references/cli-commands.md:1-80]() ## Summary The Claude Code Plugin transforms `chkpt` from a manual CLI tool into an automated safety net for AI-driven development. By integrating proactive suggestions and mandatory safety checks (dry-runs), it ensures that complex workspace modifications can be reverted instantly, providing a robust recovery mechanism during experimental coding or large-scale refactors. Sources: [crates/chkpt-plugin/README.md:7-10](), [crates/chkpt-plugin/skills/chkpt/SKILL.md:10-14]()助理: 好的，我将为您生成关于 **Claude Code Plugin** 的技术维基页面。

Relevant source files