npm package: @lucasygu/claude-backup
Description: One-command backup for your Claude Code brain (~/.claude) to GitHub
Author: lucasygu
Latest version: 0.1.0

# 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

```bash
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

```bash
npm install -g @lucasygu/claude-backup
```

This also installs the `/backup` skill for Claude Code.

## Commands

```bash
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