Cross-platform CLI tool to sync AI coding tool configurations across machines via git
npm install vibe-config-syncEnglish | 中文文档
> 命令: vibe-sync
通过 Git 跨机器同步 AI 编程工具配置。目前支持 Claude Code(~/.claude/)。
在多台机器上使用 AI 编程工具时,技能、命令、代理、插件和用户偏好等配置需要在每台机器上手动复制。
| 内容 | 说明 |
|------|------|
| settings.json | 插件启用/禁用标志 |
| CLAUDE.md | 用户偏好和工作流指南 |
| skills/ | 技能定义(SKILL.md + 引用 + 模板) |
| commands/ | 自定义斜杠命令 |
| agents/ | 代理定义 |
| plugins/installed_plugins.json | 插件注册表(已剥离机器路径) |
| plugins/known_marketplaces.json | 插件市场来源(已剥离机器路径) |
| mcp-servers.json | MCP 服务器配置(从 ~/.claude.json 提取) |
不同步(机器特定 / 临时 / 大文件):plugins/cache/、projects/、telemetry/、session-env/、plans/、todos/、debug/、history.jsonl 等。
- Node.js 18+
- git
- claude CLI(用于插件同步;随 Claude Code 自动安装)
``bash`
npm install -g vibe-config-sync
`bash`
vibe-sync init # 初始化并连接 Git 远程仓库
vibe-sync push # 导出配置并推送到远程仓库
`bash`
vibe-sync init # 初始化并从远程仓库拉取
vibe-sync pull # 拉取、导入配置并同步插件
vibe-sync pull --no-plugins # 仅拉取和导入配置(跳过插件)
| 命令 | 说明 |
|------|------|
| vibe-sync init | 初始化同步仓库并连接 Git 远程仓库 |vibe-sync export
| | 从 ~/.claude/ 收集配置到同步仓库 |vibe-sync import
| | 从同步仓库恢复配置到 ~/.claude/(包含插件同步) |vibe-sync import --no-plugins
| | 仅恢复配置,跳过插件同步 |vibe-sync import --dry-run
| | 预览将要导入的内容,不实际执行 |vibe-sync status
| | 显示本地与同步配置之间的差异 |vibe-sync push
| | export + git commit + git push |vibe-sync pull
| | git pull + import(包含插件同步) |vibe-sync pull --no-plugins
| | git pull + import,跳过插件同步 |vibe-sync pull --dry-run
| | 预览将要导入的内容(跳过 git pull) |vibe-sync restore
| | 列出可用备份 |vibe-sync restore
| | 从指定备份恢复 ~/.claude/ |
`bash在机器 A 上修改配置后
vibe-sync push
工作原理
- 导出:将配置文件复制到
~/.vibe-sync/data/,同时从插件 JSON 文件中剥离机器特定路径。符号链接的技能会被解析并复制其实际内容。MCP 服务器配置从 ~/.claude.json 中提取并保存为 mcp-servers.json(如果检测到包含潜在密钥的 env 字段,会提示用户确认)。- 导入:从
~/.vibe-sync/data/ 恢复文件到 ~/.claude/,在覆盖前验证 JSON 结构。插件 JSON 文件仅作为清单使用(不会直接复制)—— claude CLI 负责安装插件并写入包含本地路径的正确注册文件。已安装的插件会被检测并跳过。MCP 服务器以增量方式合并到 ~/.claude.json——仅添加新服务器,已存在的服务器不会被覆盖。- 备份:每次导入前自动在
~/.vibe-sync/backups/claude/ 创建备份,同时备份 ~/.claude/ 内容和 ~/.claude.json。使用 vibe-sync restore 列出或恢复备份。同步策略
整体策略为最后写入优先,无冲突检测。没有字段级合并——最近一次导入会覆盖目标。
$3
整文件覆盖。同步仓库版本完全替换本地版本。
$3
目录级合并 + 文件级覆盖:
| 场景 | 行为 |
|------|------|
| 仓库有
skills/foo/,本地没有 | foo/ 被添加 |
| 双方都有 skills/foo/SKILL.md | 仓库版本覆盖本地 |
| 本地有 skills/bar/,仓库没有 | bar/ 被保留(不删除) |
| 仓库的 skills/foo/ 缺少本地有的文件 | 本地文件被保留 |简而言之:新内容会被添加,已有内容会被覆盖,但本地内容不会被删除。
$3
- 导出:通过
realpathSync 解析符号链接并复制实际文件内容——符号链接本身不会被保留
- 导入:作为普通目录复制,无需重建符号链接。这确保了技能在不同机器上都能正常工作,不受原始符号链接目标路径的影响$3
插件 JSON 文件(
installed_plugins.json、known_marketplaces.json)在导出时会剥离机器特定路径。导入时不会复制到 ~/.claude/plugins/——而是作为清单使用。claude CLI 被调用来安装每个插件,并在安装过程中写入包含本地路径的正确注册文件。已安装的插件(通过 installPath 检测)会被跳过,以避免冗余的网络操作。$3
MCP 服务器配置存储在
~/.claude.json 的 mcpServers 键下。导出时,该部分被提取并保存为同步目录中的 mcp-servers.json。如果任何服务器配置包含 env 字段(可能包含 API 密钥等密钥),导出前会提示用户确认。导入时,MCP 服务器采用仅增量策略——同步仓库中的新服务器会被添加到
~/.claude.json,但同名的已有服务器不会被覆盖。这保留了机器特定的自定义配置(如本地路径、环境变量)。$3
- 如果两台机器修改了不同的配置然后同步,最后执行
import 的机器会丢失其本地更改(可在 ~/.vibe-sync/backups/claude/ 找到带时间戳的备份进行手动恢复)
- 在一台机器上删除的文件/技能不会在另一台机器上被删除——只有添加和修改会传播
- 符号链接的技能会被解析并作为普通目录复制,因此同步版本是独立于原始符号链接目标的独立快照环境变量
| 变量 | 说明 | 默认值 |
|------|------|--------|
|
CLAUDE_HOME | 覆盖 Claude 配置目录 | ~/.claude |
| CLAUDE_JSON | 覆盖 Claude 全局配置文件(MCP 服务器) | ~/.claude.json` |MIT