ThisCalculator

Everyday

Back Up Claude Code Settings, Projects & Sessions

Updated · Standard formula, shown below

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

  1. Close Claude Code. Exit any running sessions so files are not being written while you copy them.
  2. Identify your home directory. In your terminal, run echo $HOME (macOS/Linux) or echo %USERPROFILE% (Windows). Note the path—it’s usually /Users/yourname or C:\Users\yourname.
  3. Locate the main settings directory. Claude Code stores global settings in a hidden folder called .claude inside your home directory. On macOS/Linux it’s ~/.claude; on Windows it’s %USERPROFILE%\.claude.
  4. Copy the global settings folder. Copy the entire .claude folder 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.

  5. Back up project-specific settings. For each project where you use Claude Code, look for a .claude folder 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.

  6. Back up session history. Claude Code stores session transcripts and conversation history in the ~/.claude/projects directory (inside the global .claude folder). If you already copied the whole .claude folder, 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.

  7. 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. Run env | grep -i claude (macOS/Linux) or set | findstr /i claude (Windows) to see them.
  8. Verify the backup. Navigate to your backup location and confirm the .claude folder and any project folders are present. Check that session files are not empty (they should be JSON files with content).
  9. 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: use Compress-Archive in PowerShell.

Common Mistakes

  • Forgetting hidden files. The .claude folder 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.json but not the projects subfolder, you lose session history. Copy the whole .claude folder.
  • 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.md files 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 .claude folder 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 ~/.claude doesn’t exist, you may not have used Claude Code yet, or it’s installed in a different location. Check with which claude to confirm the installation.
  • Permission denied when copying. Use sudo on 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 claude and check if your settings are applied. If not, verify the folder structure—the .claude folder 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

  1. Where does Claude Code store its settings?
    Global settings are in ~/.claude (or %USERPROFILE%\.claude on Windows). Project-specific settings are in a .claude folder within each project directory.
  2. Can I back up just my conversations?
    Yes, copy the ~/.claude/projects folder. It contains JSON files for each session, organized by project.
  3. Do I need to back up my API key?
    Your API key is stored in the .claude folder (in credentials). Backing it up is convenient, but be aware it’s a secret—store the backup securely.
  4. Will restoring the backup overwrite my current settings?
    Yes, if you replace the .claude folder, it will overwrite existing settings. To merge, manually copy specific files instead.
  5. 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.
  6. How do I restore the backup on a new machine?
    Copy the .claude folder back to your home directory, and copy any project .claude folders back into their respective projects. Then run claude to verify.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.