claude-backup

One-command backup for your Claude Code brain (~/.claude) to GitHub.

Your Claude Code config — skills, memory, agents, settings, hooks — is your accumulated AI expertise. This tool backs it up automatically so you never lose it.

Quick Start

npx @lucasygu/claude-backup init

That's it. This will:

1. Detect your ~/.claude directory
2. Create a private GitHub repo (via gh CLI)
3. Generate a smart .gitignore (backs up config, ignores ephemeral data)
4. Run the first backup
5. Install a scheduler (every 30 min)
6. Register Claude Code hooks (auto-sync on tool use + session end)

Install globally

npm install -g @lucasygu/claude-backup

This also installs the /backup skill for Claude Code.

Commands

claude-backup              # Smart default: init or sync
claude-backup init         # One-shot setup
claude-backup sync         # Backup now
claude-backup status       # Health check
claude-backup status --json  # Machine-readable status

claude-backup daemon install    # Install scheduled backup
claude-backup daemon uninstall  # Remove scheduler
claude-backup daemon status     # Check scheduler

claude-backup hook install      # Register Claude Code hooks
claude-backup hook uninstall    # Remove hooks
claude-backup hook status       # Check hooks

What gets backed up

| Backed up | Not backed up (by design) | |-----------|--------------------------| | CLAUDE.md (global instructions) | Session transcripts (JSONL — large, ephemeral) | | skills/ (custom skills) | Credentials & secrets | | agents/ (agent definitions) | Debug logs, cache, telemetry | | settings.json (permissions, model config) | Plugin marketplace cache | | keybindings.json | Temporary files | | plugins/installed_plugins.json | | | projects/*/memory/ (persistent memory) | | | hooks/ (hook scripts) | |

Three-layer backup

| Layer | Trigger | How | |-------|---------|-----| | Passive | Every Claude Code tool use | PostToolUse hook (5-min debounce) | | Scheduled | Every 30 min | launchd (macOS) / cron (Linux) | | Manual | You decide | claude-backup sync or /backup in Claude Code |

Cross-machine sync

If you use the same repo on multiple machines, the tool auto-remaps project memory directories when usernames differ:

Machine A (user: alice):  projects/-Users-alice-projects-myapp/memory/
Machine B (user: bob):    projects/-Users-bob-projects-myapp/memory/
                          ↑ auto-remapped on pull

Git-native design

Unlike other backup tools that copy files to a separate directory, this tool works directly in ~/.claude which is already a git repo. No rsync, no file drift — what you see is what's backed up.

Commit messages are category-aware:

vault-sync 2026-03-10 14:30 (3 memories, 1 skill, 2 config)
vault-sync 2026-03-10 15:00 (no changes, skipped)

Requirements

• git (required)
• gh CLI (optional — for automatic GitHub repo creation)
• Node.js >= 22

As a Claude Code skill

After installing, use /backup in any Claude Code session:

/backup          # sync now
/backup init     # full setup
/backup status   # health check

License

MIT