Frequently Asked Questions

Common questions and answers about using vsync.

General Questions

Which tool should I use as the source?

We recommend Claude Code because:

Most complete feature set (Skills, MCP, Agents, Commands)
Clean JSON format
Well-documented
Active development

However, you can use any supported tool as your source. The choice depends on:

Which tool you primarily use for editing configs
Which tool has the most complete setup currently
Team preferences and workflow

Will vsync overwrite my existing configs?

By default, Safe Mode only creates and updates—it never deletes. Your existing configs in target tools will be updated to match the source, but nothing is removed unless you use --prune mode.

Important: Changes made directly in target tools will be overwritten on the next sync. Always edit in your source tool.

What happens if I edit configs directly in target tools?

Changes in target tools will be overwritten on the next sync. vsync uses a unidirectional sync model:


Source (Your edits) → Targets (Auto-updated)

Best practice: Always edit in your source tool, or use import to pull changes from another project.

How do I switch my source tool?

Simply re-run the init command:


vsync init
# Choose a different source tool

Then sync to update all targets with the new source.

Does it work with monorepos?

Yes! Each project can have its own .vsync.json. User-level configs (~/.vsync.json) work globally across all projects.

Example structure:


monorepo/
├── packages/
│   ├── frontend/
│   │   └── .vsync.json  # Frontend-specific config
│   └── backend/
│       └── .vsync.json  # Backend-specific config
└── .vsync.json          # Monorepo root config

Is it safe to commit `.vsync.json` to git?

Yes! The config file contains:

Tool names
Sync preferences
No secrets or credentials

MCP configs with secrets should use environment variables like ${API_KEY}, which are safe to commit.

Can I sync in both directions?

No, vsync is unidirectional (source → targets). This is intentional to maintain a clear source of truth.

To switch directions:

Run vsync init
Choose a different source tool
Sync to update targets

Configuration Questions

What’s the difference between project-level and user-level?

Project-Level (.vsync.json):

Team configs shared via git
Project-specific Skills and integrations
Scoped to one project directory

User-Level (~/.vsync.json):

Personal global configs
Works across all projects
Not shared with team
Ideal for personal preferences and global Skills

Can I use both project and user level configs?

Yes! They operate independently:


# Sync project configs
vsync sync
 
# Sync user configs
vsync sync --user

Project configs don’t override user configs—they’re separate layers.

How do I exclude specific tools?

Just don’t include them in target_tools:


{
  "source_tool": "claude-code",
  "target_tools": ["cursor"]  // Only sync to Cursor, not OpenCode
}

Sync Behavior Questions

What happens in Safe Mode vs Prune Mode?

Safe Mode (default):


Source: A, B, C
Target: A, B, D
Result: A, B, C, D  (D is kept)

Prune Mode:


Source: A, B, C
Target: A, B, D
Result: A, B, C  (D is deleted)

How do I know what changed?

Use the plan command to see a detailed preview:


vsync plan

Or use --dry-run with sync:


vsync sync --dry-run

Both show exactly what will be created, updated, deleted, or skipped.

Can I review changes before they’re applied?

Yes! By default, vsync sync shows a plan and asks for confirmation:


📋 Sync Plan (Safe Mode)

cursor:
  CREATE: 1 item
  UPDATE: 2 items

? Proceed with sync? (Y/n)

Use -y/--yes to skip confirmation (useful for automation).

MCP Questions

Why do environment variables look different in each tool?

Each tool has its own variable interpolation syntax:

Tool	Syntax	Example
Claude Code	`${VAR}`	`${API_KEY}`
Cursor	`${env:VAR}`	`${env:API_KEY}`
OpenCode	`{env:VAR}`	`{env:API_KEY}`
Codex	No interpolation	Direct values only

vsync automatically converts between these formats.

Will vsync expose my secrets?

No! vsync:

Never expands environment variables
Preserves variable references as-is
Only converts syntax between formats
Doesn’t read actual environment values

Example:


// Before sync (source)
{ "TOKEN": "${API_TOKEN}" }
 
// After sync (target)
{ "TOKEN": "${env:API_TOKEN}" }  // Reference preserved, not expanded

Can I use defaults for environment variables?

Yes, but with limitations:


// Claude Code (supports defaults)
{
  "env": {
    "PORT": "${PORT:-3000}"
  }
}

Note: Cursor and OpenCode don’t support defaults, so they’ll be converted to simple variable references:


// Synced to Cursor (default syntax lost)
{
  "env": {
    "PORT": "${env:PORT}"
  }
}

Skills and Agents Questions

Can I sync Skills with custom files?

Yes! Skills can include multiple files:


my-skill/
├── SKILL.md           # Main skill file
├── template.md        # Supporting file
├── examples/          # Supporting directory
│   └── good.md
└── scripts/
    └── helper.sh

All files are synced together (or symlinked if enabled).

What’s the difference between Skills and Agents?

Skills: Reusable instruction templates (supported by all tools)
Agents: Custom AI agent definitions (Claude Code, OpenCode only)

Both are synced similarly, but Agents have limited tool support.

Can I sync Cursor Rules?

Cursor Rules (.cursorrules files) are currently not supported. vsync focuses on:

Skills
MCP servers
Agents
Commands

Future versions may add Rules support based on demand.

Troubleshooting

”Config file not found” Error

Solution: Run vsync init to create configuration.


vsync init

”Permission denied” Errors

Causes:

Target directories don’t have write permissions
Symlinks require admin rights (on some systems)

Solutions:

Check directory permissions: ls -la ~/.cursor/
On Windows, run as Administrator for symlinks
Use copy mode instead: "use_symlinks_for_skills": false

”Tool not detected” During Init

Cause: Tool’s config directory doesn’t exist.

Solution: Create the directory first:


mkdir -p ~/.cursor
vsync init

Sync Hangs or Times Out

Possible causes:

Large Skills with many files
Network issues (if reading from remote directories)
File system performance

Solutions:

Use --dry-run to test without writing
Check system resources
Try syncing fewer items

Format Conversion Issues

Symptom: Synced configs don’t work in target tool.

Common issues:

Environment variables not set in target environment
Command paths differ between systems
OpenCode missing required type field

Solution: Verify the generated config manually:


# Check what was written
cat .cursor/mcp.json
cat .opencode/opencode.json
cat .codex/config.toml

Migration Questions

How do I migrate from manual config management?

Choose your most complete tool as source
Run vsync init and select that tool
Run vsync sync to populate targets
Verify configs in target tools
Start editing only in source tool going forward

Can I migrate between projects?

Yes, use the import command:


cd new-project
vsync import ../old-project

This copies configs from the old project to your source tool, then you can sync to targets.

What about migrating from other sync tools?

vsync doesn’t directly import from other sync tools, but you can:

Manually copy configs to one of the supported tools
Use that tool as source
Initialize vsync
Sync to other tools

Performance Questions

How fast is vsync?

Typical sync times:

First sync: 1-3 seconds (copying files)
Incremental syncs: 0.5-1 second (hash-based skipping)
With symlinks: 0.3-0.5 seconds (no copying)

Performance depends on:

Number of items
File sizes
Disk speed
Number of target tools

Does vsync cache anything?

Yes! The manifest (.vsync-cache/manifest.json) acts as a cache:

Stores SHA256 hashes of all items
Enables fast change detection
Allows incremental syncs

Can I speed up syncs?

Enable symlinks: "use_symlinks_for_skills": true
Commit manifest: Include .vsync-cache/ in git
Use selective sync: Only sync what you need
Use —yes flag: Skip confirmation prompts

Still Have Questions?

GitHub Issues: Ask a question
Documentation: Browse other docs sections
CLI Help: Run vsync --help