Back Up Claude Code Settings, Projects & Sessions
This guide shows you how to back up your Claude Code configuration, project-specific settings, and conversation history so you can restore them on a new machine or after a reinstall. You’ll copy a few files and folders from your home directory and from each project, then verify the backup works. No special tools are required—just a terminal and a destination like an external drive or cloud folder.
What You’ll Need
- Terminal access (Command Prompt or PowerShell on Windows, Terminal on macOS/Linux)
- Write access to your home directory and the projects you use with Claude Code
- A backup destination: external drive, USB stick, or a cloud-synced folder (e.g., Dropbox, Google Drive)
- Claude Code installed (to verify the backup later)
Step-by-Step
- Close Claude Code. Exit any running sessions so files are not being written while you copy them.
- Identify your home directory. In your terminal, run
echo $HOME(macOS/Linux) orecho %USERPROFILE%(Windows). Note the path—it’s usually/Users/yournameorC:\Users\yourname. - Locate the main settings directory. Claude Code stores global settings in a hidden folder called
.claudeinside your home directory. On macOS/Linux it’s~/.claude; on Windows it’s%USERPROFILE%\.claude. - Copy the global settings folder. Copy the entire
.claudefolder to your backup location. For example, on macOS/Linux:cp -r ~/.claude /path/to/backup/claude-backup/
On Windows (PowerShell):
Copy-Item -Recurse $HOME\.claude C:\backup\claude-backup\
This folder contains your authentication credentials, global configuration (like model preferences), and any custom slash commands or agents you’ve defined.
- Back up project-specific settings. For each project where you use Claude Code, look for a
.claudefolder inside that project’s root directory. Copy it to a subfolder in your backup, naming it after the project. For example:cp -r /path/to/myproject/.claude /backup/claude-projects/myproject/
These folders contain project-specific CLAUDE.md files, custom commands, and settings that override global ones.
- Back up session history. Claude Code stores session transcripts and conversation history in the
~/.claude/projectsdirectory (inside the global.claudefolder). If you already copied the whole.claudefolder, this is included. If you only want sessions, copy just that subfolder:cp -r ~/.claude/projects /backup/claude-sessions/
Each project has a subfolder named after the encoded project path, containing JSON files for each session.
- Check for environment variables. If you use environment variables to configure Claude Code (e.g.,
ANTHROPIC_API_KEY,CLAUDE_CODE_SETTINGS), note them down or export them to a file. Runenv | grep -i claude(macOS/Linux) orset | findstr /i claude(Windows) to see them. - Verify the backup. Navigate to your backup location and confirm the
.claudefolder and any project folders are present. Check that session files are not empty (they should be JSON files with content). - Optional: Compress the backup. Create a single archive for easy transfer. On macOS/Linux:
tar -czf claude-backup.tar.gz /backup/claude-backup/. On Windows: useCompress-Archivein PowerShell.
Common Mistakes
- Forgetting hidden files. The
.claudefolder is hidden by default. In file managers, enable “Show hidden files” or use the terminal to avoid missing it. - Copying only some files. If you copy only
settings.jsonbut not theprojectssubfolder, you lose session history. Copy the whole.claudefolder. - Backing up while Claude Code is running. This can lead to corrupted or incomplete files. Always exit first.
- Not checking the backup. A backup that is empty or missing files is useless. Always verify the contents before relying on it.
- Storing backups only on the same machine. If the hard drive fails, the backup fails too. Use an external drive or cloud service.
Tips
- Schedule regular backups—weekly or before major updates—to avoid losing recent sessions.
- Use version control for your
CLAUDE.mdfiles if you want to track changes over time. - Keep a copy of your environment variables in a plain text file (but be careful with secrets—store them in a password manager if possible).
- If you use multiple machines, consider syncing your
.claudefolder with a cloud service, but be aware of security implications since it contains API keys. - Test restoring your backup on a non-critical machine once to ensure the process works.
Troubleshooting
- Backup folder not found. If
~/.claudedoesn’t exist, you may not have used Claude Code yet, or it’s installed in a different location. Check withwhich claudeto confirm the installation. - Permission denied when copying. Use
sudoon macOS/Linux if needed, but be careful—it may change file ownership. Better to ensure your user owns the directory. - Session files are empty or corrupted. This often happens if you copied while Claude Code was running. Close all sessions and try again.
- Restore doesn’t work. After restoring, run
claudeand check if your settings are applied. If not, verify the folder structure—the.claudefolder must be in your home directory, not nested inside another folder. - Backup is too large. Session files can accumulate. You can delete old session files before backing up, or exclude them if you don’t need history.
Frequently Asked Questions
- Where does Claude Code store its settings?
Global settings are in~/.claude(or%USERPROFILE%\.claudeon Windows). Project-specific settings are in a.claudefolder within each project directory. - Can I back up just my conversations?
Yes, copy the~/.claude/projectsfolder. It contains JSON files for each session, organized by project. - Do I need to back up my API key?
Your API key is stored in the.claudefolder (in credentials). Backing it up is convenient, but be aware it’s a secret—store the backup securely. - Will restoring the backup overwrite my current settings?
Yes, if you replace the.claudefolder, it will overwrite existing settings. To merge, manually copy specific files instead. - Can I use cloud sync for my Claude Code folder?
Yes, but be cautious: syncing live while Claude Code is running may cause conflicts. Sync only when the app is closed. - How do I restore the backup on a new machine?
Copy the.claudefolder back to your home directory, and copy any project.claudefolders back into their respective projects. Then runclaudeto verify.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.