Transfer Claude Code Settings to Another Computer

Transfer Claude Code configuration by inventorying the source, backing up both computers, and merging only reviewed settings, instructions, skills, agents, rules, and secret-free project MCP definitions. Sign in again and recreate local secrets on the destination. Do not copy chat history, OAuth state, caches, or the whole ~/.claude.json file.

What you can transfer

Review these locations rather than copying them blindly:

• User settings: ~/.claude/settings.json
• User instructions: ~/.claude/CLAUDE.md
• User skills, agents, and rules: ~/.claude/skills/, ~/.claude/agents/, and ~/.claude/rules/
• Shared project configuration: CLAUDE.md, .claude/settings.json, .claude/skills/, .claude/agents/, and .claude/rules/
• Project MCP definitions in .mcp.json, after replacing sensitive values and machine-specific paths

Project files usually belong in the project’s version-control workflow. Personal user files should travel through an encrypted transfer method you control.

What not to copy

Do not transfer accounts, authentication tokens, chat or session history, caches, logs, trust decisions, or unrelated per-project state. Avoid copying ~/.claude.json wholesale because it combines MCP entries with authentication and local application state. Do not copy .claude/settings.local.json unless you have reviewed every machine-specific override and intentionally recreated it.

1. Back up source and destination

Quit Claude Code on both computers. On macOS or Linux, create dated backups before editing:

cp -a ~/.claude ~/.claude.backup-before-transfer
cp -a ~/.claude.json ~/.claude.json.backup-before-transfer

Run the equivalent copy in your file manager or PowerShell on Windows. If the destination already has Claude Code configuration, back it up too. Never replace a destination directory without a recovery copy.

2. Build a reviewed transfer folder

Create an empty temporary folder outside any public repository. Copy only the user files and directories you actually need. Open every JSON and Markdown file and remove credentials, tokens, private filesystem paths, and settings that should remain source-machine-only.

For a shared .mcp.json, replace secrets with environment-variable references:

{
  "mcpServers": {
    "team-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer ${TEAM_API_TOKEN}" }
    }
  }
}

Set TEAM_API_TOKEN separately on the destination. Do not include a real token in the transfer folder.

3. Merge on the destination

Install and launch the current Claude Code release once, then quit it so the destination folders exist. Compare the reviewed files with the destination versions. Merge JSON keys and Markdown instructions deliberately; do not overwrite working destination configuration with the entire source directory.

Copy project-scoped files through the repository when they are intended for collaborators. Keep user-scoped files under the destination user’s home directory. Recreate machine-specific executable paths and local settings for that computer.

4. Reauthenticate and verify

Start Claude Code and sign in normally. Run /status to confirm which settings sources loaded. Check /mcp and approve any reviewed project-scoped servers, then exercise each transferred skill or agent in a disposable project. Confirm that:

1. The expected settings sources appear.
2. User and project instructions load in the intended scope.
3. Skills can be invoked and their supporting files resolve.
4. MCP servers connect only after destination secrets are configured.
5. Existing destination-only settings still work.

Troubleshooting

• If settings do not load, validate the JSON and check /status for the rejected source.
• If an MCP server fails, inspect it with claude mcp get <name>, correct destination paths, and recreate its secret or OAuth login.
• If a skill is missing, confirm the folder contains SKILL.md under ~/.claude/skills/<name>/ or <project>/.claude/skills/<name>/.
• If destination behavior changed unexpectedly, restore the backup and repeat the transfer one file at a time.

Official sources

These instructions were checked against the following vendor documentation.

• Anthropic: Claude Code settings
• Anthropic: Explore the .claude directory
• Anthropic: Connect Claude Code to tools via MCP