Protect Your Agent Investment

~/.claude/ doesn't back itself up. Your hooks, permissions, and instructions deserve better.

Back up. Restore. Share across machines. One command each.

~/.claude/ ──▶ backup.sh ──▶ ~/.claude-backups/ ──▶ git, Dropbox, iCloud, USB stick, whatever
                                                         │
new machine ◀── restore.sh ◀─────────────────────────────┘

---

The Problem

You've spent hours tuning your Claude Code setup - hooks that enforce your workflow, permissions dialed in, global instructions that shape all of your sessions, plugins, and memory files. All of it lives in ~/.claude/.

But how often do you actually back it up? One bad plugin install, one accidental delete, one new laptop - and you're rebuilding from scratch.

What This Does

./backup.sh	Snapshots your entire ~/.claude/ config to a local folder
./restore.sh	Restores everything on a new machine (or after a mishap)
./setup.sh	Wires automatic backups every time a session ends

That's the whole thing. Three bash scripts with a bit of python for the JSON handling.

Quick Start

git clone https://github.com/rusty428/claude-code-config-backup.git
cd claude-code-config-backup

# Back up your current config
./backup.sh

# Your config is now in ~/.claude-backups/latest/

Want a timestamped snapshot instead?

./backup.sh --snapshot
# Creates ~/.claude-backups/2026-03-12_14-30-00/

Or back up to a custom location:

./backup.sh --target ~/Dropbox/claude-backup

Automatic Backups

Run the setup script and answer two questions:

./setup.sh

It will ask:

1. Where to store backups (default: ~/.claude-backups/)
2. How - overwrite a single copy each time, or keep timestamped snapshots

This adds a SessionEnd hook to your settings.json. Every time a Claude Code session ends, your config is backed up automatically. Idempotent - safe to run more than once.

# To remove later
./setup.sh --remove

What Gets Backed Up

File	What It Is
settings.json	Hooks, permissions, plugins, env vars, model preferences
settings.local.json	Local permission overrides
CLAUDE.md	Global instructions - your rules for every session
scripts/	Hook scripts (PreToolUse, SessionEnd, Notification, etc.)
memory/	Cross-project memory files
plugins/*.json	Plugin and marketplace manifests

Excluded: Session history, debug logs, cache, tasks, todos. These are ephemeral - Claude Code regenerates them.

Restoring

On a new machine, or just rolling back a bad change:

# Restore from latest
./restore.sh

# See available snapshots
./restore.sh --list

# Restore a specific snapshot
./restore.sh --snapshot 2026-03-12_14-30-00

# Restore from a custom location
./restore.sh --source ~/Dropbox/claude-backup

This recreates ~/.claude/, copies everything back, and offers to reinstall your plugins from the manifest.

Why Portability Matters

You have a work laptop and a personal machine. You want the same hooks, the same permissions, the same instructions on both. Without this, you're manually keeping two configs in sync.

1. ./backup.sh on machine A
2. Sync ~/.claude-backups/ however you want - git, Dropbox, iCloud, airdrop, carrier pigeon
3. ./restore.sh on machine B

Both machines now behave identically.

Example Configs

The examples/ directory includes annotated samples:

• settings.json - Tuned config with hooks, permissions, and notification sounds
• CLAUDE.md - Example global instructions
• block-cd-in-bash.sh - A PreToolUse hook that enforces the cwd parameter

These aren't installed by default - they're references to learn from and adapt.

Repo Structure

claude-code-config-backup/
├── backup.sh              # Snapshot ~/.claude/ to a backup directory
├── restore.sh             # Restore from backup to ~/.claude/
├── setup.sh               # Wire automatic backups via SessionEnd hook
├── examples/
│   ├── settings.json      # Annotated example config
│   ├── CLAUDE.md          # Example global instructions
│   └── block-cd-in-bash.sh  # Example hook script
├── .gitignore
└── README.md

Requirements

• macOS or Linux
• Claude Code CLI installed
• python3 (for JSON handling in setup.sh and restore.sh)
• bash 3.2+

Note: This is for the Claude Code CLI (~/.claude/), not the Claude Desktop app. Claude Desktop stores its configuration separately in ~/Library/Application Support/Claude/ on macOS.

Disclaimer

This tool copies files from your ~/.claude/ directory. It does not modify your Claude Code installation or communicate with any external service. That said, your configuration may contain sensitive data (API keys, environment variables, tokens). Review your backup contents before sharing or pushing to a public repo. Use at your own risk.

License

MIT - see LICENSE for details.