npm package: @opentech1/cc-sync
Description: Sync Claude Code configuration across devices via GitHub
Author: Leo
Latest version: 2.0.13

# cc-sync

Sync your Claude Code configuration across devices via GitHub.

## What is cc-sync?

cc-sync automatically synchronizes your Claude Code slash commands and configuration files across multiple devices using a private GitHub repository. Any changes you make to `~/.claude/` on one device can be easily synced to all your other devices.

## Features

- **Automatic sync**: Push and pull your Claude configuration with simple commands
- **Daemon mode**: Watch for changes and auto-push them to GitHub
- **Private & secure**: Uses your existing GitHub authentication via `gh` CLI
- **Simple setup**: One command to initialize

## Requirements

- **Node.js 18+** or **Bun** (recommended)
- **GitHub CLI** (`gh`) installed and authenticated
  ```bash
  # Install GitHub CLI (macOS)
  brew install gh

  # Authenticate
  gh auth login
  ```

## Installation

### Using Bun (recommended)

```bash
# Clone the repository
git clone https://github.com/yourusername/cc-sync.git
cd cc-sync

# Install globally
bun install -g .
```

### Using npm

```bash
# Clone the repository
git clone https://github.com/yourusername/cc-sync.git
cd cc-sync

# Install globally
npm install -g .
```

After installation, you can use the `cc-sync` command from anywhere.

## Quick Start

### 1. Initialize

First-time setup on your primary device:

```bash
cc-sync init
```

This creates a private `.cc-sync-config` repository on your GitHub account and pushes your current `~/.claude/` configuration.

### 2. Push changes

After making changes to your Claude configuration:

```bash
cc-sync push
```

### 3. Pull changes

On another device, pull the latest configuration:

```bash
cc-sync pull
```

### 4. Check status

See what has changed locally:

```bash
cc-sync status
```

### 5. Daemon mode (optional)

Automatically push changes whenever files are modified:

```bash
cc-sync daemon
```

Press Ctrl+C to stop the daemon.

## How it Works

1. **Private GitHub repo**: cc-sync creates a private repository called `.cc-sync-config` on your GitHub account
2. **Local config**: Your Claude configuration lives in `~/.claude/`
3. **Git-based sync**: Uses Git to track changes and sync between devices
4. **GitHub CLI**: Leverages `gh` for authentication (no need to manage tokens)

## Commands

```bash
cc-sync init        # Initialize cc-sync (first-time setup)
cc-sync push        # Push local changes to GitHub
cc-sync pull        # Pull changes from GitHub
cc-sync status      # Show local changes
cc-sync daemon      # Watch for changes and auto-push
cc-sync --help      # Show help
cc-sync --version   # Show version
```

## Typical Workflow

### On your first device

```bash
# One-time setup
cc-sync init

# Make changes to ~/.claude/commands/
# Then push them
cc-sync push
```

### On your second device

```bash
# One-time setup
cc-sync init

# Pull the configuration from your first device
cc-sync pull

# Make changes locally
# Push them back
cc-sync push
```

### Using daemon mode

```bash
# Start watching for changes
cc-sync daemon

# Now any changes to ~/.claude/ are automatically pushed
# Leave it running in the background or in a tmux session
```

## What Gets Synced?

Everything in your `~/.claude/` directory:

- Slash commands (`~/.claude/commands/*.md`)
- CLAUDE.md configuration
- Any other configuration files you add

## Troubleshooting

### "gh: command not found"

Install the GitHub CLI:
```bash
brew install gh
gh auth login
```

### "Repository already exists"

If `.cc-sync-config` already exists on your GitHub account, you can:
1. Delete it from GitHub and run `cc-sync init` again
2. Or manually clone it to `~/.claude/.cc-sync-repo/`

### Merge conflicts

If you have conflicting changes on multiple devices:
```bash
cd ~/.claude/.cc-sync-repo
git status
# Resolve conflicts manually
git add .
git commit -m "Resolved conflicts"
cc-sync push
```

## License

MIT

## Contributing

Issues and pull requests welcome!