vibe-config-sync

English | 中文文档

Command: vibe-sync

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
CLAUDE.md	User preferences and workflow guidelines
skills/	Skill definitions (SKILL.md + references + templates)
commands/	Custom slash commands
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): cache/log/temp/session state, lock files, and runtime auth/session material.

Prerequisites

• Node.js 18+
• git
• claude CLI (for plugin sync; installed automatically with Claude Code)

Installation

npm install -g vibe-config-sync

Quick Start

Machine A (first time setup)

vibe-sync init          # Initialize and connect to a Git remote
vibe-sync push          # Export all providers and push to remote
vibe-sync push --provider claude   # Claude only

Machine B (import)

vibe-sync init                      # Initialize and pull from remote
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

Command	Description
vibe-sync init	Initialize sync repository and connect to Git remote
vibe-sync export	Export selected provider(s) (`--provider claude
vibe-sync import	Import selected provider(s) (`--provider claude
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 for selected provider(s)
vibe-sync push	export + git commit + git push
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 (--provider supported, default all)
vibe-sync restore <timestamp>	Restore selected provider(s) from backup timestamp (all restores available providers, skips missing ones)

Daily Workflow

# After changing configs on Machine A
vibe-sync push

# On Machine B, pull latest
vibe-sync pull

How It Works

• Provider-aware data layout stores sync data under ~/.vibe-sync/data/claude/ and ~/.vibe-sync/data/codex/ (legacy Claude root layout is auto-migrated).

• 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.

• 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

The overall strategy is last-write-wins with no conflict detection. There is no field-level merge — the most recent import overwrites the target.

Files (settings.json, CLAUDE.md)

Whole-file overwrite. The sync repo version replaces the local version entirely.

Directories (skills/, commands/, agents/)

Directory-level merge + file-level overwrite:

Scenario	Behavior
Repo has skills/foo/, local does not	foo/ is added
Both have skills/foo/SKILL.md	Repo version overwrites local
Local has skills/bar/, repo does not	bar/ is kept (not deleted)
Repo's skills/foo/ is missing a file that local has	Local file is kept

In short: new content is added, existing content is overwritten, but nothing is deleted from the local side.

Symlinked Skills

• Export: symlinks are resolved via realpathSync and the actual file contents are copied — the symlink itself is not preserved
• Import: copied as regular directories, no symlink recreation needed. This ensures skills work across machines regardless of the original symlink target path

Plugin JSON

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)
• Deleted files/skills on one machine will not be deleted on the other — only additions and modifications propagate
• Symlinked skills are resolved and copied as regular directories, so the synced version is a standalone snapshot independent of the original symlink target

Environment Variables

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

MIT