claude-snapshot — Summary

claude-snapshot is a Claude Code plugin that exports the complete ~/.claude/ setup (settings, CLAUDE.md files, plugins, hooks, MCP server configs, marketplace registrations) as a portable .tar.gz archive and applies it to another machine in under 2 minutes. It solves three concrete problems: multi-machine sync (personal ↔ work), OS reinstall recovery (backup before format), and team onboarding (share a snapshot with new team members). The plugin ships 4 Claude Code slash commands (/snapshot:export, /snapshot:inspect, /snapshot:diff, /snapshot:apply) backed by a Node.js core script (src/snapshot.mjs) that handles all file operations. Design principles are explicitly numbered (P1–P5): Minimal Blast Radius (no daemon, no background watch), Allowlist Over Denylist (explicit artifact list rather than wholesale capture), No Network Ever (local-only), Diff Before Destroy (preview before apply with .bak backup), and Cross-Platform First-Class (Node.js rather than bash). An npx -y claude-snapshot path allows use without plugin installation. Among seeds, there is no direct parallel — claude-snapshot is not a workflow methodology but a machine migration utility for Claude Code's configuration layer, most similar to agent-os in that it manages the ~/.claude/ directory, but unlike agent-os it manages existing configurations rather than authoring new conventions.

claude-snapshot — Overview

Origin

Created by Rodolfo Moraes (adhenawer on GitHub). Published as a Claude Code plugin at version 0.3.0.

Philosophy

The README explicitly documents five design principles:

[P1] Minimal Blast Radius: one-shot commands, no daemon, no background watch, no network. Every side effect is triggered by an explicit user command and scoped to ~/.claude/ plus the output tarball path.

[P2] Allowlist Over Denylist: snapshots contain an explicit list of artifacts (settings, CLAUDE.md, hooks, plugin manifests, MCP servers). New files Claude Code adds in future versions are NOT auto-captured — plugin updates decide what gets included. This is the opposite trade-off from wholesale-capture tools; we pay with manual maintenance and gain predictable, auditable snapshot contents.

[P3] No Network, Ever: export and apply are local-only. Plugin reinstallation during apply delegates to Claude Code's own /plugin install mechanism, which manages network access itself. claude-snapshot makes zero outbound requests.

[P4] Diff Before Destroy: every apply is preceded by a diff summary the user must acknowledge. Every overwritten file is first copied to <file>.bak. Snapshot contents are always inspectable without extraction via /snapshot:inspect.

[P5] Cross-Platform First-Class: the plugin is Node.js, not bash. It runs the same on macOS and Linux without polyfills, different code paths, or GNU-coreutils assumptions. Windows via WSL is supported; native Windows is best-effort.

Use Cases

1. Multiple machines — personal ↔ work sync
2. OS reinstall — backup before format, restore after fresh install
3. Safe rollback — snapshot before risky config experiments
4. Team onboarding — share snapshot with new team members for instant parity

claude-snapshot — Architecture

Distribution

• Type: Claude Code plugin (primary) + npm package (secondary)
• Plugin name: snapshot@claude-snapshot
• npm package: claude-snapshot
• Version analyzed: 0.3.0
• Runtime required: Node.js 18+, Claude Code with plugin support
• Language: JavaScript (Node.js ESM)
• npm dependency: tar package for archive I/O

Install Methods

# As Claude Code plugin (recommended)
/plugin marketplace add adhenawer/claude-snapshot
/plugin install snapshot@claude-snapshot
/reload-plugins

# Via npx (no install)
npx -y claude-snapshot export
npx -y claude-snapshot inspect <path>
npx -y claude-snapshot diff <path>
npx -y claude-snapshot apply <path>

Directory Tree

claude-snapshot/
├── src/
│   └── snapshot.mjs         # Core Node.js ESM script
├── commands/
│   ├── export.md             # /snapshot:export command
│   ├── inspect.md            # /snapshot:inspect command
│   ├── diff.md               # /snapshot:diff command
│   └── apply.md              # /snapshot:apply command
├── .claude-plugin/
│   ├── plugin.json           # Plugin manifest (name: snapshot, version: 0.3.0)
│   └── marketplace.json
├── tests/                    # 57 passing tests
├── docs/
└── package.json

Snapshot Anatomy

claude-snapshot-YYYY-MM-DD.tar.gz
├── manifest.json          # schemaVersion, plugins, marketplaces, hooks, MDs, MCPs, checksums
├── settings.json          # Claude Code settings (plugins, hooks, permissions, env, statusLine)
├── mcp-servers.json       # MCP configs (path-normalized, OAuth tokens excluded)
├── global-md/             # CLAUDE.md + other root-level .md files
├── hooks/                 # Custom hook scripts
├── plugins/
│   ├── installed_plugins.json
│   ├── known_marketplaces.json
│   └── blocklist.json
└── cache/                 # (only with --full)

What Migrates

Cross-Platform

• Absolute paths (like /Users/you/) normalized to $HOME at export
• Resolved back to current machine's $HOME at apply
• Windows native: best-effort; WSL: supported

claude-snapshot — Components

Commands (4 slash commands)

Core Script

src/snapshot.mjs — single Node.js ESM module implementing all snapshot operations:

• Export: reads ~/.claude/, normalizes paths, creates .tar.gz with manifest.json
• Inspect: extracts and displays manifest without side effects
• Diff: compares manifest against current ~/.claude/ state
• Apply: backup → write → install plugins (delegates to Claude Code's /plugin install)

npx Interface

npx -y claude-snapshot export
npx -y claude-snapshot inspect <path>
npx -y claude-snapshot diff <path>
npx -y claude-snapshot apply <path>

Outputs:

• Human-readable summary (interactive terminal)
• Single JSON line when piped
• --json flag forces JSON in terminal

Plugin Manifest

{
  "name": "snapshot",
  "version": "0.3.0",
  "description": "Export and apply portable snapshots of your Claude Code setup across machines",
  "author": { "name": "Rodolfo Moraes" },
  "repository": "https://github.com/adhenawer/claude-snapshot",
  "license": "MIT"
}

No Hooks, No Skills, No MCP

claude-snapshot ships zero hooks, skills, subagents, or MCP servers. It is a pure utility plugin.

Tests

57 passing tests covering export, inspect, diff, and apply operations.

claude-snapshot — Uniqueness

differs_from_seeds

claude-snapshot has no direct analog among the 11 seeds. It is entirely infrastructure-focused — managing the ~/.claude/ directory as a configuration artifact — rather than defining agent behavior, spec formats, or workflow methodology. The closest seed parallel is agent-os (which also manages ~/.claude/ content), but agent-os authors new standards while claude-snapshot migrates existing ones. Unlike claude-conductor (which provides markdown templates), claude-snapshot treats the entire Claude Code configuration layer as a portable backup artifact. It has zero overlap with workflow seeds (superpowers, BMAD-METHOD, spec-driver, spec-kit) — it exists in the "configuration infrastructure" layer that all workflow seeds assume but none address. The most philosophically similar framework in this batch is claude-overlay (which also manages Claude Code config files), but claude-overlay manages provider credentials while claude-snapshot manages the complete setup portability.

Positioning

• Primary differentiator: The only tool in the catalog explicitly designed for Claude Code configuration portability and backup. Snapshots include a complete machine-portable archive of plugins, hooks, CLAUDE.md files, and MCP configs with path normalization.
• Secondary differentiator: Explicit design principles (P1–P5) published in the README — unusual rigor for a 2-star project. The design shows careful reasoning about blast radius, reversibility, and OAuth token safety.
• Target user: Developers with multiple machines (personal + work) or who regularly reinstall OSes and need to preserve their Claude Code setup.

Observable Failure Modes

1. Version skew: If Claude Code changes ~/.claude/ file formats between snapshot export and apply, the snapshot may be partially incompatible. The schemaVersion in manifest.json should help but is not documented as having compatibility guarantees.
2. MCP manual installation: MCP servers are reported but not applied automatically. On machines with many MCPs, the manual step list could be long and error-prone.
3. Plugin marketplace assumption: Apply relies on /plugin install which requires the marketplace to be accessible. Air-gapped machines cannot apply plugin-containing snapshots.
4. .bak accumulation: Each apply creates .bak files; repeated applies to the same machine accumulate backup files without cleanup.
5. Narrow scope (Claude Code only): Snapshots are useless on machines using Cursor, Codex, or other AI tools — the format is Claude Code-specific.