{"id":42239659,"url":"https://github.com/nicepkg/vsync","last_synced_at":"2026-02-01T13:00:50.070Z","repository":{"id":334720599,"uuid":"1142465755","full_name":"nicepkg/vsync","owner":"nicepkg","description":"Sync MCP servers, Skills, Agents \u0026 Commands across Claude Code, Cursor, OpenCode, Codex. One config, all tools.","archived":false,"fork":false,"pushed_at":"2026-01-27T03:27:42.000Z","size":1579,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-31T19:55:57.298Z","etag":null,"topics":["ai","ai-coding","ai-tools","automation","claude","claude-code","cli","codex","config-sync","cursor","developer-tools","devtools","mcp","mcp-server","nodejs","opencode","productivity","typescript"],"latest_commit_sha":null,"homepage":"https://vsync.xiaominglab.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nicepkg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["nicepkg"]}},"created_at":"2026-01-26T12:58:44.000Z","updated_at":"2026-01-30T00:41:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nicepkg/vsync","commit_stats":null,"previous_names":["nicepkg/vsync"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/nicepkg/vsync","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicepkg%2Fvsync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicepkg%2Fvsync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicepkg%2Fvsync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicepkg%2Fvsync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicepkg","download_url":"https://codeload.github.com/nicepkg/vsync/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicepkg%2Fvsync/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28978716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T12:13:08.691Z","status":"ssl_error","status_checked_at":"2026-02-01T12:13:08.356Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-coding","ai-tools","automation","claude","claude-code","cli","codex","config-sync","cursor","developer-tools","devtools","mcp","mcp-server","nodejs","opencode","productivity","typescript"],"created_at":"2026-01-27T04:03:01.205Z","updated_at":"2026-02-01T13:00:49.522Z","avatar_url":"https://github.com/nicepkg.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"website/public/icon.svg\" width=\"120\" height=\"120\" /\u003e\n\n# vsync\n\n### **One config. Many AI tools. Zero pain.**\n\n[![GitHub stars](https://img.shields.io/github/stars/nicepkg/vsync?style=social)](https://github.com/nicepkg/vsync)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/nicepkg/vsync/pulls)\n[![Tests](https://img.shields.io/badge/tests-612%20passing-brightgreen)](https://github.com/nicepkg/vsync)\n\n[简体中文](./README_cn.md) | English\n\n\u003cimg src=\"https://img.shields.io/badge/Claude_Code-Fully_Supported-blueviolet?style=for-the-badge\u0026logo=anthropic\" /\u003e\n\u003cimg src=\"https://img.shields.io/badge/Cursor-Fully_Supported-blue?style=for-the-badge\" /\u003e\n\u003cimg src=\"https://img.shields.io/badge/OpenCode-Fully_Supported-green?style=for-the-badge\" /\u003e\n\u003cimg src=\"https://img.shields.io/badge/Codex-Fully_Supported-orange?style=for-the-badge\" /\u003e\n\n---\n\n**One-command config sync for AI vibe coding tools**\n\nManaging Skills, MCP servers, Agents \u0026 Commands across multiple AI coding tools is a nightmare.\nEach tool has its own directories and formats. vsync solves this with one simple command.\n\n[Get Started](#-quick-start) · [Features](#-features) · [Documentation](https://vsync.xiaominglab.com)\n\n\u003c/div\u003e\n\n---\n\n## ✨ Why vsync?\n\n**The Problem**: You love using multiple AI vibe coding tools (Claude Code, Cursor, OpenCode, Codex...), but each tool has:\n\n- Different directory structures for Skills, Agents, Commands, MCP servers\n- Different config file formats (JSON, TOML, JSONC)\n- Different environment variable syntax\n\nManaging configurations across tools becomes a nightmare, especially for teams.\n\n**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.\n\n### The Problem We Solve\n\n| 😫 Without vsync                                                     | 🎉 With vsync                                                |\n| :------------------------------------------------------------------- | :----------------------------------------------------------- |\n| 📋 Manually copy configs between multiple vibe coding tools          | ⚡ One command syncs everything automatically                |\n| 📂 Different directories for Skills/Agents/Commands/MCP in each tool | 🎯 One command maps to all correct paths                     |\n| 🔥 Environment variables break during migration                      | 🛡️ Variables preserved safely (JSON ↔ TOML ↔ JSONC)          |\n| 🤷 No idea which configs are outdated or in conflict                 | 📊 Smart diff shows exactly what changed and why             |\n| ⚠️ Risky deletions, manual cleanup nightmares                        | ✅ Safe mode by default, Prune mode for strict mirroring     |\n| 🔧 Multiple tools = multiple config formats                          | 🎯 Transparent format conversion (preserves JSONC comments!) |\n| 🐌 Copying dozens of configs manually is painfully slow              | ⚡ Instant sync with parallel operations \u0026 smart caching     |\n\n### Key Benefits\n\n```\n📚  Single Source of Truth → All tools sync from one place\n🎯  Smart Diff Planning    → Preview changes before applying\n⚡  Safe \u0026 Prune Modes     → Choose your sync strategy\n🌈  Multi-Tool Support     → Claude Code, Cursor, OpenCode, Codex\n🗣️  Multi-Language CLI     → English \u0026 中文 (Chinese)\n⚡  Performance Optimized  → Parallel ops, caching, symlinks\n🔗  Symlink Support        → Share Skills via symlinks (optional)\n```\n\n### How It Works\n\n```mermaid\nflowchart TD\n    A[Pick Source Tool\u003cbr/\u003eYour source of truth] --\u003e B[vsync reads configs\u003cbr/\u003eSkills, MCP, Agents, Commands]\n    B --\u003e C[Compare with targets\u003cbr/\u003eCalculate differences]\n    C --\u003e D[Show you the plan\u003cbr/\u003eWhat will change]\n    D --\u003e E{Your approval}\n    E --\u003e|Yes| F[Auto-convert formats\u003cbr/\u003eJSON → TOML → JSONC]\n    E --\u003e|No| G[Cancelled]\n    F --\u003e H[Write to all targets\u003cbr/\u003eCrash-safe atomic writes]\n    H --\u003e I[✅ All tools synced!]\n\n    style A fill:#e1f5ff\n    style I fill:#c8e6c9\n    style E fill:#fff9c4\n```\n\n**The magic**: Edit configs in ONE tool → Run `vsync sync` → ALL tools stay in sync\n\n---\n\n## 🎯 Features\n\n| Feature               | Description                           | Status  |\n| :-------------------- | :------------------------------------ | :------ |\n| **Skills Sync**       | Sync Agent Skills across all tools    | ✅ v1.0 |\n| **MCP Sync**          | Sync MCP servers with security checks | ✅ v1.0 |\n| **Diff Planning**     | Preview changes before applying       | ✅ v1.0 |\n| **Safe Mode**         | Add \u0026 update only, no deletions       | ✅ v1.0 |\n| **Prune Mode**        | Strict mirroring with deletions       | ✅ v1.0 |\n| **Atomic Writes**     | All-or-nothing file operations        | ✅ v1.0 |\n| **Manifest Tracking** | Hash-based change detection           | ✅ v1.0 |\n| **User Layer**        | Global configs (~/.vsync.json)        | ✅ v1.1 |\n| **Agents Sync**       | Custom AI agents                      | ✅ v1.1 |\n| **Commands Sync**     | Quick commands                        | ✅ v1.1 |\n| **Codex Support**     | Full Codex integration (TOML format)  | ✅ v1.1 |\n| **Multi-Language**    | English \u0026 中文 CLI output             | ✅ v1.2 |\n| **Performance**       | Parallel operations, smart caching    | ✅ v1.2 |\n| **Symlinks**          | Symbolic link support                 | ✅ v1.2 |\n| **Import/Export**     | Share configs between projects        | ✅ v1.1 |\n\n---\n\n## ⚡ Quick Start\n\nFull documentation: https://vsync.xiaominglab.com\n\n### Installation\n\n```bash\n# Option 1: Run directly with npx (no installation needed)\nnpx @nicepkg/vsync\n\n# Option 2: Install globally with npm\nnpm install -g @nicepkg/vsync\n\n# Verify installation\nvsync --version\n```\n\n### Initialize\n\n```bash\n# Project-level configuration\nvsync init\n\n# User-level (global) configuration\nvsync init --user\n```\n\n**Interactive prompts:**\n\n```\n🚀 Welcome to vsync!\n\n✔ Detecting existing tools...\n✔ Detected: claude-code, cursor\n\n? Which AI coding tools do you use?\n  ◉ claude-code (detected)\n  ◉ cursor (detected)\n  ◯ opencode\n  ◯ codex\n\n? Which tool is your source of truth?\n  ❯ claude-code\n\n? What do you want to sync?\n  ◉ Skills\n  ◉ MCP\n\n✔ Configuration created\n✔ Cache directory created\n✔ Manifest initialized\n\n✅ Setup complete! Run vsync sync to start syncing\n```\n\n### Sync Your Configs\n\n```bash\n# Safe mode (default: no deletions)\nvsync sync\n\n# Preview changes without applying\nvsync sync --dry-run\n\n# Strict mirroring (deletes extra items in targets)\nvsync sync --prune\n```\n\n**Example output:**\n\n```\n📖 Reading source (claude-code)...\n  ✓ Found 3 skills\n  ✓ Found 2 MCP servers\n\n📊 Analyzing differences...\n\n📋 Sync Plan (Safe Mode)\n\ncursor:\n  CREATE:\n    • skill/deploy-prod\n  UPDATE:\n    • skill/git-release\n    • mcp/github\n\n? Proceed with sync? (Y/n) y\n\n✓ Sync completed in 1.2s\n```\n\n### Real-World Usage\n\n**Scenario 1: Team Onboarding**\n\n```bash\n# New team member joins, already has Claude Code setup\ncd my-project\nvsync init  # Choose Claude Code as source, Cursor \u0026 OpenCode as targets\nvsync sync  # Boom! All tools configured in seconds\n\n# Their entire AI coding environment is now in sync with the team\n```\n\n**Scenario 2: User-Level Config Sync Across Multiple Tools**\n\n```bash\n# Set up your global personal configs once\nvsync init --user  # Configure which tools to sync\nvsync sync --user  # Sync your personal Skills, MCP servers, Agents globally\n\n# Now ALL your tools share the same user-level configs\n# Works across all your projects automatically\n```\n\n**Scenario 3: Migration from One Tool to Another**\n\n```bash\n# Moving from Cursor to Claude Code?\nvsync init  # Choose Cursor as SOURCE (the reference/standard)\n                # Choose Claude Code as TARGET (will pull from source)\nvsync sync  # All your skills, MCP servers, agents migrated instantly\n\n# SOURCE = Your standard reference (everything syncs FROM here)\n# TARGET = Will match the source (everything syncs TO here)\n```\n\n---\n\n## 🛠 CLI Commands\n\n### Core Commands\n\n```bash\n# Initialize configuration\nvsync init [--user]\n\n# Sync configurations\nvsync sync [--user] [--dry-run] [--prune]\n\n# View sync plan without executing\nvsync plan [--user]\n\n# Check sync status\nvsync status [--user]\n\n# List configurations\nvsync list [skills|mcp] [--user]\n\n# Clean configs from targets\nvsync clean [name] [--user] [--from-source]\n\n# Import from another project\nvsync import \u003cpath\u003e [--user]\n```\n\n### Example Workflows\n\n**1. Daily sync after updating Skills:**\n\n```bash\n# Edit your Skills in Claude Code\nvim ~/.claude/skills/my-skill/SKILL.md\n\n# Sync to all target tools\nvsync sync\n```\n\n**2. Preview changes before applying:**\n\n```bash\nvsync plan\n# Review the plan\nvsync sync\n```\n\n**3. Strict mirror mode (delete outdated configs):**\n\n```bash\nvsync sync --prune\n```\n\n**4. Clean up a skill from all targets:**\n\n```bash\n# From targets only (source unchanged)\nvsync clean skill/old-skill\n\n# From source AND all targets (dangerous!)\nvsync clean skill/old-skill --from-source\n```\n\n**5. Import configs from another project:**\n\n```bash\nvsync import ../other-project\n```\n\n---\n\n## 📋 Configuration\n\n### .vsync.json\n\n**Project-level:** `\u003cproject\u003e/.vsync.json`\n**User-level:** `~/.vsync.json`\n\n```json\n{\n  \"version\": \"1.0.0\",\n  \"level\": \"project\",\n  \"source_tool\": \"claude-code\",\n  \"target_tools\": [\"cursor\", \"opencode\", \"codex\"],\n  \"sync_config\": {\n    \"skills\": true,\n    \"mcp\": true\n  },\n  \"use_symlinks_for_skills\": false,\n  \"language\": \"en\"\n}\n```\n\n**Key Settings**:\n\n- `source_tool`: Your source of truth (where you edit configs)\n- `target_tools`: Tools that will sync FROM the source\n- `sync_config`: What to sync (skills, mcp, agents, commands)\n- `use_symlinks_for_skills`: Use symlinks instead of copying (saves disk space)\n- `language`: CLI language - `\"en\"` or `\"zh\"` (user-level only)\n\n### Config Format Differences (Why You Need vsync)\n\nEach vibe coding tool uses different formats AND different directory structures. vsync handles all the complexity:\n\n**Directory Structure Differences**:\n| Config Type | Claude Code | Cursor | OpenCode | Codex |\n|:------------|:------------|:-------|:---------|:------|\n| **Skills** | `.claude/skills/` | `.cursor/skills/` | `.opencode/skills/` | `.codex/skills/` |\n| **Agents** | `.claude/agents/` | N/A | `.opencode/agents/` | N/A |\n| **Commands** | `.claude/commands/` | `.cursor/commands/` | `.opencode/commands/` | N/A |\n| **MCP Config** | `.mcp.json` | `mcp.json` | `opencode.json(c)` | `config.toml` |\n\n**File Format Differences**:\n| Aspect | Claude Code | Cursor | OpenCode | Codex |\n|:-------|:------------|:-------|:---------|:------|\n| **Format** | JSON | JSON | JSONC (with comments) | TOML |\n| **MCP Field Name** | `mcpServers` | `mcpServers` | `mcp` ⚠️ | `mcp_servers` |\n| **Env Var Syntax** | `${VAR}` | `${env:VAR}` | `{env:VAR}` | No interpolation |\n| **Type Field** | Not required | Not required | **Required** (`local`/`remote`) | Required |\n\n**Without vsync**:\n\n- ❌ Manually copy files between different directories\n- ❌ Remember which tool uses which path\n- ❌ Convert environment variable syntax by hand\n- ❌ Often break configs or forget required fields\n\n**With vsync**:\n\n- ✅ One command → auto-syncs to all tools\n- ✅ Automatic format conversion\n- ✅ Skills support symlinks (optional)\n\n### Advanced Features (v1.2+)\n\n**Performance Optimizations**:\n\n- ⚡ **Parallel Operations**: Sync to multiple targets simultaneously\n- 💾 **Smart Caching**: Skip unchanged configs using hash-based manifest\n- 🔗 **Symlink Support**: Follows symbolic links correctly\n- 📦 **Optimized I/O**: Atomic writes with fsync for crash safety\n\n**Format Intelligence**:\n\n- 🎯 **TOML Support**: Full Codex config.toml handling\n- 💬 **JSONC Preservation**: Keeps comments in OpenCode configs\n- 🔄 **Cross-Format Variables**: Converts `${VAR}` ↔ `${env:VAR}` ↔ `{env:VAR}` automatically\n- 🛡️ **Variable Safety**: Never expands environment variables, preserves syntax\n\n## 🎨 Sync Modes\n\n### Safe Mode (Default)\n\n**What it does:**\n\n- ✅ Create new items\n- ✅ Update existing items\n- ❌ **Never deletes**\n\n```bash\nvsync sync\n```\n\n### Prune Mode\n\n**What it does:**\n\n- ✅ Create new items\n- ✅ Update existing items\n- ⚠️ **Deletes items not in source**\n\n```bash\nvsync sync --prune\n```\n\n**Use when:** You want strict mirroring (e.g., cleaning up old configs)\n\n## ❓ FAQ\n\n**Q: Which tool should I use as the source?**\nA: We recommend **Claude Code** as it has the most complete feature set. However, you can use any tool as your source.\n\n**Q: Will vsync overwrite my existing configs?**\nA: By default, **Safe Mode** only creates and updates—it never deletes. Use `--prune` if you want strict mirroring.\n\n**Q: What happens if I edit configs directly in target tools?**\nA: Changes in target tools will be overwritten on the next sync. The SOURCE is your reference standard—everything syncs FROM the source. Always edit in your source tool, or use `import` to pull changes from another project.\n\n**Q: How do I switch my source tool?**\nA: Run `vsync init` again and choose a different source. Then sync to update all targets.\n\n**Q: Does it work with monorepos?**\nA: Yes! Each project can have its own `.vsync.json`. User-level configs (`~/.vsync.json`) work globally.\n\n**Q: Is it safe to commit `.vsync.json` to git?**\nA: Yes! The config file contains no secrets—only tool names and sync preferences. MCP configs with secrets should use environment variables.\n\n**Q: Can I sync in both directions?**\nA: vsync is one-directional (source → targets). To switch directions, re-run `init` and choose a different source tool.\n\n**Q: What's the difference between project-level and user-level?**\nA:\n\n- **Project-level** (`.vsync.json`): Team configs, checked into git\n- **User-level** (`~/.vsync.json`): Personal global configs, not shared\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Here's how you can help:\n\n- ⭐ **Star this repo** - Help others discover this project\n- 🐛 **Report bugs** - Open an issue if something isn't working\n- 💡 **Suggest features** - What would make this better for you?\n- 🔧 **Submit PRs** - Improve code, docs, or add features\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n### Development\n\nWant to contribute? See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.\n\n### Contributors\n\n\u003ca href=\"https://github.com/nicepkg/vsync/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=nicepkg/vsync\" /\u003e\n\u003c/a\u003e\n\n---\n\n## 📚 Roadmap\n\n### v1.0 (MVP) ✅ Released\n\n- [x] Skills sync (with full file support)\n- [x] MCP sync with security checks\n- [x] Safe \u0026 Prune modes\n- [x] Intelligent diff planning\n- [x] Claude Code, Cursor, OpenCode support\n- [x] Atomic writes \u0026 crash safety\n- [x] Hash-based manifest system\n\n### v1.1 ✅ Released\n\n- [x] User-level configs (~/.vsync.json)\n- [x] Agents sync (custom AI agents)\n- [x] Commands sync (quick commands)\n- [x] Full Codex support (TOML format)\n- [x] Import command (share configs between projects)\n- [x] Clean command enhancements\n\n### v1.2 ✅ Current\n\n- [x] Multi-language support (English \u0026 中文)\n- [x] Performance optimizations (parallel ops, caching)\n- [x] Symbolic link support\n- [x] 612 tests passing (45 test files)\n- [x] Production-ready stability\n\n### v1.3 🔜 Next (Watch Mode \u0026 Automation)\n\n- [ ] Watch mode (auto-sync on file changes)\n- [ ] GitHub Actions integration\n- [ ] Pre-commit hooks\n- [ ] Validation improvements\n\n### v2.0 🚀 Future\n\n- [ ] Web UI dashboard\n- [ ] Configuration templates\n- [ ] VS Code extension\n- [ ] Plugin system\n\n---\n\n## 📄 License\n\nMIT © [nicepkg](https://github.com/nicepkg)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**If this project helped you, please consider giving it a ⭐**\n\n\u003ca href=\"https://github.com/nicepkg/vsync\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/stars/nicepkg/vsync?style=for-the-badge\u0026logo=github\u0026color=yellow\" alt=\"GitHub stars\" /\u003e\n\u003c/a\u003e\n\nMade with ❤️ by [nicepkg](https://github.com/nicepkg)\n\n\u003c/div\u003e\n","funding_links":["https://github.com/sponsors/nicepkg"],"categories":["Multi-Agent \u0026 Orchestration",":tada: New","Tools","Agent Infrastructure"],"sub_categories":["Other IDEs","Development Tools","Configuration \u0026 Context Management"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicepkg%2Fvsync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicepkg%2Fvsync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicepkg%2Fvsync/lists"}