Skip to Content
🚀 vsync v1.0 is here! Sync your AI tools effortlessly. Star us on GitHub
DocumentationAdvanced Features

Advanced Features

Explore advanced features and optimization techniques in vsync.

vsync can use symbolic links for Skills directories instead of copying files, providing instant updates and significant disk space savings.

When symlinks are enabled:

  1. Source tool Skills directory remains untouched
  2. Target tools get symlinks pointing to the source
  3. Changes in source are instantly visible in all targets
  4. No file duplication = disk space saved
~/.claude/skills/my-skill/  (Source - actual files)
       ↑
       ├── symlink from ~/.cursor/skills/my-skill/
       ├── symlink from ~/.opencode/skills/my-skill/
       └── symlink from ~/.codex/skills/my-skill/

During First Sync

On your first vsync sync, you’ll be prompted:

? How would you like to sync Skills?
  ❯ Use symlinks (recommended - instant updates, saves space)
    Copy files (traditional - independent copies)

Your choice is saved in .vsync.json.

Manual Configuration

Edit .vsync.json:

{
  "use_symlinks_for_skills": true
}

Benefits

✅ Instant Updates: Edit once in source, changes reflect everywhere ✅ Disk Space: One copy instead of N+1 copies ✅ Performance: Faster sync operations (no file copying) ✅ Simplicity: Single source of truth becomes literal

Limitations

⚠️ Platform Support: Requires OS support for symlinks (works on macOS, Linux, Windows 10+) ⚠️ Skills Only: Currently only Skills support symlinks (MCP, Agents, Commands still copied) ⚠️ Permission Issues: May require admin rights on some systems

Switching Between Modes

You can change the setting anytime:

# 1. Edit config
vim .vsync.json
# Change "use_symlinks_for_skills" to true/false
 
# 2. Re-sync to apply
vsync sync

vsync will handle the conversion automatically, replacing symlinks with copies or vice versa.

Performance Optimization

vsync is optimized for speed and efficiency.

Hash-Based Change Detection

Uses SHA256 hashes to detect changes:

  • Fast: No need to compare file contents
  • Accurate: Even tiny changes are detected
  • Efficient: Skip unchanged configs automatically
// Manifest tracks hashes
{
  "items": {
    "skill/my-skill": {
      "hash": "abc123...",
      "targets": {
        "cursor": "abc123..."
      }
    }
  }
}

Parallel Operations

Multiple targets are synced in parallel:

Source Read (1s)
    ↓
Diff Calculation (0.2s)
    ↓
Write to cursor (0.5s)  ─┐
Write to opencode (0.5s) ├─ Parallel (0.5s total)
Write to codex (0.5s)   ─┘
    ↓
Total: ~1.7s instead of 2.7s

Smart Caching

The manifest acts as a cache:

  • Skip files with matching hashes
  • Avoid redundant I/O operations
  • Incremental syncs are nearly instant

Atomic Writes

All writes use atomic operations:

  1. Write to temporary file
  2. fsync to disk
  3. Atomic rename

Result: Crash-safe, no partial writes

Multi-Language CLI (v1.2+)

vsync supports English and Chinese (中文) interfaces.

Setting Language

User-Level (Global)

Edit ~/.vsync.json:

{
  "language": "en"  // or "zh"
}

Environment Variable

export VIBE_SYNC_LANG=zh
vsync sync

Supported Languages

  • en - English (default)
  • zh - 简体中文 (Simplified Chinese)

Example Output

English:

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

中文:

📖 正在读取源配置 (claude-code)...
  ✓ 找到 3 个技能
  ✓ 找到 2 个 MCP 服务器

Advanced Sync Patterns

Selective Sync

Only sync specific config types:

{
  "sync_config": {
    "skills": true,
    "mcp": false,      // Don't sync MCP
    "agents": true,
    "commands": false  // Don't sync Commands
  }
}

Multi-Source Strategy

For complex setups, use multiple configs:

# Project has its own config
cd ~/my-project
vsync sync
 
# User has global config
vsync sync --user

Both layers can coexist—project configs don’t override user configs.

Temporary Source Switch

Need to import from a different tool temporarily?

# 1. Import from Cursor to current source
vsync import /path/to/cursor/project
 
# 2. Sync to targets
vsync sync

Your source tool remains unchanged; you’re just importing new items.

Environment Variable Management

Best Practices

  1. Never hardcode secrets:

    // ✅ Good
{ "API_KEY": "${API_KEY}" }
 
// ❌ Bad
{ "API_KEY": "sk-abc123" }

  2. Use defaults for local dev:

    {
  "DATABASE_URL": "${DATABASE_URL:-postgresql://localhost/dev}"
}

  3. Document required variables:

    // In your README.md
// Required environment variables:
// - API_KEY: Your API key
// - DATABASE_URL: Database connection string

Cross-Tool Variable Syntax

vsync automatically converts between tools:

Source (Claude Code)Target (Cursor)Target (OpenCode)
${VAR}${env:VAR}{env:VAR}
${VAR:-default}${env:VAR} (default lost){env:VAR} (default lost)

Note: Defaults are preserved only in Claude Code format.

Rollback and Safety

Automatic Rollback

If any error occurs during sync:

  1. All changes are rolled back automatically
  2. Original configs are restored from backups
  3. No partial sync state
✓ Backup created: cursor/mcp.json
✓ Backup created: opencode/opencode.json
❌ Error writing to opencode
⚠️  Rolling back all changes...
✅ Rollback complete - all files restored

Manual Rollback

If you need to undo a sync:

  1. Use version control (if configs are committed)
  2. Use system backups (Time Machine, etc.)
  3. Re-run sync with previous source state

CI/CD Integration

GitHub Actions

name: Sync AI Tool Configs
 
on:
  push:
    paths:
      - '.claude/**'
      - '.vsync.json'
 
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
 
      - name: Sync configs
        run: npx @nicepkg/vsync sync --yes
        env:
          # Add any required environment variables
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Pre-commit Hook

Automatically sync before commits:

#!/bin/bash
# .git/hooks/pre-commit
 
# Check if .vsync.json exists
if [ -f .vsync.json ]; then
  echo "Running vsync..."
  npx @nicepkg/vsync sync --yes
 
  # Add synced files to commit
  git add .cursor/ .opencode/ .codex/
fi

Watch Mode (Coming in v1.3)

Planned feature for automatic syncing on file changes:

# Auto-sync when source configs change
vsync watch

This will monitor source directories and trigger syncs automatically.

Debugging

Enable Debug Logging

Set environment variable:

export VIBE_SYNC_DEBUG=1
vsync sync

Verbose Output

vsync sync --verbose

Check Manifest

Inspect the manifest to see sync state:

cat .vsync-cache/manifest.json | jq

Performance Tips

  1. Use Symlinks: Significantly faster for Skills
  2. Commit Manifest: Helps with incremental syncs
  3. Selective Sync: Only sync what you need
  4. Run in Background: Use --yes flag for automation

Advanced Configuration Examples

Mixed Sync Strategy

{
  "sync_config": {
    "skills": true,      // Full sync
    "mcp": true,         // Full sync
    "agents": false,     // Skip (manual management)
    "commands": false    // Skip (manual management)
  },
  "use_symlinks_for_skills": true
}

Multi-Tool Development

# Project uses Claude Code + Cursor
cd ~/project-a
cat .vsync.json
{
  "source_tool": "claude-code",
  "target_tools": ["cursor"]
}
 
# Another project uses Cursor + OpenCode
cd ~/project-b
cat .vsync.json
{
  "source_tool": "cursor",
  "target_tools": ["opencode"]
}

Next Steps

Last updated on
Quick ReferenceFAQ