Name	Name	Last commit message	Last commit date
Latest commit History 55 Commits
bin	bin
src	src
.gitignore	.gitignore
.npmignore	.npmignore
LICENSE	LICENSE
README.ko.md	README.ko.md
README.md	README.md
clsync.config.json	clsync.config.json
package-lock.json	package-lock.json
package.json	package.json

CLSYNC

🔄 Sync your Claude Code environment across machines via GitHub

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

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月01日T00:00:00.000Z",
 "updated_at": "2026年01月01日T00: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

Buy Me A Coffee

License

workromancer/clsync

Folders and files

Latest commit

History

Repository files navigation