Claude Code Plugin
Relevant source files
The following files were used as context for generating this wiki page:
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:
- Proactive Automation: Monitoring for risky operations (like large refactors or dependency changes) to suggest saves.
- Direct Operations: Executing user-requested commands with safety checks (e.g., forced dry-runs before restoration).
- 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.
Proactive Protection Logic
The skill identifies "risky operations" to prevent data loss during AI-driven workspace modifications.
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 rmoperations. - Dependency Changes: Modifications to
package.json,Cargo.toml, orgo.mod. - Risky Git Actions: Operations like
git rebaseorgit 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:
chkpt save -m "message"
chkpt list --limit 10
chkpt restore <id> --dry-run
chkpt delete <id>
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
The following files were used as context for generating this wiki page:
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:
- Proactive Automation: Monitoring for risky operations (like large refactors or dependency changes) to suggest saves.
- Direct Operations: Executing user-requested commands with safety checks (e.g., forced dry-runs before restoration).
- 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.
Proactive Protection Logic
The skill identifies "risky operations" to prevent data loss during AI-driven workspace modifications.
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 rmoperations. - Dependency Changes: Modifications to
package.json,Cargo.toml, orgo.mod. - Risky Git Actions: Operations like
git rebaseorgit 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:
chkpt save -m "message"
chkpt list --limit 10
chkpt restore <id> --dry-run
chkpt delete <id>
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