A new Windows machine should be fun. Fresh hardware, clean installs, a blank slate. But if you use Claude Code every day, that fresh start can turn into hours of setup. After all, your MCP servers, slash commands, plugins, and access rules all live in various config files. So if you miss just one file, you will spend days clicking “Allow” on each tool prompt.
This Claude Code Windows migration guide covers the full process. It walks you through backup, cleanup, restore, and testing. I wrote it after a real move in April 2026 with Claude Code v2.1.89+ on Windows. The goal is simple: land on your new machine with it all working the same way. Same servers. Same plugins. Zero re-setup.
Table of Contents
What You Need on the New Machine
Before you copy anything, set up these tools on your new machine. If you skip one, you will hit odd errors later.
- Node.js 18+: grab it from nodejs.org. While the native Claude Code installer does not need Node, your MCP servers might if they run via
npx.
- Claude Code: use the native installer from Anthropic. It auto-updates and needs no extras. You can also use
npm install -g @anthropic-ai/claude-code, but that method was marked as old in early 2026.
- GitHub CLI: run
winget install GitHub.cli. You need this if you use gh commands for pull requests, issues, or auth.
- uv (optional): only needed if you run Python-based MCP servers via
uvx. Just run winget install astral-sh.uv.
Here is a quick tip about uv: after you install it, close and reopen PowerShell. The setup updates your PATH, but the current shell will not see it. This tripped me up.
Phase 1: List and Backup (Old Machine)
In this phase, you note what you have and back up the right files. In my view, most issues come from skipping this step. You end up halfway through and then see that you missed a key file.
Step 1: Record Your Toolchain
First, open PowerShell on your old machine. Run these commands. Save the output since you will look at it many times later.
node --version
npm --version
npm list -g --depth=0
gh auth status
claude --version
Pay close attention to the npm list -g output. It tells you which packages to put back later. Also, gh auth status shows your token scopes. If any of your MCP servers use Python packages, then run pip list too. That said, most MCP servers run via npx or uvx and load on their own. So check the mcpServers block in .claude.json to see how yours work.
Step 2: Back Up the Global Config Folder
Next, copy the whole .claude folder from your user profile. On Windows, it lives at:
c:\Users\[USER]\.claude\
This folder is the heart of your Claude Code config. Here is what lives inside it and why each part matters.
First, settings.json holds your global settings, plugins, status line layout, and effort level. You must copy this. Then there is CLAUDE.md, which holds global rules for all your projects. Think of it as Claude Code’s brain. Both of these are key.
Next, the commands folder holds your custom slash commands. Each one is an .md file. In the same way, the agents folder stores your sub-agents as .md files. If you have built up a set of these, losing them would hurt. So back them up.
Last, the projects folder stores chat logs per project. You only need it if you use --resume to pick up old chats. And, the statsig folder is a cache that rebuilds on its own. Skip it. Also, .credentials.json stores auth tokens, but a fresh login is cleaner.
Step 3: Back Up Global MCP Server Config
This is the file people forget most. So copy .claude.json from your home folder root (not from inside .claude):
c:\Users\[USER]\.claude.json
It holds all your global MCP server setups. It also stores per-project config keyed by full path. The Claude Code docs go into more detail.
Security warning: Your MCP tokens sit in plain text in this file. So do not commit it to a repo or paste it in a chat. If you expose it by mistake, rotate those tokens right away.
Step 4: Back Up the ccstatusline Config
If you use ccstatusline for your terminal status bar, then the widget layout lives in a separate spot:
c:\Users\[USER]\.config\ccstatusline\settings.json
This file controls which widgets show up and in what order: model name, effort, context bar, usage, folder, and git branch. Without it, ccstatusline falls back to defaults. Then you have to redo it all by hand.
Step 5: Back Up Per-Project Local Settings
For each project you work in, also look for files that are .gitignored. These will not come with a git clone.
In fact, the file lost most often is .claude\settings.local.json inside each project. It stores your per-project access rules. These rules let Claude Code run dotnet build, gh pr, and more without asking each time. Without it, Claude Code prompts you for each tool again. That gets old fast.
Also watch for .claude\settings.json (shared project settings), .claude\commands\ and .claude\agents\ (project-level commands and agents), CLAUDE.md (project notes), and .mcp.json (project MCP servers). Most come with git clone. But the local settings file does not.
Step 6: Back Up Shell Env Vars
Then open your PowerShell profile with notepad $PROFILE. Copy any lines that set Claude-related env vars. Look for ANTHROPIC_API_KEY, GITHUB_TOKEN, cloud flags, and any MCP tokens.
On top of that, check your system-level env vars through Settings → System → About → Advanced system settings → Env Vars. Some devs set API keys at the system level, so it is worth checking both spots.
Phase 2: Clean and Prepare
Before you restore files, take a few minutes to tidy your config. While this step is not required, I suggest it. Old entries and stale paths cause odd errors, so cleaning them now saves time later.
Step 7: Clean Up .claude.json Before Restoring
Open your backed-up .claude.json file and look for entries that need a fix.
First, fix or remove stale project paths. The "projects" section holds entries keyed by full path. Each one stores cached trust data. If a project no longer exists, just delete it. If your repos will live at a new path, then update the keys. Not sure? Just delete the whole "projects" block. Claude Code rebuilds it on its own.
After that, remove stale worktree entries. Look under "githubRepoPaths" and "projects" for paths to .claude-worktrees. Since these are temp folders, old ones are safe to cut. Entries like this can go:
"c:\\Users\\[USER]\\.claude-worktrees\\myproject\\inspiring-rubin"
You may also see the same path listed twice. One uses backslashes, the other forward slashes. This is normal on Windows. Just leave both or clean up the duplicate.
Step 8: Clean Up Per-Project settings.local.json
Next, go through each project’s settings.local.json. Remove one-off commands that will not match again. Cut entries with hardcoded commit hashes or entries that point to deleted files.
But keep the wildcard patterns you rely on. These save you from constant prompts:
"Bash(dotnet build:*)",
"Bash(dotnet test:*)",
"Bash(gh pr:*)",
"Bash(grep:*)",
"Bash(git add:*)",
"WebSearch"
This cleanup cuts noise and stops Claude Code from trying to match stale entries.
Phase 3: Restore on the New Machine
At this point, your files are clean and your tools are set up. Now it is time to move it all to the new machine. This phase goes fast if you did the prep work in Phases 1 and 2.
Step 9: Restore Global Config
Copy your backed-up files to the same spots on the new machine:
- Copy the
.claude\ folder to c:\Users\[USER]\.claude\
- Then copy
.claude.json to c:\Users\[USER]\.claude.json
- Last, copy the ccstatusline config to
c:\Users\[USER]\.config\ccstatusline\settings.json
For the ccstatusline config, you may need to create the target folder first:
mkdir -Force "$env:USERPROFILE\.config\ccstatusline"
Step 10: Restore Shell Env Vars
Open your PowerShell profile with notepad $PROFILE. Then paste the env var lines from Step 6, save, and reload with . $PROFILE. After that, your API keys and tokens will be ready in each new session.
Step 11: Install Global npm Packages
Next, put back any global npm packages from your Step 1 list:
npm install -g dbmate
Here is a tip: many MCP tools use "command": "npx". So they load on their own at runtime. You only need to set up packages that showed up in your npm list -g output. To check, run npm list -g <package-name>.
Step 12: Authenticate
After that, log into Claude Code and the GitHub CLI:
# Claude Code
claude auth login
# GitHub CLI (match the scopes from your Step 1 output)
gh auth login --scopes gist,read:org,repo,workflow
Then check both:
claude auth status
gh auth status
I suggest skipping .credentials.json and just logging in fresh. This avoids stale token bugs. Plus, fresh tokens prove your accounts are linked to the new machine.
Step 13: Clone Repos and Restore Local Files
Now clone your repos with git clone. Then copy back any .gitignored files from Step 5 by hand. Most of all, restore the cleaned-up .claude\settings.local.json from Step 8. Without it, you lose all your access rules.
Step 14: Rotate Exposed Secrets
If your .claude.json was shared or exposed during the move, then rotate each token in it right away. Open the file. Find each token under mcpServers. Then go to each service’s account page and revoke the old one. After that, create a new token and update .claude.json.
Phase 4: Test Everything
Now the last phase: testing. Open PowerShell, go to one of your project folders, and start Claude Code:
cd c:\repos\myproject
claude
Then run through this checklist to make sure it all moved over:
- Status line: Check that your widgets show up at the bottom (model, effort, context bar, usage, current folder, git branch).
- Slash commands: Type
/ and check your custom commands are in the list.
- Agents: Run
/agents to see your custom sub-agents.
- Plugins: Confirm that your plugins are loaded and active.
- MCP servers: Test one of your MCP tools to make sure the server connects.
- Permissions: Run
/permissions to review your allow-list.
- Effort level: Confirm it shows your preferred level (for example,
high).
If any of these fail, see the gotchas list below. Most of the time, the fix is a missing file or a stale config entry.
Quick Reference: All Files to Copy
Here is each file and folder in the move, sorted by need. Use this as your checklist.
Critical (Always Copy)
c:\Users\[USER]\.claude.json ← Global MCP servers
c:\Users\[USER]\.claude\settings.json ← Global settings, plugins, status line, effort
c:\Users\[USER]\.claude\CLAUDE.md ← Global instructions
c:\Users\[USER]\.claude\commands\ ← Global slash commands
c:\Users\[USER]\.claude\agents\ ← Global sub-agents
c:\Users\[USER]\.config\ccstatusline\settings.json ← Status line widget layout
<each-project>\.claude\settings.local.json ← Per-project permissions (gitignored)
PowerShell $PROFILE ← Env vars
Copy If Present
c:\Users\[USER]\.claude\settings.local.json
<each-project>\.mcp.json (if not committed to Git)
Optional
c:\Users\[USER]\.claude\projects\ ← Session history (can be large)
c:\Users\[USER]\.claude\.credentials.json ← Or just re-auth fresh
Skip
c:\Users\[USER]\.claude\statsig\ ← Auto-regenerated
Common Gotchas Summary
During this move, I hit a few issues that were not clear at first. Here is a list so you can fix them fast.
- uvx not found after install: Your PATH is not refreshed in the current PowerShell session. Simply close and reopen PowerShell to fix it.
- MCP server fails to connect: This often means either
uv is not set up or your API token is stale. So install uv via winget and rotate the token if needed.
- Tool prompts keep showing: Most likely,
.claude\settings.local.json was not copied. Restore it from your backup since this file is .gitignored.
- Status line missing or showing defaults: In this case, the ccstatusline config file was not copied. Just restore
c:\Users\[USER]\.config\ccstatusline\settings.json from your backup.
- Project not found or trust dialog pops up: This happens when the full path changed. Either update the project keys in
.claude.json, or just let Claude Code rebuild them.
- Worktree entry errors: Stale
.claude-worktrees paths remain in the config. Just delete them, since worktrees are created on demand.
- API token exposed: If
.claude.json was shared or pasted during the move, then rotate each token in that file right away at each service’s account page.
- Global tool missing (like dbmate): Tools set up via
npm install -g do not come back on their own. So put them back from your Step 1 list.
- Duplicate project entries (backslash and forward-slash): This is normal on Windows and is harmless. But you can clean up the dupes if you like a tidy config file.
Other Option: Community Sync Tools
The manual steps in this guide give you full control. But if you switch machines often, a few tools from the dev world can help.
Memoir is a tool that backs up and restores your settings in two commands. It also remaps paths across platforms. Claude Sync takes a different route. It syncs your ~/.claude folder with encrypted cloud storage. And, if you use chezmoi for dotfiles, there is a simple recipe for storing your config in a private GitHub repo.
As of April 2026, there is no built-in sync command. These tools fill that gap. That said, none of them do the cleanup from Phase 2. So the manual review is still worth doing.
Related Articles
Have you moved Claude Code to a new Windows machine? Did you run into gotchas that I missed, or did you find a smoother way to handle the access rules? Drop a note below and let me know how it went.
The post Claude Code Windows Migration Guide: Move Your Entire Setup to a New Machine appeared first on Programming and Tech Blog.