vsync

One config. Many AI tools. Zero pain.

One-command config sync for AI vibe coding tools

Managing Skills, MCP servers, Agents & Commands across multiple AI coding tools is a nightmare. Each tool has its own directories and formats. vsync solves this with one simple command.

Get Started · Features · Documentation

</div>

✨ Why vsync?

The Problem: You love using multiple AI vibe coding tools (Claude Code, Cursor, OpenCode, Codex...), but each tool has:

Different directory structures for Skills, Agents, Commands, MCP servers
Different config file formats (JSON, TOML, JSONC)
Different environment variable syntax

Managing configurations across tools becomes a nightmare, especially for teams.

The Solution: vsync gives you one command to sync everything. Pick one tool as your source of truth, and all others stay perfectly in sync.

The Problem We Solve

| 😫 Without vsync | 🎉 With vsync | | :------------------------------------------------------------------- | :----------------------------------------------------------- | | 📋 Manually copy configs between multiple vibe coding tools | ⚡ One command syncs everything automatically | | 📂 Different directories for Skills/Agents/Commands/MCP in each tool | 🎯 One command maps to all correct paths | | 🔥 Environment variables break during migration | 🛡️ Variables preserved safely (JSON ↔ TOML ↔ JSONC) | | 🤷 No idea which configs are outdated or in conflict | 📊 Smart diff shows exactly what changed and why | | ⚠️ Risky deletions, manual cleanup nightmares | ✅ Safe mode by default, Prune mode for strict mirroring | | 🔧 Multiple tools = multiple config formats | 🎯 Transparent format conversion (preserves JSONC comments!) | | 🐌 Copying dozens of configs manually is painfully slow | ⚡ Instant sync with parallel operations & smart caching |

Key Benefits

📚  Single Source of Truth → All tools sync from one place
🎯  Smart Diff Planning    → Preview changes before applying
⚡  Safe & Prune Modes     → Choose your sync strategy
🌈  Multi-Tool Support     → Claude Code, Cursor, OpenCode, Codex
🗣️  Multi-Language CLI     → English & 中文 (Chinese)
⚡  Performance Optimized  → Parallel ops, caching, symlinks
🔗  Symlink Support        → Share Skills via symlinks (optional)

How It Works

flowchart TD
    A[Pick Source Tool<br/>Your source of truth] --> B[vsync reads configs<br/>Skills, MCP, Agents, Commands]
    B --> C[Compare with targets<br/>Calculate differences]
    C --> D[Show you the plan<br/>What will change]
    D --> E{Your approval}
    E -->|Yes| F[Auto-convert formats<br/>JSON → TOML → JSONC]
    E -->|No| G[Cancelled]
    F --> H[Write to all targets<br/>Crash-safe atomic writes]
    H --> I[✅ All tools synced!]

    style A fill:#e1f5ff
    style I fill:#c8e6c9
    style E fill:#fff9c4

The magic: Edit configs in ONE tool → Run vsync sync → ALL tools stay in sync

🎯 Features

⚡ Quick Start

Full documentation: https://vsync.xiaominglab.com

Installation

# Option 1: Run directly with npx (no installation needed)
npx @nicepkg/vsync

# Option 2: Install globally with npm
npm install -g @nicepkg/vsync

# Verify installation
vsync --version

Initialize

# Project-level configuration
vsync init

# User-level (global) configuration
vsync init --user

Interactive prompts:

🚀 Welcome to vsync!

✔ Detecting existing tools...
✔ Detected: claude-code, cursor

? Which AI coding tools do you use?
  ◉ claude-code (detected)
  ◉ cursor (detected)
  ◯ opencode
  ◯ codex

? Which tool is your source of truth?
  ❯ claude-code

? What do you want to sync?
  ◉ Skills
  ◉ MCP

✔ Configuration created
✔ Cache directory created
✔ Manifest initialized

✅ Setup complete! Run vsync sync to start syncing

Sync Your Configs

# Safe mode (default: no deletions)
vsync sync

# Preview changes without applying
vsync sync --dry-run

# Strict mirroring (deletes extra items in targets)
vsync sync --prune

Example output:

📖 Reading source (claude-code)...
  ✓ Found 3 skills
  ✓ Found 2 MCP servers

📊 Analyzing differences...

📋 Sync Plan (Safe Mode)

cursor:
  CREATE:
    • skill/deploy-prod
  UPDATE:
    • skill/git-release
    • mcp/github

? Proceed with sync? (Y/n) y

✓ Sync completed in 1.2s

Real-World Usage

Scenario 1: Team Onboarding

# New team member joins, already has Claude Code setup
cd my-project
vsync init  # Choose Claude Code as source, Cursor & OpenCode as targets
vsync sync  # Boom! All tools configured in seconds

# Their entire AI coding environment is now in sync with the team

Scenario 2: User-Level Config Sync Across Multiple Tools

# Set up your global personal configs once
vsync init --user  # Configure which tools to sync
vsync sync --user  # Sync your personal Skills, MCP servers, Agents globally

# Now ALL your tools share the same user-level configs
# Works across all your projects automatically

Scenario 3: Migration from One Tool to Another

# Moving from Cursor to Claude Code?
vsync init  # Choose Cursor as SOURCE (the reference/standard)
                # Choose Claude Code as TARGET (will pull from source)
vsync sync  # All your skills, MCP servers, agents migrated instantly

# SOURCE = Your standard reference (everything syncs FROM here)
# TARGET = Will match the source (everything syncs TO here)

🛠 CLI Commands

Core Commands

# Initialize configuration
vsync init [--user]

# Sync configurations
vsync sync [--user] [--dry-run] [--prune]

# View sync plan without executing
vsync plan [--user]

# Check sync status
vsync status [--user]

# List configurations
vsync list [skills|mcp] [--user]

# Clean configs from targets
vsync clean [name] [--user] [--from-source]

# Import from another project
vsync import <path> [--user]

Example Workflows

1. Daily sync after updating Skills:

# Edit your Skills in Claude Code
vim ~/.claude/skills/my-skill/SKILL.md

# Sync to all target tools
vsync sync

2. Preview changes before applying:

vsync plan
# Review the plan
vsync sync

3. Strict mirror mode (delete outdated configs):

vsync sync --prune

4. Clean up a skill from all targets:

# From targets only (source unchanged)
vsync clean skill/old-skill

# From source AND all targets (dangerous!)
vsync clean skill/old-skill --from-source

5. Import configs from another project:

vsync import ../other-project

📋 Configuration

.vsync.json

Project-level: <project>/.vsync.json User-level: ~/.vsync.json

{
  "version": "1.0.0",
  "level": "project",
  "source_tool": "claude-code",
  "target_tools": ["cursor", "opencode", "codex"],
  "sync_config": {
    "skills": true,
    "mcp": true
  },
  "use_symlinks_for_skills": false,
  "language": "en"
}

Key Settings:

source_tool: Your source of truth (where you edit configs)
target_tools: Tools that will sync FROM the source
sync_config: What to sync (skills, mcp, agents, commands)
use_symlinks_for_skills: Use symlinks instead of copying (saves disk space)
language: CLI language - "en" or "zh" (user-level only)

Config Format Differences (Why You Need vsync)

Each vibe coding tool uses different format

Vsync

Install / Use

README