Documentation

Welcome to the vsync documentation! Here you’ll find everything you need to sync your AI coding tool configurations effortlessly.

What is vsync?

vsync is a powerful CLI tool that synchronizes configuration files across multiple AI coding tools (Claude Code, Cursor, OpenCode, and Codex). It provides:

Single Source of Truth: Choose one tool as your reference, others sync automatically
Smart Format Conversion: Handles JSON ↔ TOML ↔ JSONC conversions
Environment Variable Safety: Preserves variable syntax without expansion
Intelligent Diff Planning: Shows exactly what will change before applying
Safe & Prune Modes: Choose between conservative updates or strict mirroring

Getting Started

Getting Started - Installation, initialization, and first sync
Core Concepts - Understanding sync modes, layers, and workflows

Reference

Configuration - Config file structure and tool-specific formats
CLI Commands - Complete command reference with examples
Quick Reference - Command cheat sheet and common patterns

Advanced

Advanced Features - Symlinks, performance optimization, and more
FAQ - Common questions and troubleshooting

Supported AI Tools

vsync supports synchronization for the following AI coding tools:

Tool	Support Level	Config Format	Special Features
Claude Code	✅ Full (Source/Target)	JSON	Most complete feature set
Cursor	✅ Full (Source/Target)	JSON	Advanced variable interpolation
OpenCode	✅ Full (Source/Target)	JSONC	Comment preservation
Codex	✅ Full (Source/Target)	TOML	TOML format support

What Gets Synced?

vsync manages the following configuration types:

Skills: Reusable agent skill templates
MCP Servers: Model Context Protocol integrations
Agents: Custom AI agent definitions (v1.1+)
Commands: Quick command shortcuts (v1.1+)

Key Features

🎯 Smart Diff Planning

Preview exactly what will change before applying, with detailed reasons for each operation.

🛡️ Safe Mode (Default)

Only creates and updates configurations—never deletes unless explicitly requested.

⚡ Performance Optimized

Parallel operations for multiple targets
Hash-based change detection
Smart caching with manifest tracking

🔗 Symlink Support (v1.2+)

Optionally use symbolic links for Skills to save disk space and enable instant updates.

🌐 Multi-Language CLI (v1.2+)

Native support for English and Chinese (中文).

Quick Start


# Install
npm install -g @nicepkg/vsync
 
# Initialize
vsync init
 
# Sync
vsync sync

Getting Help

GitHub Issues: Report bugs or request features
CLI Help: Run vsync --help or vsync <command> --help
Contributing: Check out the Contributing Guide

Ready to get started? Head over to Getting Started!