{
"markdown": "\n\n# claude-snapshot\n\n**Portable Claude Code setup snapshots.** Export your config, plugins, hooks, and global instructions — apply on another machine in under 2 minutes.\n\n[](https://github.com/adhenawer/claude-snapshot/actions/workflows/test.yml)\n[](https://github.com/adhenawer/claude-snapshot/actions/workflows/test.yml)\n[](https://github.com/adhenawer/claude-snapshot/commits/main)\n\n[](https://opensource.org/licenses/MIT)\n[](https://docs.anthropic.com/en/docs/claude-code)\n[](https://nodejs.org/)\n\n\n\n
\n\n## Why\n\n- **Multiple machines** — Keep your personal and work setups in sync. Export at home, drop the file on Drive, apply at work.\n- **Mac format / OS reinstall** — Save a snapshot before wiping your machine. Restore your entire Claude Code setup after a fresh install.\n- **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.\n- **Onboarding** — New team member? Share your team's snapshot and they're up and running with the same plugins, hooks, and conventions.\n\n## Principles\n\nDesign decisions in this plugin are evaluated against these principles.\n\n**[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.\n\n**[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.\n\n**[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.\n\n**[P4] Diff Before Destroy**: every `apply` is preceded by a diff summary the user must acknowledge. Every overwritten file is first copied to `.bak`. Snapshot contents are always inspectable without extraction via `/snapshot:inspect`.\n\n**[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.\n\n## Prerequisites\n\n- Claude Code with plugin support\n- Node.js 18+ (the plugin uses the [`tar`](https://www.npmjs.com/package/tar) npm package for archive I/O)\n\n## Install\n\n### As a Claude Code plugin (recommended)\n\n```bash\n# 1. Register the marketplace\n/plugin marketplace add adhenawer/claude-snapshot\n\n# 2. Install the plugin\n/plugin install snapshot@claude-snapshot\n\n# 3. Reload plugins\n/reload-plugins\n```\n\n### Try without installing (via npx)\n\nNo marketplace registration, no install, no reload — run it straight from the npm registry:\n\n```bash\nnpx -y claude-snapshot export\n```\n\nWrites a snapshot to `~/claude-snapshot-YYYY-MM-DD.tar.gz` and prints the path. The other commands take that path as their only argument:\n\n```bash\nnpx -y claude-snapshot inspect \nnpx -y claude-snapshot diff \nnpx -y claude-snapshot apply \n```\n\nUseful for one-off backups, CI, or trying the tool before adding the plugin to your Claude Code setup.\n\nThe 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.\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `/snapshot:export` | Export your setup as a portable `.tar.gz` snapshot |\n| `/snapshot:inspect ` | Preview snapshot contents without extracting |\n| `/snapshot:diff ` | Compare a snapshot against your current setup |\n| `/snapshot:apply ` | Apply a snapshot to this machine (with confirmation) |\n\n## Typical workflows\n\n### Sync between machines\n\n```bash\n# On your personal machine — writes to ~/claude-snapshot-YYYY-MM-DD.tar.gz\n/snapshot:export\n\n# Copy the file to your work machine (via Drive, scp, USB, etc.), then:\n/snapshot:apply ~/claude-snapshot-YYYY-MM-DD.tar.gz\n```\n\n### Backup before format\n\n```bash\n# Before wiping\n/snapshot:export\n\n# After fresh install + Claude Code installed\n/snapshot:apply ~/claude-snapshot-YYYY-MM-DD.tar.gz\n```\n\n### Safe experimentation\n\n```bash\n# Save current state\n/snapshot:export\n\n# Try new plugins, change hooks, break things...\n\n# Something went wrong? Roll back (use the path printed by export)\n/snapshot:apply ~/claude-snapshot-YYYY-MM-DD.tar.gz\n```\n\n## What migrates\n\n| Artifact | Included |\n|---|---|\n| `settings.json` (plugins, hooks, permissions, env, statusLine) | Yes |\n| `CLAUDE.md` + other global `.md` files | Yes |\n| Plugin manifests + marketplace registrations | Yes |\n| Hook scripts | Yes |\n| MCP servers (from `~/.claude.json`, `mcpServers` key only — OAuth tokens excluded) | Yes (report only on apply) |\n| Plugin caches (with `--full`) | Yes |\n| Sessions, history, telemetry | No |\n| Project-scoped plugins | No |\n\n## How it works\n\n```mermaid\nflowchart LR\n SRC[Machine A
~/.claude/] -->|/snapshot:export| PKG[claude-snapshot.tar.gz]\n PKG -->|/snapshot:inspect| SUM[manifest summary]\n PKG -->|/snapshot:diff| DIFF[diff vs current]\n PKG -->|/snapshot:apply| APP[backup → write → install]\n APP --> DST[Machine B
~/.claude/]\n```\n\n1. **Export** reads `~/.claude/` and writes a `.tar.gz` with a `manifest.json` index.\n2. Absolute paths (like `/Users/you/`) are normalized to `$HOME` for portability.\n3. **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`.\n4. **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.\n\n### Snapshot anatomy\n\n```\nclaude-snapshot-YYYY-MM-DD.tar.gz\n├── manifest.json # schemaVersion, plugins, marketplaces, hooks, MDs, MCPs, checksums\n├── settings.json # your Claude Code settings\n├── mcp-servers.json # MCP server configs (only if you have any; path-normalized)\n├── global-md/ # CLAUDE.md and other root-level .md files\n├── hooks/ # your custom hook scripts\n├── plugins/\n│ ├── installed_plugins.json\n│ ├── known_marketplaces.json\n│ └── blocklist.json\n└── cache/ # (only with --full)\n```\n\n## Privacy\n\nclaude-snapshot is designed with reversibility and minimal blast radius in mind.\n\n**What it touches**\n\n- Reads `~/.claude/` on export\n- Writes files into `~/.claude/` on apply — with automatic `.bak` backup of any conflicting file\n- Writes the output tarball to the path you specify (default: `~/`)\n\n**What it doesn't touch**\n\n- No writes outside `~/.claude/` and your chosen output path\n- No network requests — plugin install during apply delegates to Claude Code's own `/plugin install` mechanism\n- No telemetry, no analytics, nothing leaves your machine\n- Does not require `--dangerously-skip-permissions`\n\n**Reversibility**\n\nEvery file overwritten during `apply` is copied to `.bak` first. If something breaks, restore from the `.bak` files or re-apply the previous snapshot.\n\n## Uninstall\n\n```bash\n# Remove the plugin\n/plugin uninstall snapshot\n\n# (Optional) Remove the marketplace registration\n/plugin marketplace remove claude-snapshot\n```\n\nSnapshots you created (`*.tar.gz`) are plain files — delete them as you would any other file.\n\n## Roadmap\n\nThe 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.\n\n**Planned support**\n\n| Target | Config root | Status |\n|---|---|---|\n| Claude Code | `~/.claude/` | ✅ v0.2 (current) |\n| OpenAI Codex CLI | `~/.codex/` | 🚧 planned for v0.3 |\n| Cursor | `~/.cursor/` | 🚧 planned for v0.3 |\n\nThe 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`.\n\n**Shorter-term items** (not tool-expansion)\n\n- `--with-mcp` flag to write through `~/.claude.json` on apply (opt-in, with `.bak` of the full file)\n- Encrypted snapshot option for team sharing\n- Selective apply (pick subset of the snapshot contents)\n\n## Contributing\n\nIssues 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.\n\n## License\n\n[MIT](LICENSE)\n",
"bytes": 9778,
"sha": "3b2b16cead569a952804d97ffb03212deecc8f1ad63b8591342e956ec51a5559",
"repo_slug": "adhenawer/claude-snapshot",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_adhenawer_claude_snapshot_claude_snapsho_2598b5df/readme"
}