claude-sync — How To Guide

Script: ~/.claude/scripts/claude-sync.sh  ·  Repo: github.com/d1g1entr0py/claude-data  ·  ← env.consaul.cloud

1 — Overview

claude-sync is a bash script that backs up and synchronises Claude Code data (memory files, settings, CLAUDE.md files, scripts) across devices via a private GitHub repository. It uses git as the transport layer — each push is a signed commit with a timestamp and device name, giving you a full history of every change.

# Core flow
~/.claude/  ──push──▶  github.com/d1g1entr0py/claude-data  ──pull──▶  ~/.claude/ (other device)

2 — What Is Synced

Included

Not Included (excluded by design)

3 — Commands

All commands are run as: bash ~/.claude/scripts/claude-sync.sh <command> — or just claude-sync <command> if symlinked to PATH (see below).

Common usage examples

# Check what would be pushed before committing
bash ~/.claude/scripts/claude-sync.sh status

# Immediate push with a label (e.g. end of a session)
bash ~/.claude/scripts/claude-sync.sh push "completed voice-assistant refactor"

# Pull latest on a secondary device after the server has auto-pushed
bash ~/.claude/scripts/claude-sync.sh pull

# View sync history
bash ~/.claude/scripts/claude-sync.sh log 10

# Add to PATH for convenience (run once)
ln -s ~/.claude/scripts/claude-sync.sh /usr/local/bin/claude-sync
claude-sync status

4 — Automation (cron)

The auto-push cron is already installed on hetzner-cloudvm-hel1:

*/30 * * * * /root/.claude/scripts/claude-sync.sh push >> /root/.claude/.sync.log 2>&1

Output is logged to ~/.claude/.sync.log. To tail it:

tail -f ~/.claude/.sync.log

To change the interval (e.g. every 15 minutes):

bash ~/.claude/scripts/claude-sync.sh auto-off
bash ~/.claude/scripts/claude-sync.sh auto 15

5 — Setting Up a New Device

Run these commands on the new machine:

# 1. Create the token file (use the same token as the server, or create a new one)
echo 'ghp_YOURTOKEN' > ~/.claude/.sync-token && chmod 600 ~/.claude/.sync-token

# 2. Copy the script to the right location
mkdir -p ~/.claude/scripts
# Option A — copy from this server over SSH:
scp -i ~/.ssh/vps-hetzner root@89.167.54.62:~/.claude/scripts/claude-sync.sh ~/.claude/scripts/
# Option B — download from GitHub (requires token):
TOKEN=$(cat ~/.claude/.sync-token) && curl -s -H "Authorization: Bearer $TOKEN" \
  "https://raw.githubusercontent.com/d1g1entr0py/claude-data/main/scripts/claude-sync.sh" \
  -o ~/.claude/scripts/claude-sync.sh
chmod +x ~/.claude/scripts/claude-sync.sh

# 3. Run setup — clones the repo and configures git
bash ~/.claude/scripts/claude-sync.sh setup

# 4. Pull current state
bash ~/.claude/scripts/claude-sync.sh pull

# 5. Optionally enable auto-push on this device too
bash ~/.claude/scripts/claude-sync.sh auto 30

# 6. Optionally add to PATH
ln -s ~/.claude/scripts/claude-sync.sh /usr/local/bin/claude-sync

6 — Adding / Removing Sync Locations

Open the script and find the SYNC_MAP array near the top:

nano ~/.claude/scripts/claude-sync.sh
# or
vim ~/.claude/scripts/claude-sync.sh

Adding a static path

Add an entry to SYNC_MAP. Format is ["source relative to ~/.claude"]="dest in repo":

declare -A SYNC_MAP=(
    # existing entries...
    ["settings.json"]="settings.json"
    ["projects/-/memory"]="memory/global"
    ["scripts"]="scripts"
    ["todos"]="todos"

    # NEW — example: sync a custom hooks directory
    ["hooks"]="hooks"
)

Directories are synced with rsync -a --delete (mirrors the source exactly). Single files are copied directly.

Removing a static path

Delete the line from SYNC_MAP. Note: files already committed to the repo are not automatically deleted from GitHub — you'd need to cd ~/.claude/.sync-repo && git rm -r <path> && git push if you want to clean them out.

Project memory and CLAUDE.md files (auto-discovered)

You don't need to add projects manually. The discover_projects() function scans ~/.claude/projects/ and automatically includes any directory that has a memory/ subdirectory or a CLAUDE.md file. Creating either of those is enough for the project to be picked up on the next push.

Excluding specific files from a synced directory

The script uses rsync for directory syncing. To exclude files, edit the stage_files() function and add --exclude='pattern' to the relevant rsync call:

rsync -a --delete --exclude='.git' --exclude='*.tmp' --exclude='secrets.json' \
  "$src_path/" "$dst_path/"

7 — Managing the GitHub Token

The token is stored in ~/.claude/.sync-token (mode 600, never committed to git). Every network operation reads this file and updates the git remote URL automatically — so rotating the token is a one-liner:

# Rotate the token — script self-heals on next run
echo 'ghp_NEWTOKEN' > ~/.claude/.sync-token && chmod 600 ~/.claude/.sync-token

# Verify it works
bash ~/.claude/scripts/claude-sync.sh status

Creating a token on GitHub

1. Go to github.com → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click Generate new token (classic)
3. Set a note (e.g. claude-sync-hetzner), choose an expiry
4. Check the repo scope (full repository access)
5. Click Generate token, copy it immediately
6. Save to the server: echo 'ghp_...' > ~/.claude/.sync-token && chmod 600 ~/.claude/.sync-token

8 — Troubleshooting

Manually inspect the sync repo

cd ~/.claude/.sync-repo

# Show last 10 commits
git log --oneline -10

# See exactly what changed in the last push
git show --stat HEAD

# Check remote is reachable
GIT_TERMINAL_PROMPT=0 git ls-remote origin HEAD

# See what would be staged right now
bash ~/.claude/scripts/claude-sync.sh status

9 — Windows Deployment (PowerShell)

A full PowerShell port of the bash script is available. It mirrors all commands — push, pull, status, log, auto — and uses Task Scheduler instead of cron and robocopy instead of rsync.

Prerequisites

• Git for Windows — git-scm.com/download/win (adds git to PATH)
• PowerShell 5.1+ — built into Windows 10/11. PowerShell 7+ also works and is recommended.
• A GitHub personal access token with repo scope — see section 7.

Execution policy (one-time)

Windows blocks unsigned scripts by default. Set the policy once per machine (run PowerShell as Administrator):

# Allow local scripts — run once as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine

First-time setup

# 1. Create the Claude scripts directory
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\scripts"

# 2. Download the script
Invoke-WebRequest -Uri "https://env.consaul.cloud/claude-sync.ps1" `
    -OutFile "$env:USERPROFILE\.claude\scripts\claude-sync.ps1"

# 3. Save your GitHub token
Set-Content "$env:USERPROFILE\.claude\.sync-token" "ghp_YOURTOKEN"

# 4. Run setup — verifies git, token, and clones the repo
& "$env:USERPROFILE\.claude\scripts\claude-sync.ps1" setup

# 5. Pull current state from GitHub
& "$env:USERPROFILE\.claude\scripts\claude-sync.ps1" pull

# 6. Enable auto-push every 30 minutes via Task Scheduler
& "$env:USERPROFILE\.claude\scripts\claude-sync.ps1" auto 30

Commands (PowerShell syntax)

# Shorthand alias — run once per session or add to $PROFILE
Set-Alias claude-sync "$env:USERPROFILE\.claude\scripts\claude-sync.ps1"

# Then use the same command names as the bash version:
claude-sync status
claude-sync push "end of session note"
claude-sync pull
claude-sync log 10
claude-sync auto 30      # register Task Scheduler job
claude-sync auto-off     # remove Task Scheduler job

Path differences: Linux vs Windows

Viewing and managing the Task Scheduler job

# Check if the job is registered and its last run time
Get-ScheduledTask -TaskName ClaudeSync | Select-Object TaskName, State
(Get-ScheduledTaskInfo -TaskName ClaudeSync).LastRunTime
(Get-ScheduledTaskInfo -TaskName ClaudeSync).LastTaskResult  # 0 = success

# Trigger a manual run immediately (same as push)
Start-ScheduledTask -TaskName ClaudeSync

# Remove the job
& "$env:USERPROFILE\.claude\scripts\claude-sync.ps1" auto-off

# Tail the log
Get-Content "$env:USERPROFILE\.claude\.sync.log" -Wait -Tail 20

Adding the alias to your PowerShell profile (permanent)

# Open your profile file (creates it if missing)
if (-not (Test-Path $PROFILE)) { New-Item $PROFILE -Force }
notepad $PROFILE

# Add this line, save, then re-open PowerShell:
Set-Alias claude-sync "$env:USERPROFILE\.claude\scripts\claude-sync.ps1"

Troubleshooting (Windows-specific)

Last updated 2026-04-23  ·  env.consaul.cloud  ·  Bash: ~/.claude/scripts/claude-sync.sh  ·  PowerShell: claude-sync.ps1