{"id":50084224,"url":"https://github.com/adhenawer/claude-snapshot","last_synced_at":"2026-05-29T09:00:27.535Z","repository":{"id":351699436,"uuid":"1212105730","full_name":"adhenawer/claude-snapshot","owner":"adhenawer","description":"Portable Claude Code setup snapshots — export, diff, and apply your config across machines","archived":false,"fork":false,"pushed_at":"2026-04-16T04:54:19.000Z","size":280,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-16T06:34:01.406Z","etag":null,"topics":["claude-code","claude-code-plugin","cli","config-sync","developer-tools","dotfiles","snapshot"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adhenawer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-16T04:14:03.000Z","updated_at":"2026-04-16T04:54:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/adhenawer/claude-snapshot","commit_stats":null,"previous_names":["adhenawer/claude-snapshot"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/adhenawer/claude-snapshot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adhenawer%2Fclaude-snapshot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adhenawer%2Fclaude-snapshot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adhenawer%2Fclaude-snapshot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adhenawer%2Fclaude-snapshot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adhenawer","download_url":"https://codeload.github.com/adhenawer/claude-snapshot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adhenawer%2Fclaude-snapshot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33644313,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","claude-code-plugin","cli","config-sync","developer-tools","dotfiles","snapshot"],"created_at":"2026-05-22T18:00:36.857Z","updated_at":"2026-05-29T09:00:27.526Z","avatar_url":"https://github.com/adhenawer.png","language":"JavaScript","funding_links":[],"categories":["Plugins","Agent Infrastructure"],"sub_categories":["All Plugins","Configuration \u0026 Context Management"],"readme":"\u003cdiv align=\"center\"\u003e\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[![CI](https://github.com/adhenawer/claude-snapshot/actions/workflows/test.yml/badge.svg)](https://github.com/adhenawer/claude-snapshot/actions/workflows/test.yml)\n[![Tests](https://img.shields.io/badge/tests-57%20passing-brightgreen)](https://github.com/adhenawer/claude-snapshot/actions/workflows/test.yml)\n[![Last commit](https://img.shields.io/github/last-commit/adhenawer/claude-snapshot)](https://github.com/adhenawer/claude-snapshot/commits/main)\n![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-D97757.svg)](https://docs.anthropic.com/en/docs/claude-code)\n[![Node.js](https://img.shields.io/badge/node-%E2%89%A518-339933.svg?logo=node.js\u0026logoColor=white)](https://nodejs.org/)\n\n![demo](demo.gif)\n\n\u003c/div\u003e\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 `\u003cfile\u003e.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 \u003cpath\u003e\nnpx -y claude-snapshot diff    \u003cpath\u003e\nnpx -y claude-snapshot apply   \u003cpath\u003e\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 \u003cpath\u003e` | Preview snapshot contents without extracting |\n| `/snapshot:diff \u003cpath\u003e` | Compare a snapshot against your current setup |\n| `/snapshot:apply \u003cpath\u003e` | 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\u003cbr/\u003e~/.claude/] --\u003e|/snapshot:export| PKG[claude-snapshot.tar.gz]\n  PKG --\u003e|/snapshot:inspect| SUM[manifest summary]\n  PKG --\u003e|/snapshot:diff| DIFF[diff vs current]\n  PKG --\u003e|/snapshot:apply| APP[backup → write → install]\n  APP --\u003e DST[Machine B\u003cbr/\u003e~/.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 `\u003cfile\u003e.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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadhenawer%2Fclaude-snapshot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadhenawer%2Fclaude-snapshot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadhenawer%2Fclaude-snapshot/lists"}