claude-snapshot
claude-snapshot exports and imports portable snapshots of your entire Claude Code setup across machines. It captures settings.json, plugins,
Open source Open in the app JSON README (API)
About
claude-snapshot exports and imports portable snapshots of your entire Claude Code setup across machines. It captures settings.json, plugins, marketplace registrations, hooks, and global CLAUDE.md files into a single .tar.gz file with a manifest index. Absolute paths are normalized to $HOME for cross-machine portability. On apply, it backs up conflicting files as .bak and installs missing plugins automatically. Supports slim (config only, ~6KB) and full (with plugin caches for offline restore) export modes.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- adhenawer
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 2
- Last push
- 2026-04-19T15:03:21Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
adhenawer/claude-snapshot/claude-snapshot
README
<div align="center"> # claude-snapshot **Portable Claude Code setup snapshots.** Export your config, plugins, hooks, and global instructions — apply on another machine in under 2 minutes. [](https://github.com/adhenawer/claude-snapshot/actions/workflows/test.yml) [](https://github.com/adhenawer/claude-snapshot/actions/workflows/test.yml) [](https://github.com/adhenawer/claude-snapshot/commits/main)  [](https://opensource.org/licenses/MIT) [](https://docs.anthropic.com/en/docs/claude-code) [](https://nodejs.org/)  </div> ## Why - **Multiple machines** — Keep your personal and work setups in sync. Export at home, drop the file on Drive, apply at work. - **Mac format / OS reinstall** — Save a snapshot before wiping your machine. Restore your entire Claude Code setup after a fresh install. - **Safe rollback** — About to experiment with new plugins or risky config changes? Take a snapshot first. If things break, apply the snapshot and you're back to a known good state. - **Onboarding** — New team member? Share your team's snapshot and they're up and running with the same plugins, hooks, and conventions. ## Principles Design decisions in this plugin are evaluated against these 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. ## Prerequisites - Claude Code with plugin support - Node.js 18+ (the plugin uses the [`tar`](https://www.npmjs.com/package/tar) npm package for archive I/O) ## Install ### As a Claude Code plugin (recommended) ```bash # 1. Register the marketplace /plugin marketplace add adhenawer/claude-snapshot # 2. Install the plugin /plugin install snapshot@claude-snapshot # 3. Reload plugins /reload-plugins ``` ### Try without installing (via npx) No marketplace registration, no install, no reload — run it straight from the npm registry: ```bash npx -y claude-snapshot export ``` Writes a snapshot to `~/claude-snapshot-YYYY-MM-DD.tar.gz` and prints the path. The other commands take that path as their only argument: ```bash npx -y claude-snapshot inspect <path> npx -y claude-snapshot diff <path> npx -y claude-snapshot apply <path> ``` Useful for one-off backups, CI, or trying the tool before adding the plugin to your Claude Code setup. The CLI prints a human-readable summary on an interactive terminal and a single JSON line when piped — pass `--json` to force JSON in a terminal. ## Commands | Command | Description | |---|---| | `/snapshot:export` | Export your setup as a portable `.tar.gz` snapshot | | `/snapshot:inspect <path>` | Preview snapshot contents without extracting | | `/snapshot:diff <path>` | Compare a snapshot against your current setup | | `/snapshot:apply <path>` | Apply a snapshot to this machine (with confirmation) | ## Typical workflows ### Sync between machines ```bash # On your personal machine — writes to ~/claude-snapshot-YYYY-MM-DD.tar.gz /snapshot:export # Copy the file to your work machine (via Drive, scp, USB, etc.), then: /snapshot:apply ~/claude-snapshot-YYYY-MM-DD.tar.gz ``` ### Backup before format ```bash # Before wiping /snapshot:export # After fresh install + Claude Code installed /snapshot:apply ~/claude-snapshot-YYYY-MM-DD.tar.gz ``` ### Safe experimentation ```bash # Save current state /snapshot:export # Try new plugins, change hooks, break things... # Something went wrong? Roll back (use the path printed by export) /snapshot:apply ~/claude-snapshot-YYYY-MM-DD.tar.gz ``` ## What migrates | Artifact | Included | |---|---| | `settings.json` (plugins, hooks, permissions, env, statusLine) | Yes | | `CLAUDE.md` + other global `.md` files | Yes | | Plugin manifests + marketplace registrations | Yes | | Hook scripts | Yes | | MCP servers (from `~/.claude.json`, `mcpServers` key only — OAuth tokens excluded) | Yes (report only on apply) | | Plugin caches (with `--full`) | Yes | | Sessions, history, telemetry | No | | Project-scoped plugins | No | ## How it works ```mermaid flowchart LR SRC[Machine A<br/>~/.claude/] -->|/snapshot:export| PKG[claude-snapshot.tar.gz] PKG -->|/snapshot:inspect| SUM[manifest summary] PKG -->|/snapshot:diff| DIFF[diff vs current] PKG -->|/snapshot:apply| APP[backup → write → install] APP --> DST[Machine B<br/>~/.claude/] ``` 1. **Export** reads `~/.claude/` and writes a `.tar.gz` with a `manifest.json` index. 2. Absolute paths (like `/Users/you/`) are normalized to `$HOME` for portability. 3. **Apply** extracts the snapshot, resolves `$HOME` for the target machine, backs up any conflicting files as `.bak`, and installs missing plugins via `claude plugin install`. 4. **MCP servers** are captured from `~/.claude.json` (the `mcpServers` key only) and included in the tarball. On apply, claude-snapshot *reports* which MCPs need installation on the target machine — it does NOT auto-write `~/.claude.json` because that file also holds OAuth tokens and project state. ### Snapshot anatomy ``` claude-snapshot-YYYY-MM-DD.tar.gz ├── manifest.json # schemaVersion, plugins, marketplaces, hooks, MDs, MCPs, checksums ├── settings.json # your Claude Code settings ├── mcp-servers.json # MCP server configs (only if you have any; path-normalized) ├── global-md/ # CLAUDE.md and other root-level .md files ├── hooks/ # your custom hook scripts ├── plugins/ │ ├── installed_plugins.json │ ├── known_marketplaces.json │ └── blocklist.json └── cache/ # (only with --full) ``` ## Privacy claude-snapshot is designed with reversibility and minimal blast radius in mind. **What it touches** - Reads `~/.claude/` on export - Writes files into `~/.claude/` on apply — with automatic `.bak` backup of any conflicting file - Writes the output tarball to the path you specify (default: `~/`) **What it doesn't touch** - No writes outside `~/.claude/` and your chosen output path - No network requests — plugin install during apply delegates to Claude Code's own `/plugin install` mechanism - No telemetry, no analytics, nothing leaves your machine - Does not require `--dangerously-skip-permissions` **Reversibility** Every file overwritten during `apply` is copied to `<file>.bak` first. If something breaks, restore from the `.bak` files or re-apply the previous snapshot. ## Uninstall ```bash # Remove the plugin /plugin uninstall snapshot # (Optional) Remove the marketplace registration /plugin marketplace remove claude-snapshot ``` Snapshots you created (`*.tar.gz`) are plain files — delete them as you would any other file. ## Roadmap The current release (v0.2) targets **Claude Code** as its first-class environment. The architecture is deliberately tool-agnostic at the collector level — `collect()` reads a config directory and produces a structured snapshot — so extending to sibling agent tools is a natural next step. **Planned support** | Target | Config root | Status | |---|---|---| | Claude Code | `~/.claude/` | ✅ v0.2 (current) | | OpenAI Codex CLI | `~/.codex/` | 🚧 planned for v0.3 | | Cursor | `~/.cursor/` | 🚧 planned for v0.3 | The goal is one tool, one command (`npx claude-snapshot export --target codex`), many backends — so moving across machines or migrating between agents doesn't mean rebuilding the whole setup. Contributions that add a collector/applier for a new tool are welcome; the bar is a hermetic test fixture and a round-trip test matching the existing pattern in `tests/snapshot.test.mjs`. **Shorter-term items** (not tool-expansion) - `--with-mcp` flag to write through `~/.claude.json` on apply (opt-in, with `.bak` of the full file) - Encrypted snapshot option for team sharing - Selective apply (pick subset of the snapshot contents) ## Contributing Issues and PRs welcome at [github.com/adhenawer/claude-snapshot/issues](https://github.com/adhenawer/claude-snapshot/issues). For larger changes, please open an issue first to discuss the approach. ## License [MIT](LICENSE)