Purpose
claude-snapshot is used to export and restore the Claude Code configuration environment. It is officially described as "a portable Claude Code configuration snapshot—export, compare, and apply your configuration across multiple machines." Typical uses include:
- Synchronizing personal and work configurations between multiple machines: export a snapshot at home, put it in cloud storage, and apply it at the office.
- Saving a snapshot before formatting a Mac or reinstalling the system, and restoring the entire Claude Code configuration after reinstalling.
- Safe rollback: take a snapshot before trying new plugins or high-risk configuration changes, and apply the snapshot to return to a known good state if problems occur.
- Team onboarding: share a team snapshot so new members get the same plugins, hooks, and conventions.
Main capabilities
- Export: read ~/.claude/, write a .tar.gz snapshot that contains a manifest.json index.
- Apply: extract the snapshot, resolve $HOME for the target machine, back up conflicting files as .bak, and install missing plugins.
- Snapshot contents: settings, CLAUDE.md, hooks, plugin manifests, MCP servers. MCP servers are collected from the mcpServers key in ~/.claude.json and placed into the tar archive; when applying, it only reports which MCPs need to be installed on the target machine, and does not automatically write to ~/.claude.json (because that file also contains OAuth tokens and project state).
- Portability: absolute paths (such as /Users/you/) are normalized to $HOME during export.
- Reviewable: snapshot contents can be inspected via /snapshot:inspect without extracting.
- Output format: prints a human-readable summary in an interactive terminal; outputs single-line JSON in a pipe; --json can be passed to force JSON in the terminal.
Design principles
- [P1] Minimal footprint: one-off commands, no daemon, no background listening, no network. Every side effect is triggered by an explicit user command and is scoped to ~/.claude/ and the output tar package path.
- [P2] Allowlist over denylist: snapshots only include explicitly listed artifacts; files added by future versions of Claude Code will not be captured automatically, and plugin updates determine what content is included. This trades manual maintenance for predictability.Testable, auditable snapshot content.
- [P3] Never goes online: both export and apply are local operations. Plugin reinstallation during apply is delegated to Claude Code's own /plugin install mechanism, which manages network access; claude-snapshot itself makes no outbound requests.
- [P4] Diff before overwrite: a diff summary is shown for user confirmation before every apply. Every file that is overwritten is first copied to <file>.bak.
- [P5] Cross-platform first: the plugin uses Node.js rather than bash, so it runs on macOS and Linux without polyfills or different code paths; Windows is supported via WSL, with native Windows supported on a best-effort basis.
Usage
Prerequisites: Claude Code with plugin support; Node.js 18+ (the plugin uses the tar npm package for archive I/O).
As a Claude Code plugin (recommended):
Try without installing (via npx): Run directly from the npm registry with no marketplace registration, no installation, and no reload. The command writes a snapshot to ~/claude-snapshot-YYYY-MM-DD.tar.gz and prints the path; other commands take that path as their only argument. Suitable for one-off backups, CI, or trying it out before adding the plugin to Claude Code.
What snapshots read and write
Reads: reads ~/.claude/ during export. Writes: writes to ~/.claude/ during apply, and automatically backs up any conflicting file as .bak; the output tar archive is written to the path you specify (default ~/). Does not touch: does not write outside ~/.claude/ and the specified output path; no network requests; no telemetry, no analytics, data never leaves the local machine; does not require --dangerously-skip-permissions.
Rollback and deletion
During apply, every file that is overwritten is first copied to <file>.bak, so if something goes wrong you can restore from the .bak or re-apply the previous snapshot. The snapshots you create (*.tar.gz) are ordinary files and can be deleted like any other file.
Limitations and current status
The current version, v0.2, treats Claude Code as a first-class environment. The architecture is deliberately kept tool-agnostic at the collector layer—collect() reads the config directory and produces a structured snapshot—so extending to similar agent tools is a natural next step. Planned support: the goal is "one tool, one command (npx claude-snapshot export --target codex), multiple backends," so that migrating across machines or between different agents does not require rebuilding the entire configuration set. Contributions adding collectors/appliers for new tools are welcome; the bar is hermetic test fixtures and round-trip tests that follow the existing patterns in tests/snapshot.test.mjs. Shorter-term (non-tool-extension) items: a --with-mcp flag that writes ~/.claude.json during apply (opt-in, with a .bak of the entire file); an encrypted snapshot option for team sharing; selective apply (choosing a subset of the snapshot contents). Submit issues and PRs to github.com/adhenawer/claude-snapshot/issues; for larger changes, please open an issue first to discuss the approach.
Information not yet provided
The official text does not provide specific pricing, platform availability, processing results data, performance metrics, usage step screenshots, or user reviews, so these are not covered here.
