# CCSync

**Repository Path**: twqian/ccsync

## Basic Information

- **Project Name**: CCSync
- **Description**: 通过 Git 在多台电脑之间同步 Claude Code 配置（~/.claude/）的命令行工具。直接同步插件缓存文件，确保斜杠命令前缀在所有机器上完全一致。密钥自动脱敏，apply 前自动备份。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-04-13
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CCSync

通过 Git 在多台电脑之间同步你的 Claude Code 配置。

## 特性

- **环境变量保护**：使用占位符
- **跨平台**：支持 Windows（PowerShell）、macOS 和 Linux（Bash）
- **增量同步**：只推送变更；另一端拉取并合并
- **插件直传**：直接同步插件缓存文件和注册表，确保斜杠命令前缀在所有机器上一致
- **自动备份**：apply 前自动创建带时间戳的备份

## 安装

```bash
npm install -g claude-code-sync
```

## 快速开始

### 机器 A（源机器）

```bash
# 1. 创建一个 Git 仓库作为同步存储（GitHub、Gitee、自建 Git 服务器均可）
#    支持所有 Git 协议：HTTPS、SSH、file://

# 2. 初始化
claude-code-sync init --remote <git-url>

# 3. 捕获当前配置
claude-code-sync capture

# 4. 推送到远程
claude-code-sync push
```

### 机器 B（目标机器）

```bash
# 1. 克隆同步仓库
claude-code-sync clone <git-url>

# 2. 应用同步配置
claude-code-sync apply
```

### 日常使用

```bash
# 在任意机器上修改配置后：
claude-code-sync capture
claude-code-sync push

# 在其他所有机器上：
claude-code-sync pull
claude-code-sync apply
```

## 命令

| 命令 | 说明 |
|------|------|
| `init --remote <url>` | 初始化同步仓库并连接 Git 远程 |
| `clone <url>` | 在新机器上克隆同步仓库 |
| `capture` | 扫描 `~/.claude/` 并生成同步快照 |
| `push` | 提交并推送变更到 Git |
| `pull` | 从 Git 拉取最新变更 |
| `apply` | 将同步配置应用到本地 `~/.claude/` |

### 三层数据模型

CCSync 将 Claude Code 的配置分为三层：

| 层级 | 内容 | 同步方式 |
|------|------|----------|
| **声明层** | MCP 服务器配置、env 变量列表 | 记录在 `operations.json` 中 |
| **定义层** | CLAUDE.md、agents/、rules/、skills/、settings overrides、插件缓存 | 直接文件同步 |
| **物理层** | marketplaces/ 源码（含 .git）、node_modules | 不同步 — 插件通过缓存直传 |

### 同步仓库结构

```
claude-code-sync-repo/
├── operations.json         # 操作清单（MCP 服务器、env 变量等）
├── files/                  # 配置文件
│   ├── CLAUDE.md
│   ├── settings.json       # 脱敏版本（env 值 → $占位符）
│   ├── config.json
│   ├── agents/
│   │   └── reviewer.md
│   ├── rules/
│   │   └── style.md
│   ├── skills/
│   └── plugins/            # 插件缓存和注册表（v0.2.0 新增）
│       ├── known_marketplaces.json
│       ├── installed_plugins.json
│       └── cache/
│           └── <marketplace>/<plugin>/<version>/
│               ├── skills/
│               ├── agents/
│               └── ...
└── README.md
```

## License

[Apache-2.0](LICENSE)