vibe-config-sync 0.2.4 → 0.4.0

package/README.md

@@ -4,14 +4,23 @@
 
 > **Command:** `vibe-sync`
 
-Sync AI coding tool configurations across machines via Git. Currently supports Claude Code (`~/.claude/`).
+Sync AI coding tool configurations across machines via Git. Supports Claude Code (`~/.claude/`) and Codex (`~/.codex/`).
 
 ## Problem
 
 When using AI coding tools on multiple machines, configurations like skills, commands, agents, plugins, and user preferences need to be manually replicated on each machine.
 
+## Security Recommendation
+
+- Use a **private** Git repository for sync data.
+- If you use a public repository, do **not** sync any sensitive information (API keys, tokens, credentials, secrets in config files or MCP env).
+
 ## What Gets Synced
 
+Default provider is `all` (both Claude and Codex).
+
+### Claude (`data/claude/`)
+
 | Content | Description |
 |---------|-------------|
 | `settings.json` | Plugin enable/disable flags |
@@ -21,8 +30,19 @@ When using AI coding tools on multiple machines, configurations like skills, com
 | `agents/` | Agent definitions |
 | `plugins/installed_plugins.json` | Plugin registry (machine paths stripped) |
 | `plugins/known_marketplaces.json` | Plugin marketplace sources (machine paths stripped) |
+| `mcp-servers.json` | MCP server configs (extracted from `~/.claude.json`) |
+
+### Codex (`data/codex/`)
+
+| Content | Description |
+|---------|-------------|
+| `config.toml` | Codex settings/preferences |
+| `AGENTS.md` | Codex user preferences and workflow guidance |
+| `commands/` | User custom commands (if present) |
+| `skills/` | Codex skills |
+| `agents/` | Codex agents |
 
-**Not synced** (machine-specific / ephemeral / large): `plugins/cache/`, `projects/`, `telemetry/`, `session-env/`, `plans/`, `todos/`, `debug/`, `history.jsonl`, etc.
+**Not synced** (machine-specific / ephemeral / large): cache/log/temp/session state, lock files, and runtime auth/session material.
 
 ## Prerequisites
 
@@ -42,15 +62,17 @@ npm install -g vibe-config-sync
 
 ```bash
 vibe-sync init          # Initialize and connect to a Git remote
-vibe-sync push          # Export configs and push to remote
+vibe-sync push          # Export all providers and push to remote
+vibe-sync push --provider claude   # Claude only
 ```
 
 ### Machine B (import)
 
 ```bash
 vibe-sync init                      # Initialize and pull from remote
-vibe-sync pull                      # Pull, import configs, and sync plugins
-vibe-sync pull --no-plugins         # Pull and import configs only (skip plugins)
+vibe-sync pull                      # Pull + import all providers
+vibe-sync pull --provider claude    # Pull + import Claude only
+vibe-sync pull --no-plugins         # Disable Claude plugin phase
 ```
 
 ## Commands
@@ -58,17 +80,17 @@ vibe-sync pull --no-plugins         # Pull and import configs only (skip plugins
 | Command | Description |
 |---------|-------------|
 | `vibe-sync init` | Initialize sync repository and connect to Git remote |
-| `vibe-sync export` | Collect configs from `~/.claude/` into sync repo |
-| `vibe-sync import` | Restore configs from sync repo to `~/.claude/` (includes plugin sync) |
-| `vibe-sync import --no-plugins` | Restore configs only, skip plugin sync |
+| `vibe-sync export` | Export selected provider(s) (`--provider claude|codex|all`, default `all`) |
+| `vibe-sync import` | Import selected provider(s) (`--provider claude|codex|all`, default `all`) |
+| `vibe-sync import --no-plugins` | Skip Claude plugin sync phase (no effect for Codex) |
 | `vibe-sync import --dry-run` | Preview what would be imported without making changes |
-| `vibe-sync status` | Show diff between local and synced configs |
+| `vibe-sync status` | Show diff for selected provider(s) |
 | `vibe-sync push` | export + git commit + git push |
-| `vibe-sync pull` | git pull + import (includes plugin sync) |
-| `vibe-sync pull --no-plugins` | git pull + import, skip plugin sync |
+| `vibe-sync pull` | git pull + import |
+| `vibe-sync pull --no-plugins` | Skip Claude plugin phase during import |
 | `vibe-sync pull --dry-run` | Preview what would be imported (skips git pull) |
-| `vibe-sync restore` | List available backups |
-| `vibe-sync restore <timestamp>` | Restore `~/.claude/` from a specific backup |
+| `vibe-sync restore` | List available backups (`--provider` supported, default `all`) |
+| `vibe-sync restore <timestamp>` | Restore selected provider(s) from backup timestamp (`all` restores available providers, skips missing ones) |
 
 ## Daily Workflow
 
@@ -82,11 +104,13 @@ vibe-sync pull
 
 ## How It Works
 
-- **Export** copies config files into `~/.vibe-sync/data/`, stripping machine-specific paths from plugin JSON files. Skills that are symlinks are resolved and their actual contents are copied.
+- **Provider-aware data layout** stores sync data under `~/.vibe-sync/data/claude/` and `~/.vibe-sync/data/codex/` (legacy Claude root layout is auto-migrated).
 
-- **Import** restores files from `~/.vibe-sync/data/` to `~/.claude/`, validating JSON structure before overwriting. Plugin JSON files are used as a manifest only (never copied directly) — the `claude` CLI installs plugins and writes correct registry files with local paths. Already-installed plugins are detected and skipped.
+- **Export** copies provider config files into the provider data directory. Claude plugin JSON files are sanitized (machine paths removed). Claude MCP server configs are extracted from `~/.claude.json`. Codex `config.toml` is scanned for sensitive keys; export requires interactive confirmation when sensitive fields are detected. In non-interactive mode, sensitive Codex `config.toml` export is skipped with a warning.
 
-- **Backup** is created automatically at `~/.vibe-sync/backups/claude/<timestamp>/` before every import. Use `vibe-sync restore` to list or recover from backups.
+- **Import** restores provider files from sync data to local provider directories. `--provider all` runs in order: `claude` then `codex`, with fail-fast semantics. Claude plugin JSON files are manifest-only (never copied directly) and are applied through `claude` CLI. Claude MCP servers are additive-only merges into `~/.claude.json`.
+
+- **Backup** is provider-aware and created before import at `~/.vibe-sync/backups/<provider>/<timestamp>/`. In `all` mode, each provider is backed up independently; missing local provider config is skipped.
 
 ## Sync Strategy
 
@@ -118,6 +142,22 @@ In short: new content is added, existing content is overwritten, but nothing is
 
 Plugin JSON files (`installed_plugins.json`, `known_marketplaces.json`) are exported with machine-specific paths stripped. On import, they are **not** copied to `~/.claude/plugins/` — instead they serve as a manifest. The `claude` CLI is invoked to install each plugin, and it writes correct registry files with local paths as a side effect. Already-installed plugins (detected by `installPath`) are skipped to avoid redundant network operations.
 
+### MCP Servers
+
+MCP server configurations live in `~/.claude.json` under the `mcpServers` key. On export, this section is extracted and saved as `mcp-servers.json` in the sync directory. If any server config contains `env` fields (which may hold secrets like API keys), the user is prompted before exporting.
+
+On import, MCP servers are **additive only** — new servers from the sync repo are added to `~/.claude.json`, but existing servers with the same name are never overwritten. This preserves any machine-specific customizations (e.g., local paths, environment variables).
+
+### Codex Files
+
+Codex follows the same last-write-wins model:
+
+- `config.toml`: whole-file overwrite (no schema validation)
+- `AGENTS.md`: whole-file overwrite
+- `commands/`, `skills/`, `agents/`: directory merge + file overwrite (no local deletion)
+- Sensitive key handling applies only on export; import does not reconstruct redacted secrets
+- `skills/` symlinks are resolved and synced as real directories
+
 ### What This Means in Practice
 
 - If both machines modify different configs and then sync, the machine that runs `import` last will lose its local changes (a timestamped backup exists at `~/.vibe-sync/backups/claude/` for manual recovery)
@@ -129,6 +169,8 @@ Plugin JSON files (`installed_plugins.json`, `known_marketplaces.json`) are expo
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `CLAUDE_HOME` | Override Claude config directory | `~/.claude` |
+| `CLAUDE_JSON` | Override Claude global config file (MCP servers) | `~/.claude.json` |
+| `CODEX_HOME` | Override Codex config directory | `~/.codex` |
 
 ## License
 

package/README.zh-CN.md

@@ -4,14 +4,23 @@
 
 > **命令：** `vibe-sync`
 
-通过 Git 跨机器同步 AI 编程工具配置。目前支持 Claude Code（`~/.claude/`）。
+通过 Git 跨机器同步 AI 编程工具配置。支持 Claude Code（`~/.claude/`）和 Codex（`~/.codex/`）。
 
 ## 问题
 
 在多台机器上使用 AI 编程工具时，技能、命令、代理、插件和用户偏好等配置需要在每台机器上手动复制。
 
+## 安全建议
+
+- 同步仓库强烈建议使用**私有仓库**。
+- 如果使用公开仓库，请**不要**同步任何敏感信息（API Key、Token、凭据、配置文件或 MCP `env` 中的密钥等）。
+
 ## 同步内容
 
+默认 provider 为 `all`（Claude + Codex）。
+
+### Claude（`data/claude/`）
+
 | 内容 | 说明 |
 |------|------|
 | `settings.json` | 插件启用/禁用标志 |
@@ -21,8 +30,19 @@
 | `agents/` | 代理定义 |
 | `plugins/installed_plugins.json` | 插件注册表（已剥离机器路径） |
 | `plugins/known_marketplaces.json` | 插件市场来源（已剥离机器路径） |
+| `mcp-servers.json` | MCP 服务器配置（从 `~/.claude.json` 提取） |
+
+### Codex（`data/codex/`）
+
+| 内容 | 说明 |
+|------|------|
+| `config.toml` | Codex 配置 |
+| `AGENTS.md` | Codex 用户偏好与工作流说明 |
+| `commands/` | 用户自定义命令（若存在） |
+| `skills/` | Codex 技能 |
+| `agents/` | Codex 代理 |
 
-**不同步**（机器特定 / 临时 / 大文件）：`plugins/cache/`、`projects/`、`telemetry/`、`session-env/`、`plans/`、`todos/`、`debug/`、`history.jsonl` 等。
+**不同步**（机器特定 / 临时 / 大文件）：缓存、日志、临时/锁文件、会话态、运行期认证材料等。
 
 ## 前置条件
 
@@ -42,15 +62,17 @@ npm install -g vibe-config-sync
 
 ```bash
 vibe-sync init          # 初始化并连接 Git 远程仓库
-vibe-sync push          # 导出配置并推送到远程仓库
+vibe-sync push          # 导出所有 provider 并推送
+vibe-sync push --provider claude   # 仅 Claude
 ```
 
 ### 机器 B（导入）
 
 ```bash
 vibe-sync init                      # 初始化并从远程仓库拉取
-vibe-sync pull                      # 拉取、导入配置并同步插件
-vibe-sync pull --no-plugins         # 仅拉取和导入配置（跳过插件）
+vibe-sync pull                      # 拉取并导入所有 provider
+vibe-sync pull --provider claude    # 仅 Claude
+vibe-sync pull --no-plugins         # 关闭 Claude 插件阶段
 ```
 
 ## 命令
@@ -58,17 +80,17 @@ vibe-sync pull --no-plugins         # 仅拉取和导入配置（跳过插件）
 | 命令 | 说明 |
 |------|------|
 | `vibe-sync init` | 初始化同步仓库并连接 Git 远程仓库 |
-| `vibe-sync export` | 从 `~/.claude/` 收集配置到同步仓库 |
-| `vibe-sync import` | 从同步仓库恢复配置到 `~/.claude/`（包含插件同步） |
-| `vibe-sync import --no-plugins` | 仅恢复配置，跳过插件同步 |
+| `vibe-sync export` | 导出所选 provider（`--provider claude|codex|all`，默认 `all`） |
+| `vibe-sync import` | 导入所选 provider（`--provider claude|codex|all`，默认 `all`） |
+| `vibe-sync import --no-plugins` | 跳过 Claude 插件阶段（对 Codex 无影响） |
 | `vibe-sync import --dry-run` | 预览将要导入的内容，不实际执行 |
-| `vibe-sync status` | 显示本地与同步配置之间的差异 |
+| `vibe-sync status` | 显示所选 provider 的差异 |
 | `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` | git pull + import |
+| `vibe-sync pull --no-plugins` | 导入时跳过 Claude 插件阶段 |
 | `vibe-sync pull --dry-run` | 预览将要导入的内容（跳过 git pull） |
-| `vibe-sync restore` | 列出可用备份 |
-| `vibe-sync restore <timestamp>` | 从指定备份恢复 `~/.claude/` |
+| `vibe-sync restore` | 列出可用备份（支持 `--provider`，默认 `all`） |
+| `vibe-sync restore <timestamp>` | 从指定时间戳恢复所选 provider（`all` 会恢复存在的 provider，缺失则跳过） |
 
 ## 日常工作流
 
@@ -82,11 +104,13 @@ vibe-sync pull
 
 ## 工作原理
 
-- **导出**：将配置文件复制到 `~/.vibe-sync/data/`，同时从插件 JSON 文件中剥离机器特定路径。符号链接的技能会被解析并复制其实际内容。
+- **按 provider 分目录**：同步数据存储在 `~/.vibe-sync/data/claude/` 与 `~/.vibe-sync/data/codex/`（旧版 Claude 根目录布局会自动迁移）。
 
-- **导入**：从 `~/.vibe-sync/data/` 恢复文件到 `~/.claude/`，在覆盖前验证 JSON 结构。插件 JSON 文件仅作为清单使用（不会直接复制）—— `claude` CLI 负责安装插件并写入包含本地路径的正确注册文件。已安装的插件会被检测并跳过。
+- **导出**：按 provider 复制配置。Claude 插件 JSON 会剥离机器路径；Claude MCP 从 `~/.claude.json` 提取。Codex `config.toml` 会做敏感键扫描，检测到敏感字段时必须交互确认后才可导出。非交互模式下若检测到敏感字段，会告警并跳过该文件导出。
 
-- **备份**：每次导入前自动在 `~/.vibe-sync/backups/claude/<timestamp>/` 创建备份。使用 `vibe-sync restore` 列出或恢复备份。
+- **导入**：从 provider 目录恢复到本地。`--provider all` 按 `claude -> codex` 顺序执行，采用 fail-fast。Claude 插件 JSON 仅做清单，不直接复制；通过 `claude` CLI 安装。Claude MCP 只做增量合并（不覆盖同名现有项）。
+
+- **备份**：导入前在 `~/.vibe-sync/backups/<provider>/<timestamp>/` 创建 provider 级备份。`all` 模式下各 provider 独立备份，缺失本地配置则跳过。
 
 ## 同步策略
 
@@ -118,6 +142,22 @@ vibe-sync pull
 
 插件 JSON 文件（`installed_plugins.json`、`known_marketplaces.json`）在导出时会剥离机器特定路径。导入时**不会**复制到 `~/.claude/plugins/`——而是作为清单使用。`claude` CLI 被调用来安装每个插件，并在安装过程中写入包含本地路径的正确注册文件。已安装的插件（通过 `installPath` 检测）会被跳过，以避免冗余的网络操作。
 
+### MCP 服务器
+
+MCP 服务器配置存储在 `~/.claude.json` 的 `mcpServers` 键下。导出时，该部分被提取并保存为同步目录中的 `mcp-servers.json`。如果任何服务器配置包含 `env` 字段（可能包含 API 密钥等密钥），导出前会提示用户确认。
+
+导入时，MCP 服务器采用**仅增量**策略——同步仓库中的新服务器会被添加到 `~/.claude.json`，但同名的已有服务器不会被覆盖。这保留了机器特定的自定义配置（如本地路径、环境变量）。
+
+### Codex 文件
+
+Codex 也遵循相同的最后写入优先策略：
+
+- `config.toml`：整文件覆盖（不做 schema 校验）
+- `AGENTS.md`：整文件覆盖
+- `commands/`、`skills/`、`agents/`：目录合并 + 文件覆盖（不删除本地额外文件）
+- 敏感键处理仅发生在导出阶段；导入不会恢复被脱敏的密钥值
+- `skills/` 中的符号链接会被解析并以真实目录形式同步
+
 ### 实际影响
 
 - 如果两台机器修改了不同的配置然后同步，最后执行 `import` 的机器会丢失其本地更改（可在 `~/.vibe-sync/backups/claude/` 找到带时间戳的备份进行手动恢复）
@@ -129,6 +169,8 @@ vibe-sync pull
 | 变量 | 说明 | 默认值 |
 |------|------|--------|
 | `CLAUDE_HOME` | 覆盖 Claude 配置目录 | `~/.claude` |
+| `CLAUDE_JSON` | 覆盖 Claude 全局配置文件（MCP 服务器） | `~/.claude.json` |
+| `CODEX_HOME` | 覆盖 Codex 配置目录 | `~/.codex` |
 
 ## 许可证