CLSYNC

🔄 Sync your Claude Code environment across machines via GitHub

한국어

---

   ██████╗██╗     ███████╗██╗   ██╗███╗   ██╗ ██████╗
  ██╔════╝██║     ██╔════╝╚██╗ ██╔╝████╗  ██║██╔════╝
  ██║     ██║     ███████╗ ╚████╔╝ ██╔██╗ ██║██║
  ██║     ██║     ╚════██║  ╚██╔╝  ██║╚██╗██║██║
  ╚██████╗███████╗███████║   ██║   ██║ ╚████║╚██████╗
   ╚═════╝╚══════╝╚══════╝   ╚═╝   ╚═╝  ╚═══╝ ╚═════╝

Table of Contents

• Features
• Installation
• Quick Start
• CLI Reference
• Interactive Mode
• MCP Server
• Architecture
• Workflows
• License

---

✨ Features

Core Features

Feature	Description
🔄 GitHub Sync	Share and sync Claude Code settings via GitHub repositories
📦 Multi-Repo Support	Pull from multiple repositories and manage them independently
📤 Stage & Apply	Stage settings locally, apply them anywhere
🎯 Full Extension Support	Manage Skills, Agents, and Output Styles
🔀 Promote / Demote	Move settings between project and user scope
🔗 Link to Slash Commands	Convert skills/agents into explicit slash commands
🔍 Local Project Scan	Find and manage all .claude directories on your machine
🔌 MCP Integration	Native Claude Code integration via MCP Server (37 tools)

CLI Features

Feature	Description
🖥️ Interactive Mode	User-friendly menu when running clsync without arguments
📊 Status Dashboard	View staging area status and pulled repositories
🔍 Repository Browser	Browse GitHub repositories before pulling
📋 Scope Comparison	Compare user and project settings side-by-side
💡 Smart Hints	Helpful error messages with suggestions
📐 Responsive UI	Adapts to terminal window size

MCP Server Features

Feature	Description
📝 Create Settings	Create skills, subagents, output styles via AI
📖 Read Settings	Read and list existing settings
🔄 Sync Operations	Pull, apply, promote, demote via MCP tools
📚 Documentation Sync	Sync external documentation to Claude context

---

📦 Installation

npm install -g clsync

---

🚀 Quick Start

1. Initialize

clsync init

2. Pull Community Settings

# Browse a repository
clsync browse owner/repo

# Pull to local cache
clsync pull owner/repo

# Apply all to your ~/.claude
clsync apply --all -s owner/repo -u

3. Share Your Settings

# Stage your settings
clsync stage --all -u

# Export with metadata
clsync export ./my-settings -a "Your Name" -d "My Claude settings"

# Push to GitHub
cd my-settings && git init && git add . && git push

---

📖 CLI Reference

Basic Commands

Command	Description
clsync	Start interactive mode
clsync init	Initialize ~/.clsync directory
clsync status	Show staging area status
clsync --help	Show help with ASCII banner
clsync --version	Show version

Staging Commands

Command	Description
clsync stage [name]	Stage item to ~/.clsync/local
clsync stage --all -u	Stage all from ~/.claude
clsync stage --all -p	Stage all from .claude
clsync unstage <name>	Remove from staging
clsync list	List staged items

Apply Commands

Command	Description
clsync apply [name]	Apply from local staging
clsync apply [name] -s owner/repo	Apply from pulled repo
clsync apply --all -s owner/repo -u	Apply all to ~/.claude
clsync apply --all -s owner/repo -p	Apply all to .claude
clsync apply [name] -d /path	Apply to custom directory

Repository Commands

Command	Description
clsync pull <owner/repo>	Pull from GitHub
clsync pull <owner/repo> -f	Force overwrite
clsync browse <owner/repo>	Browse repo contents
clsync repos	List pulled repositories
clsync list <owner/repo>	List items in a repo

Scope Commands

Command	Description
clsync scopes	Compare user and project settings
clsync promote <name>	Move: .claude → ~/.claude
clsync promote <name> -f	Force overwrite
clsync promote <name> -r <new>	Rename to avoid conflict
clsync demote <name>	Move: ~/.claude → .claude

Link Commands

Command	Description
clsync link skill <name>	Link skill to slash command
clsync link agent <name>	Link subagent to slash command
clsync link --all	Link all skills and agents
clsync link --all --skills-only	Link only skills
clsync link --all --agents-only	Link only agents
clsync link skill <name> -p	Link in project scope
clsync link skill <name> -n <custom>	Link with custom command name

Scan Commands

Command	Description
clsync scan	Find all local .claude directories
clsync scan -p <dir>	Scan specific directory
clsync scan -c	Clear scan cache
clsync scan -i	Show cache info

Export Commands

Command	Description
clsync export <dir>	Export staging to directory
clsync export <dir> -a "Author"	With author name
clsync export <dir> -d "Desc"	With description

Sync Commands

Command	Description
clsync sync	Sync documentation from config
clsync sync -u	Sync to user level
clsync sync -f	Force overwrite
clsync sync -d	Dry run (preview)

---

🎮 Interactive Mode

Run clsync without arguments to enter interactive mode:

   ██████╗██╗     ███████╗██╗   ██╗███╗   ██╗ ██████╗
  ██╔════╝██║     ██╔════╝╚██╗ ██╔╝████╗  ██║██╔════╝
  ...
  📦 Local: 0 items  |  🔗 Repos: 2

? What would you like to do?
  1) 📊 View status
  2) 📦 Browse pulled repositories
  3) 📥 Apply items from repo
  4) 🔍 Pull new repository
  5) 🔀 Compare scopes (user vs project)
  6) ❓ Help
  7) 👋 Exit

Features:

• Browse and apply items with number selection
• Multi-select items to apply
• Pull new repositories interactively
• Compare scopes visually

---

🔌 MCP Server

Setup

claude mcp add clsync --transport stdio -- npx -y clsync-mcp

Available Tools (37 total)

Init & Status Tools

Tool	Description
init_clsync	Initialize ~/.clsync directory
get_status	Get current clsync status

Documentation Tools

Tool	Description
sync_docs	Sync documentation from configured sources
list_docs	List synced documentation files
read_doc	Read a documentation file

Creation Tools

Tool	Description
create_skill	Create a new skill with SKILL.md
create_subagent	Create a new subagent
create_output_style	Create a new output style

List & Read Tools

Tool	Description
list_skills	List skills (user/project/both)
read_skill	Read skill content
list_subagents	List subagents
read_subagent	Read subagent content
list_output_styles	List output styles

Stage & Unstage Tools

Tool	Description
stage_item	Stage item from ~/.claude or .claude
stage_all	Stage all items
unstage_item	Remove item from staging
list_staged	List staged items

Repository Tools

Tool	Description
pull_settings	Pull from GitHub repository
push_settings	Push to GitHub repository
browse_repo	Browse repository contents
list_repos	List pulled repositories

Apply Tools

Tool	Description
apply_setting	Apply setting from staging

Scope Tools

Tool	Description
promote_setting	Move project → user
demote_setting	Move user → project
compare_scopes	Compare user and project settings

Link Tools

Tool	Description
link_skill_to_command	Link skill to slash command
link_subagent_to_command	Link subagent to slash command
link_all_to_commands	Link all skills and agents

Export & Local Tools

Tool	Description
export_for_push	Export staged items for git push
link_local_repo	Link GitHub repo to local
unlink_local_repo	Unlink GitHub repo
get_local_info	Get local staging info

Online Registry Tools

Tool	Description
list_online_repos	List online registry repositories
pull_online_repo	Pull from online registry

Scan Tools

Tool	Description
scan_claude_dirs	Scan for .claude directories
get_scan_cache_info	Get scan cache information
clear_scan_cache	Clear scan cache

---

📐 Architecture

~/.claude/          ─┐
  ├── skills/        │
  ├── agents/        │     stage      ┌─────────────┐
  └── output-styles/ ├──────────►  ~/.clsync  ◄────►  GitHub
                     │              ├── local/        Repos
.claude/ (project)  ─┤              └── repos/
  ├── skills/        │                  └── owner/repo/
  └── ...           ─┘◄── apply ────┘

Directory Structure

~/.clsync/
├── manifest.json           # Metadata and repo tracking
├── local/                  # Your staged items
│   ├── skills/
│   ├── agents/
│   └── output-styles/
└── repos/                  # Pulled repositories
    ├── owner1/repo1/
    │   ├── clsync.json     # Repo metadata
    │   ├── skills/
    │   └── agents/
    └── owner2/repo2/

clsync.json Schema

{
  "$schema": "https://clsync.dev/schema/v1.json",
  "version": "0.2.0",
  "name": "my-settings",
  "description": "My Claude Code settings",
  "author": "username",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "items": [
    { "type": "skill", "name": "commit-msg", "path": "skills/commit-msg" }
  ],
  "stats": {
    "skills": 1,
    "agents": 0,
    "output_styles": 0,
    "total": 1
  }
}

---

🎯 Workflows

Personal: Sync Across Machines

Machine A (export):

clsync stage --all -u
clsync export ./my-settings -a "Me"
cd my-settings && git push

Machine B (import):

clsync pull user/my-settings
clsync apply --all -s user/my-settings -u

Team: Share Settings

# Team lead exports
clsync stage --all -u
clsync export ./team-settings -a "Team" -d "Shared team settings"

# Team members import
clsync pull team/settings
clsync apply --all -s team/settings -u

Community: Use Multiple Repos

clsync pull user1/awesome-skills
clsync pull user2/productivity-agents
clsync repos                              # View all
clsync apply code-reviewer -s user2/productivity-agents -u

Project: Manage Scopes

# View both scopes
clsync scopes

# Promote project setting to user (make global)
clsync promote my-skill

# Demote user setting to project (make local)
clsync demote my-agent

Link: Create Slash Commands

# Link a single skill to slash command
clsync link skill alarm
# Now use /alarm in Claude Code

# Link a subagent to slash command
clsync link agent code-reviewer
# Now use /code-reviewer in Claude Code

# Link all skills and agents at once
clsync link --all

# Link only skills
clsync link --all --skills-only

# Link in project scope
clsync link skill my-skill --project

Use Case: Convert auto-invoked skills into explicitly callable slash commands for more control.

---

🤝 Contributing

Pull requests and issues welcome!

📜 License

MIT © 2026 workromancer

---