claude-github-sync

claude-github-sync

Sync your Claude Code configuration across multiple machines using GitHub.

Installation

For AI Assistants

If you're an AI assistant helping a user install this plugin:

Step 1: Check prerequisites

# Verify GitHub CLI is installed
gh --version

# Verify GitHub CLI is authenticated
gh auth status --hostname github.com

If gh is not installed, guide the user:

• macOS: brew install gh
• Linux: sudo apt install gh
• Windows: winget install GitHub.cli

If not authenticated: gh auth login

Step 2: Install the plugin

claude plugin marketplace add oozoofrog/claude-github-sync
claude plugin install claude-github-sync

Step 3: Initial setup

Guide the user to run:

/claude-github-sync:setup

This creates a private claude-config repository and syncs their configuration automatically.

Step 4: Verify installation

/claude-github-sync:status

Should show "✅ In sync with remote" when successful.

Manual Installation

# Add marketplace
claude plugin marketplace add oozoofrog/claude-github-sync

# Install plugin
claude plugin install claude-github-sync

Or via slash command:

/install claude-github-sync@claude-github-sync

Quick Start (Recommended)

The easiest way to get started - just run:

/claude-github-sync:setup

This will:

1. Check GitHub CLI is installed and authenticated
2. Create a private claude-config repository (or use existing)
3. Initialize local git repository
4. Push your configuration automatically

That's it! One command does everything.

On Other Machines

Once you've run /setup on your first machine, just run the same command on other machines:

/claude-github-sync:setup

This will detect your existing claude-config repository and pull your configuration automatically.

Commands

Command	Description
/claude-github-sync:setup	Interactive setup (recommended) - handles everything automatically
/claude-github-sync:push	Push changes to GitHub
/claude-github-sync:push "msg"	Push with custom commit message
/claude-github-sync:pull	Pull latest from GitHub
/claude-github-sync:status	Show detailed sync status
/claude-github-sync:config	Show configuration
/claude-github-sync:open	Open repository in browser

Prerequisites

GitHub CLI (Required)

This plugin uses GitHub CLI (gh) for authentication and repository management.

Install:

• macOS: brew install gh
• Linux: sudo apt install gh or see https://cli.github.com/
• Windows: winget install GitHub.cli

Authenticate:

gh auth login

Configuration Files

After setup, the following files are created and managed:

File	Path	Description
Config	~/.claude/sync-config.json	Sync configuration (repo URL, setup timestamp, method)
Sync settings	~/.claude/settings.sync.json	Shared settings (synced to GitHub)
Local settings	~/.claude/settings.local.json	Machine-specific settings (gitignored)
Merged output	~/.claude/settings.json	Auto-merged result of sync + local
Merge script	~/.claude/scripts/merge-settings.mjs	Deep merges sync + local → settings.json
Git ignore	~/.claude/.gitignore	Excludes cache, session data, local settings

Configuration check priority:

1. Primary: Git remote URL (~/.claude/.git/config → origin)
2. Fallback: Config file (~/.claude/sync-config.json)

What Gets Synced

Included:

• CLAUDE.md - AI behavior instructions
• settings.json - Plugin settings
• plugins/ - Plugin registry (not cache)
• hud/ - Status line scripts
• Custom skills and commands

Excluded:

• plugins/cache/ - Downloaded plugins (auto-reinstalled)
• plugins/marketplaces/ - Marketplace data (auto-fetched)
• debug/, session-env/ - Session data
• history.jsonl - Command history
• projects/ - Project-specific data

Troubleshooting

"GitHub CLI not authenticated"

gh auth login

"Repository not found"

The plugin will offer to create it automatically. Or create manually:

gh repo create claude-config --private

"Push failed"

1. Check authentication: gh auth status
2. Pull first if remote has changes: /claude-github-sync:pull
3. Check the detailed status: /claude-github-sync:status

Check detailed status

/claude-github-sync:status

Shows:

• GitHub CLI authentication status
• Remote repository accessibility
• Local pending changes
• Ahead/behind commit count

Security

• Always use a private repository
• The plugin verifies repository exists before operations
• Uses GitHub CLI for secure authentication (no tokens in config)

Changelog