backup-claude

A Claude Code skill that copies the Claude Code and Claude Desktop setup into one zip file and restores that zip on a new Windows laptop. Written 2026-10-17. Source: github.com/az9713/claude-backup-skill.

9,215 MBzip size, last run

104,778files in the zip

4items skipped (unreadable links)

D:\backups\claudedefault destination (external USB drive)

1. What the skill does

The skill has two PowerShell scripts in %USERPROFILE%\.claude\skills\backup-claude\scripts\.

backup.ps1 runs on the old laptop. It writes one zip and two receipt files to D:\backups\claude. It creates the folder if it does not exist.
restore.ps1 runs on the new laptop. It unpacks the zip and merges the files into the user profile and into %APPDATA%\Claude.

Each run writes three files with the same name stem, claude-backup-<COMPUTER>-<yyyyMMdd-HHmm>:

File	Content
`.zip`	The backup. The zip also holds `claude-backup-manifest.json`, which records the user name, profile path, computer name and date of the backup.
`.files.txt`	The receipt: one line for each file that the script wrote into the zip.
`.skipped.txt`	Each file or folder that an error kept out of the zip, with the Windows error text. If nothing failed, it says `No files skipped.`

Commands

# Back up (old laptop). Claude Code can stay open.
powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.claude\skills\backup-claude\scripts\backup.ps1"

# Restore (new laptop). Close Claude Code and Claude Desktop first. Use a plain PowerShell window.
powershell -ExecutionPolicy Bypass -File restore.ps1 -Zip D:\backups\claude\claude-backup-<COMPUTER>-20261017-2149.zip

If Windows gives the USB drive a letter other than D:, add -Dest <letter>:\backups\claude to the backup command. restore.ps1 is in the zip at .claude/skills/backup-claude/scripts/restore.ps1. Copy it out of the zip before you run it.

2. How the backup works

Make the destination folder. New-Item -ItemType Directory -Force creates D:\backups\claude and any missing parent folders.
Choose the sources. From %USERPROFILE%: .claude\, .claude.json and AGENTS.md. From %APPDATA%\Claude: a fixed list of 12 config files and session folders (section 4). The script ignores a source that does not exist.
Walk every folder. The script reads each folder itself. It does not use tar.exe (section 3). It does not go into the 8 excluded .claude folders and files (section 5).
Follow links. A symlink or a junction is copied as the real files that it points to. 69 skill folders are junctions: 66 into %USERPROFILE%\.agents\skills, 2 into %USERPROFILE%\.codex\skills, 1 into a folder under %USERPROFILE%. If a link points to its own parent folder, the script records it in .skipped.txt and does not follow it, because following it would repeat without end.
Read files that are in use. Each file is opened with share mode ReadWrite, Delete. Thus the script can also read the transcript that a running Claude Code session writes. Only a file that another program locks exclusively fails, and that failure goes into .skipped.txt.
Write the zip. The script uses the .NET System.IO.Compression.ZipArchive class with CompressionLevel.Fastest. It writes one entry for each file, keeps the file's last-write time, and stores non-ASCII names correctly.
Write the receipts. .files.txt and .skipped.txt are UTF-8 text files.
Check the finished zip. The script opens the zip again. It stops with an error if .claude/settings.json or .claude.json is missing. It warns if the number of entries in the zip is different from the number of lines in .files.txt.

3. Why the scripts do not use tar.exe

The first version used the Windows tar.exe (bsdtar 3.8.9). On 2026-10-17 it made a zip of 8,887 MB that was not complete. A comparison of that zip with the files on disk showed:

615 Claude Desktop files were missing, and 613 of them came from one Cowork session (local-agent-mode-sessions\<session-id>). One unreadable link (debug/latest) in that session gave the error Cannot stat: Invalid argument. After that error, tar did not copy the rest of that folder and gave no message about the missing files. Its only signal was exit code 1.
In a test, one locked file made tar leave out 3 other files in the same tree.
A file named 日本 ✓.txt made tar crash with exit code -1073741819 (access violation), and the zip was empty.

The .NET version adds files one at a time and records each failure. Thus each file is in .files.txt or in .skipped.txt, and no file can be lost without a record.

4. What is in the backup

Sizes are on disk before compression, measured on 2026-10-17.

Source	What it holds	Size
`.claude\projects\`	Session transcripts (`.jsonl`) for 455 project folders, and the `memory\` folder in 253 of them	8,367 MB
`.claude\skills-archive\`	Skills that you archived	1,796 MB
`.claude\plugins\`	`installed_plugins.json`, `known_marketplaces.json` (22 marketplaces), `blocklist.json`, and the plugin `cache`, `data` and `marketplaces` folders	506 MB
`.claude\security\`	Kept as found; the script makes no decision about its content	327 MB
`.claude\file-history\`	Checkpoints for rewind	201 MB
`.claude\skills\`	Your skills, plus the content of the 61 linked skill folders (8 more are in `skills-archive`)	44 MB + link targets
Rest of `.claude\`	`settings.json`, `CLAUDE.md`, `keybindings.json`, `mcp.json`, `.credentials.json`, `history.jsonl` (5.8 MB), `statusline-command.sh`, the hook scripts, `agents\`, `commands\`, `hooks\`, `coach\`, `jobs\`, `plans\`, `tasks\`, `teams\`, `scheduled-tasks\`, `backups\` and the other small folders	about 100 MB
`%USERPROFILE%\.claude.json`	9 user-scope MCP servers, settings for 987 project paths, account data	4 MB
`%USERPROFILE%\AGENTS.md`	Your instructions shared across agents	7 MB
`%APPDATA%\Claude\local-agent-mode-sessions\`	Cowork sessions	3,311 MB
`%APPDATA%\Claude\Claude Extensions\` and `Claude Extensions Settings\`	Desktop extensions and their settings	114 MB
`%APPDATA%\Claude\claude-code-sessions\`	Claude Code sessions started from Desktop	19 MB
8 Desktop config files	`claude_desktop_config.json` (MCP servers, `coworkUserFilesPath`, preferences), `developer_settings.json`, `ccd-session-presets.json`, `ssh_configs.json`, `git-worktrees.json`, `mcp-user-tool-toggles.json`, `extensions-installations.json`, `cowork-enabled-cli-ops.json`	under 1 MB

The sources have at least 14,767 MB on disk, and the zip is 9,215 MB.

5. What is not in the backup, and why

Item	Size	Reason
`.claude\cache`, `debug`, `paste-cache`, `telemetry`, `statsig`	20.6 MB	Caches, debug logs and usage data. Claude Code makes them again.
`.claude\shell-snapshots`, `session-env`, `daemon.lock`	54.1 MB	State for running processes on this machine. They have no use after a restart.
`%APPDATA%\Claude\vm_bundles`	10,457 MB	The VM image for Cowork. Desktop downloads it again.
`%APPDATA%\Claude\claude-code`, `claude-code-vm`	510 MB	Program files that Desktop installs.
`Cache`, `Code Cache`, `GPUCache`, `GrShaderCache`, `ShaderCache`, `Dawn*`, `logs`, `Crashpad`, `sentry`	about 520 MB	Browser-engine caches and logs. Desktop makes them again.
`config.json`, `Local Storage`, `IndexedDB`, `Network`, `Partitions`, `Session Storage`, `Local State`	about 48 MB	Desktop login and browser state. Windows encrypts it for this user on this machine (DPAPI), so it cannot work on another laptop. You log in to Desktop again.
16 old Desktop configs (`claude_desktop_config.json.03242025.a` … `claude_desktop_config_weather_only.json`)	under 1 MB	Your old copies of the config file. Only the current file is used.
`%USERPROFILE%\.claude.json.backup`	2 MB	Claude Code makes this copy of `.claude.json` automatically. The zip has the real file.
`%LOCALAPPDATA%\claude-cli-nodejs`	176 MB	MCP logs.
4 `debug/latest` links in one Cowork session	—	Windows cannot open them (`The file cannot be accessed by the system`). They point to the newest debug log and are listed in `.skipped.txt`.

6. Why these files are enough to recreate the setup

Claude Code and Claude Desktop do not keep their setup in the Windows registry or in a cloud copy. They read it from a fixed set of files in the user profile. If those files are on the new laptop at the same paths, the new installation reads the same setup. The table connects each part of the setup to its file and shows that each file is in the zip.

Part of the setup	Where Claude reads it	In zip
Settings: model, permissions, hooks, status line, enabled plugins, extra marketplaces, env, theme, `cleanupPeriodDays`	`.claude\settings.json`	yes
Global instructions	`.claude\CLAUDE.md`, `%USERPROFILE%\AGENTS.md`	yes
Key bindings, status line script, hook scripts	`.claude\keybindings.json`, `.claude\statusline-command.sh`, `.claude\*.ps1`, `.claude\hooks\`	yes
Skills, agents, commands	`.claude\skills\`, `.claude\agents\`, `.claude\commands\`	yes, with links followed
Plugins and marketplaces	`.claude\plugins\installed_plugins.json`, `known_marketplaces.json`, `cache\`, `marketplaces\`, `data\`	yes
User MCP servers, per-project settings, account	`%USERPROFILE%\.claude.json`, `.claude\mcp.json`	yes
Login token	`.claude\.credentials.json`	yes
Auto memory	`.claude\projects\<project>\memory\`	yes
Sessions for `--resume`, prompt history, rewind checkpoints	`.claude\projects\*.jsonl`, `history.jsonl`, `file-history\`	yes
Desktop MCP servers and preferences	`%APPDATA%\Claude\claude_desktop_config.json`, `developer_settings.json`	yes
Desktop extensions, Desktop and Cowork sessions	`Claude Extensions\`, `claude-code-sessions\`, `local-agent-mode-sessions\`	yes
Desktop login	`config.json` and the browser state	no; log in again
Program files (Claude Code, Desktop, Cowork VM)	The installers	no; install first

Each item in section 5 belongs to one of three groups: (1) the app makes it again, (2) the app or its installer downloads it again, or (3) Windows encrypts it to the old machine, so a copy would not work. None of the three groups holds a setting that you made.

Evidence. In a test, I set USERPROFILE and APPDATA to test folders and did a full backup and restore. The test checked these points:

excluded folders were left out
a junction to a skill was followed
a file in use by another program was read
a non-ASCII file name (日本 ✓ café.jsonl) came back with the correct content
the restore copied the new laptop's existing settings.json aside before it replaced the file

The only absolute file path in your settings.json is ~/.claude/statusline-command.sh, and that file is in the zip.

7. Conditions and limits

The argument in section 6 is true only when the conditions below are true. Read them before you start a migration.

MCP servers need their programs

The zip holds each MCP server's configuration, but not the program that the configuration starts. 8 of the 9 user MCP servers in .claude.json use a local command, and you must install that command on the new laptop:

1 command-line tool installed with Bun, in %USERPROFILE%\.bun\bin
1 Python virtual environment inside a project folder under %USERPROFILE%\Downloads
1 executable that a desktop app installs under %LOCALAPPDATA%\Programs
1 command-line tool in %USERPROFILE%\.local\bin
2 Node.js scripts: one in a global npm package under %APPDATA%\npm\node_modules, one in a project folder under %USERPROFILE%\Downloads
2 servers started through npx and uvx, which need Node.js and uv

The 9th server is an HTTP server and needs nothing installed. The one MCP server in the Desktop config uses the same Node.js script as one of the Claude Code servers.

3 plugin marketplaces are local folders

19 of the 22 marketplaces come from GitHub, and Claude Code downloads them again. The other 3 point to project folders under %USERPROFILE%\Downloads, which are not in the zip. The zip has the cached copy of those plugins in .claude\plugins\cache\. To update or reinstall those plugins, you need the source folders.

Same user path

The session folder names (.claude\projects\C--Users-<user>-…), the 987 project paths in .claude.json, and the MCP paths above all contain the old profile path C:\Users\<user>. If the new laptop's profile path is different, restore.ps1 shows a warning, and you must change these paths yourself.

Not in the zip

Project-level .claude\, CLAUDE.md, .mcp.json and HANDOFF.md. They are in each project folder.
2 personal knowledge folders in %USERPROFILE% that are not part of Claude (2,898 MB, and one git repository).
claude.ai web chats. They are on Anthropic's servers. To get a copy, use claude.ai → Settings → Privacy → Export data.

Other points

Linked skills come back as plain folders. After a restore, the 69 linked skill folders are normal folders and no longer junctions into .agents\skills. Tools that update .agents\skills (for example npx skills) do not update them.
The zip is not encrypted. It holds .credentials.json and the API keys in the MCP env blocks. Keep it on the local USB drive. Do not put it in cloud storage.
The backup holds only what exists on the day of the run. Your cleanupPeriodDays is 10000, so Claude Code does not delete old transcripts within that time.
No restore on a second laptop has been done. The proof in section 6 comes from the file mapping and the test-folder round trip. To prove it fully, restore the zip into a second Windows user account or onto the new laptop, and start Claude Code there. A second account also has a different user path, so that test also shows the path warning.

8. How the restore works

Check that Claude is closed. The script stops if any process named claude runs. It only checks for the process. It never stops a process.
Unpack the zip. The .NET ZipFile.ExtractToDirectory unpacks the zip to %TEMP%\claude-restore-<stamp>. If the unpack fails, the script stops before it changes any file.
Compare the user path. The script reads claude-backup-manifest.json. If the old profile path is different from the new one, it shows a warning.
Copy existing items aside. Before it replaces an item, the script copies the current version to %USERPROFILE%\claude-pre-restore-<stamp>\.
Merge the backup. robocopy /E copies the folders, and Copy-Item copies the single files. Files with the same name are replaced. Files that exist only on the new laptop stay.
Clean up. The script deletes the temporary folder. Then start Claude Code. If it asks you to log in, run /login.

9. Run history, 2026-10-17

Zip	Size	Result
`claude-backup-<COMPUTER>-20261017-2115.zip`	8,887 MB	Not complete: tar left out 615 files and gave no message about them.
`claude-backup-<COMPUTER>-20261017-2136.zip`	9,209 MB	Not complete: the 69 linked skill folders are missing.
`claude-backup-<COMPUTER>-20261017-2149.zip`	9,215 MB	Use this one. 104,778 files, 4 unreadable links skipped, all checks passed.

The first two zips (18,096 MB together) were deleted after the third run passed its checks, so only the good backup remains on D:\backups\claude.