# Claude Backup

> Backup your Claude Code brain (~/.claude) to GitHub — one command, automatic sync

- Skill: `lucasygu/claude-backup` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add lucasygu/claude-backup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lucasygu/claude-backup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lucasygu (https://skillmd.com/u/lucasygu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lucasygu/claude-backup

---


# Claude Backup — ~/.claude to GitHub

Use the `claude-backup` CLI to back up and sync your Claude Code configuration, skills, memory, and settings to a private GitHub repo.

## Quick Reference

Run these via Bash:

```bash
# Smart default: init if first time, sync if already set up
claude-backup

# One-shot setup (creates repo, installs scheduler + hooks)
claude-backup init
claude-backup init --repo my-custom-name

# Manual sync
claude-backup sync

# Health check
claude-backup status
claude-backup status --json

# Scheduler management
claude-backup daemon install
claude-backup daemon install --interval 15
claude-backup daemon uninstall
claude-backup daemon status

# Hook management
claude-backup hook install
claude-backup hook uninstall
claude-backup hook status
```

## What gets backed up

- `CLAUDE.md` — global instructions
- `skills/` — custom skills
- `agents/` — agent definitions
- `settings.json` — permissions, model config
- `keybindings.json` — key mappings
- `plugins/installed_plugins.json` — plugin registry
- `projects/*/memory/` — per-project persistent memory
- `hooks/` — hook scripts

## What's excluded

- Session transcripts (JSONL — ephemeral, large)
- Credentials and secrets (`.credentials.json`, `*.local.json`)
- Debug logs, cache, telemetry
- Plugin marketplace cache

## How it works

Three-layer backup:

1. **Passive**: Claude Code hooks auto-sync after tool use (5-min debounce)
2. **Scheduled**: launchd (macOS) or cron (Linux) every 30 min
3. **Manual**: `claude-backup sync`

Git-native — works directly in `~/.claude` (no file copying). Commit messages are category-aware:
```
vault-sync 2026-03-10 14:30 (3 memories, 1 skill, 2 config)
```

## Cross-machine sync

Auto-remaps project memory directories when usernames differ between machines.

## Requirements

- `git` (required)
- `gh` CLI (optional — for automatic private repo creation)
- Install: `npm install -g @lucasygu/claude-backup`