claude-backup

Every debugging session. Every architecture decision. Every prompt you spent an hour crafting. Gone.

WhatsApp keeps your messages forever. Telegram keeps them forever. Discord keeps them forever. Claude Code — the tool you pay $20–200/mo for — gives you 30 days.

npx claude-backup

What You're Losing

Claude Code stores everything in ~/.claude/ — your settings, custom agents, hooks, skills, and every conversation you've ever had. Sessions older than 30 days? Silently deleted.

Each session is:

• A debugging journal — the exact steps that fixed that impossible bug
• An architecture record — why you chose that pattern, with the AI's reasoning
• A prompt library — the carefully worded instructions that actually worked
• A learning log — mistakes, corrections, breakthroughs, all timestamped

You can't Google your own Claude sessions. Once they're gone, they're gone.

How It Works

npx claude-backup

Interactive setup:

1. Checks requirements (git, gzip, python3)
2. Creates a private GitHub repo (or local-only if you prefer)
3. Backs up your config and all sessions (gzipped)
4. Sets up automatic backups (configurable: daily, 6h, hourly)

That's it. Run it once, forget about it.

Get Your Sessions Back

Browse and restore any session from your backups:

# List all backed-up sessions
claude-backup restore --list

# Show the last 5 sessions
claude-backup restore --last 5

# Filter by date
claude-backup restore --date 2026-02-27

# Filter by project
claude-backup restore --project myproject

# Restore a specific session
claude-backup restore <uuid>

The session index is auto-generated on every sync and rebuilt from the *.jsonl.gz files — you never need to manage it manually.

What Gets Saved

Config profile — settings, CLAUDE.md, agents, hooks, skills, rules. Lightweight (< 100 KB), portable between machines.

Sessions archive — all chat history, compressed with gzip. Your entire conversation history, safe in a private repo.

Machine Migration

Your config took hours to perfect. Move it in seconds.

# Old machine
claude-backup export-config
# => ~/claude-config-2026-02-25.tar.gz (47 KB)

# Transfer via AirDrop, USB, email, etc.

# New machine
npx claude-backup import-config claude-config-2026-02-25.tar.gz

Plugins are not included in the export (they are re-downloaded on first launch). Only the plugin manifest in settings.json is backed up.

Backend Modes

Choose where your backups live:

# GitHub private repo (default if gh is installed)
npx claude-backup

# Local only — no remote, no GitHub needed
npx claude-backup --local

# Custom git remote
npx claude-backup --backend git
claude-backup backend set git --remote git@myserver:backups.git

Switch backends anytime — even after setup:

claude-backup backend set github   # switch to GitHub
claude-backup backend set local    # switch to local-only
claude-backup backend set git --remote <url>  # custom remote

Backups go to ~/.claude-backup/ as a local git repo. Everything works the same — sync, restore, peek, export/import.

Backup Schedule

Control how often backups run:

claude-backup schedule daily    # Every day at 3:00 AM (default)
claude-backup schedule 6h       # Every 6 hours
claude-backup schedule hourly   # Every hour
claude-backup schedule off      # Disable automatic backups

Restore Everything