How to Transfer Your Claude Code Environment to a New Machine
Overview
When switching to a new computer, you’ll want to bring your Claude Code settings, memory, and project context with you. Here’s what to back up and how to restore it.
What to Back Up
Claude Code stores everything under ~/.claude/. Not all of it matters — here’s what to keep:
Essential
| Path | Description |
|---|---|
~/.claude/CLAUDE.md | Your global instructions that apply to all projects |
~/.claude/settings.json | Permissions, allowed/denied tools, and other settings |
~/.claude/projects/ | Per-project memory, instructions, and context |
Nice to Have
| Path | Description |
|---|---|
~/.claude/history.jsonl | Conversation history |
Skip These
| Path | Description |
|---|---|
~/.claude/cache/ | Regenerated automatically |
~/.claude/debug/ | Debug logs |
~/.claude/session-env/ | Ephemeral session data |
~/.claude/shell-snapshots/ | Shell state snapshots |
~/.claude/todos/ | Task lists from past sessions |
~/.claude/statsig/ | Analytics cache |
~/.claude/telemetry/ | Telemetry data |
~/.claude/file-history/ | File edit history |
~/.claude/backups/ | Auto-generated backups |
~/.claude/plans/ | Session plans (ephemeral) |
Project-Level Files
Claude Code also reads CLAUDE.md files from your project directories. If your projects are in git, these are already backed up. They live at the root of each repo and contain project-specific instructions.
Transfer Steps
1. On your old machine
# Copy the essential files
tar czf claude-code-backup.tar.gz \
~/.claude/CLAUDE.md \
~/.claude/settings.json \
~/.claude/projects/ \
~/.claude/history.jsonl2. On your new machine
# Install Claude Code
npm install -g @anthropic-ai/claude-code
# Restore your backup
tar xzf claude-code-backup.tar.gz -C /
# Verify
cat ~/.claude/CLAUDE.md
cat ~/.claude/settings.json
ls ~/.claude/projects/3. Verify it works
Start Claude Code in any project directory. It should pick up your global instructions and project-specific memory automatically.
cd your-project/
claudeHow Memory Works
Claude Code has a file-based memory system stored in ~/.claude/projects/. Each project gets its own directory (named after the project path) containing:
MEMORY.md— an index of all memory files- Individual memory files — user preferences, project context, feedback, and references
These memories persist across conversations and help Claude Code remember your preferences, project decisions, and past feedback. Transferring the projects/ directory ensures Claude Code remembers everything about how you work.
Tips
- Don’t back up everything — most of
~/.claude/is transient data that gets regenerated. Backing up only the essentials keeps things clean. - Check your settings — after restoring, review
settings.jsonto make sure paths and permissions still make sense on the new machine. - Project paths matter — the
projects/directory uses your project paths as directory names. If your projects live at different paths on the new machine, you may need to rename the directories under~/.claude/projects/.
