cc-sync

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 27 Open GitHub ↗

Seamlessly sync Claude Code config & sessions across machines | 跨机器无缝同步 Claude Code 配置和会话

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
  <h1 align="center">cc-sync</h1>
  <p align="center">
    Seamlessly sync your Claude Code configuration and sessions across machines.
    <br />
    <a href="./README_zh-CN.md">简体中文</a> · English
  </p>
</p>

Switch computers, run `claude --resume`, and pick up right where you left off.

## What It Does

```
Start claude  →  auto pull latest config & sessions
    ↓
  Working...
    ↓
Exit claude   →  auto commit & push
    ↓
Other machine →  start claude → auto pull → claude --resume
```

**What gets synced:**
- `settings.json` — Claude Code settings, hooks, plugin toggles
- `commands/` — Custom slash commands
- `skills/` — Custom skills
- `plugins/` — Installed plugins
- `projects/*/memory/` — Cross-session memory
- Recent N sessions (for `claude --resume`)

**What stays local:**
- `.credentials.json` — Credentials (security)
- `debug/`, `cache/`, `telemetry/`, etc. — Local caches
- Old session files — Only recent ones are synced to keep repo size manageable

## Installation

### Prerequisites

- [Claude Code](https://claude.com/claude-code) installed and used at least once
- Git
- A GitHub repository (recommend **private**) for storing config

### One-Line Install

```bash
curl -fsSL https://raw.githubusercontent.com/ikook-wang/cc-sync/main/install.sh | bash
```

The installer will interactively guide you through:

1. Enter your GitHub repo URL
2. Set number of sessions to keep (default: 3)
3. Auto-configure `.gitignore`, hooks, and shell wrapper
4. Run initial sync

> Run this once on each machine.

### On Another Machine

```bash
# 1. Install cc-sync (use the same GitHub repo URL)
curl -fsSL https://raw.githubusercontent.com/ikook-wang/cc-sync/main/install.sh | bash

# 2. Resume your previous session
claude --resume
```

## How It Works

cc-sync uses three mechanisms for automatic syncing:

| When | Mechanism | Action |
|------|-----------|--------|
| Start Claude Code | `SessionStart` hook | `git pull` to get latest |
| Exit Claude Code | Shell wrapper function | Run `sync.sh` to commit & push |
| Manual trigger | `bash ~/.claude/sync.sh` | Same as above |

### Session File Strategy

`.gitignore` ignores all session `.jsonl` files by default. When `sync.sh` runs:

1. Finds the most recent N sessions per project
2. Force-adds them with `git add -f`
3. Removes older sessions from git index with `git rm --cached` (**local files are never deleted**)

This keeps full history locally while keeping the git repo size manageable.

## Configuration

Edit `~/.claude/sync.conf`:

```bash
# Number of sessions to keep per project
KEEP_SESSIONS=3
```

## Commands

```bash
# Manual sync
bash ~/.claude/sync.sh

# Verbose mode (see sync details)
bash ~/.claude/sync.sh --verbose

# Uninstall
bash ~/.claude/uninstall.sh
```

## Uninstall

```bash
bash ~/.claude/uninstall.sh
```

This removes:
- `sync.sh`, `sync.conf`, `uninstall.sh`
- `SessionStart` hook from `settings.json`
- Shell wrapper from your rc file

**Not removed:** Your git repo and synced data.

## FAQ

### Q: What if my username/path differs across machines?

Claude Code encodes project paths in directory names (e.g., `projects/-Users-alice-WorkSpace/`). If home directory paths differ, session files won't match. Use the same username and directory structure on all machines.

### Q: Will sensitive data be synced?

No. `.credentials.json` is excluded by `.gitignore`. We recommend using a **private** repository.

### Q: How are conflicts handled?

Automatically. When `sync.sh` encounters merge conflicts during pull, it auto-resolves by keeping the local version (`--ours`), since for a personal config repo, the local state is always the most current.

### Q: Does it work on Linux?

Yes. Scripts are compatible with bash 3.2+ and work on both macOS and Linux.

## License

MIT

cc-sync

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README