Skip to content

README.ko.md

Latest commit

 

History

History
493 lines (372 loc) · 16.8 KB

README.ko.md

File metadata and controls

493 lines (372 loc) · 16.8 KB

CLSYNC

npm version license node version MCP

🔄 GitHub을 통해 Claude Code 환경을 동기화하세요

English 

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

목차

✨ 주요 기능

핵심 기능

기능 설명
🔄 GitHub 동기화 GitHub 리포지토리를 통해 Claude Code 설정 공유 및 동기화
📦 멀티 리포 지원 여러 리포지토리에서 독립적으로 풀 및 관리
📤 Stage & Apply 로컬에서 스테이지, 어디서나 적용
🎯 전체 확장 지원 Skills, Agents, Output Styles 모두 관리
🔀 Promote / Demote 프로젝트와 사용자 스코프 간 설정 이동
🔗 슬래시 명령어로 연결 Skills/Agents를 명시적 슬래시 명령어로 변환
🔍 로컬 프로젝트 스캔 컴퓨터의 모든 .claude 디렉토리 찾기 및 관리
🔌 MCP 통합 MCP 서버를 통한 Claude Code 네이티브 통합 (37개 도구)

CLI 기능

기능 설명
🖥️ 인터랙티브 모드 clsync 단독 실행 시 사용자 친화적 메뉴
📊 상태 대시보드 스테이징 영역 상태 및 풀한 리포 확인
🔍 리포 브라우저 풀하기 전 GitHub 리포지토리 탐색
📋 스코프 비교 사용자/프로젝트 설정 나란히 비교
💡 스마트 힌트 제안이 포함된 친절한 에러 메시지
📐 반응형 UI 터미널 창 크기에 맞게 조절

MCP 서버 기능

기능 설명
📝 설정 생성 AI를 통해 skills, subagents, output styles 생성
📖 설정 읽기 기존 설정 읽기 및 목록 조회
🔄 동기화 작업 MCP 도구를 통한 pull, apply, promote, demote
📚 문서 동기화 외부 문서를 Claude 컨텍스트로 동기화

📦 설치

npm install -g clsync

🚀 빠른 시작

1. 초기화

clsync init

2. 커뮤니티 설정 가져오기

# 리포지토리 탐색
clsync browse owner/repo

# 로컬 캐시로 풀
clsync pull owner/repo

# ~/.claude에 모두 적용
clsync apply --all -s owner/repo -u

3. 내 설정 공유하기

# 설정 스테이지
clsync stage --all -u

# 메타데이터와 함께 내보내기
clsync export ./my-settings -a "Your Name" -d "My Claude settings"

# GitHub에 푸시
cd my-settings && git init && git add . && git push

📖 CLI 레퍼런스

기본 명령어

명령어 설명
clsync 인터랙티브 모드 시작
clsync init ~/.clsync 디렉터리 초기화
clsync status 스테이징 영역 상태 표시
clsync --help ASCII 배너와 함께 도움말 표시
clsync --version 버전 표시

스테이징 명령어

명령어 설명
clsync stage [name] ~/.clsync/local로 스테이지
clsync stage --all -u ~/.claude에서 모두 스테이지
clsync stage --all -p .claude에서 모두 스테이지
clsync unstage <name> 스테이징에서 제거
clsync list 스테이지된 항목 목록

적용 명령어

명령어 설명
clsync apply [name] 로컬 스테이징에서 적용
clsync apply [name] -s owner/repo 풀한 리포에서 적용
clsync apply --all -s owner/repo -u ~/.claude에 모두 적용
clsync apply --all -s owner/repo -p .claude에 모두 적용
clsync apply [name] -d /path 커스텀 디렉터리에 적용

리포지토리 명령어

명령어 설명
clsync pull <owner/repo> GitHub에서 풀
clsync pull <owner/repo> -f 강제 덮어쓰기
clsync browse <owner/repo> 리포 내용 탐색
clsync repos 풀한 리포지토리 목록
clsync list <owner/repo> 리포의 항목 목록

스코프 명령어

명령어 설명
clsync scopes 사용자/프로젝트 설정 비교
clsync promote <name> 이동: .claude → ~/.claude
clsync promote <name> -f 강제 덮어쓰기
clsync promote <name> -r <new> 충돌 방지를 위해 이름 변경
clsync demote <name> 이동: ~/.claude → .claude

연결 명령어

명령어 설명
clsync link skill <name> Skill을 슬래시 명령어로
clsync link agent <name> Subagent를 슬래시 명령어로
clsync link --all 모든 skills/agents 연결
clsync link --all --skills-only Skills만 연결
clsync link --all --agents-only Agents만 연결
clsync link skill <name> -p 프로젝트 스코프에서 연결
clsync link skill <name> -n <custom> 커스텀 명령어 이름으로

스캔 명령어

명령어 설명
clsync scan 로컬 .claude 디렉토리 찾기
clsync scan -p <dir> 특정 디렉토리 스캔
clsync scan -c 스캔 캐시 삭제
clsync scan -i 캐시 정보 표시

내보내기 명령어

명령어 설명
clsync export <dir> 스테이징을 디렉터리로 내보내기
clsync export <dir> -a "작성자" 작성자 이름 포함
clsync export <dir> -d "설명" 설명 포함

동기화 명령어

명령어 설명
clsync sync 설정에서 문서 동기화
clsync sync -u 사용자 레벨로 동기화
clsync sync -f 강제 덮어쓰기
clsync sync -d 드라이 런 (미리보기)

🎮 인터랙티브 모드

인자 없이 clsync를 실행하면 인터랙티브 모드로 진입합니다:

   ██████╗██╗     ███████╗██╗   ██╗███╗   ██╗ ██████╗
  ██╔════╝██║     ██╔════╝╚██╗ ██╔╝████╗  ██║██╔════╝
  ...
  📦 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

기능:

  • 번호 선택으로 항목 탐색 및 적용
  • 다중 선택으로 여러 항목 적용
  • 인터랙티브하게 새 리포 풀
  • 스코프 시각적 비교

🔌 MCP 서버

설정

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

사용 가능한 도구 (총 37개)

초기화 및 상태 도구

도구 설명
init_clsync ~/.clsync 디렉터리 초기화
get_status 현재 clsync 상태 확인

문서 도구

도구 설명
sync_docs 설정된 소스에서 문서 동기화
list_docs 동기화된 문서 파일 목록
read_doc 문서 파일 읽기

생성 도구

도구 설명
create_skill SKILL.md와 함께 새 스킬 생성
create_subagent 새 서브에이전트 생성
create_output_style 새 출력 스타일 생성

조회 도구

도구 설명
list_skills 스킬 목록 (user/project/both)
read_skill 스킬 내용 읽기
list_subagents 서브에이전트 목록
read_subagent 서브에이전트 내용 읽기
list_output_styles 출력 스타일 목록

스테이징 도구

도구 설명
stage_item ~/.claude 또는 .claude에서 스테이지
stage_all 모든 항목 스테이지
unstage_item 스테이징에서 제거
list_staged 스테이지된 항목 목록

리포지토리 도구

도구 설명
pull_settings GitHub 리포에서 풀
push_settings GitHub 리포로 푸시
browse_repo 리포 내용 탐색
list_repos 풀한 리포지토리 목록

적용 도구

도구 설명
apply_setting 스테이징에서 설정 적용

스코프 도구

도구 설명
promote_setting 프로젝트 → 사용자 이동
demote_setting 사용자 → 프로젝트 이동
compare_scopes 사용자/프로젝트 설정 비교

연결 도구

도구 설명
link_skill_to_command Skill을 슬래시 명령어로
link_subagent_to_command Subagent를 슬래시 명령어로
link_all_to_commands 모든 skills/agents 연결

내보내기 및 로컬 도구

도구 설명
export_for_push git push를 위한 내보내기
link_local_repo GitHub 리포를 로컬에 연결
unlink_local_repo GitHub 리포 연결 해제
get_local_info 로컬 스테이징 정보 확인

온라인 레지스트리 도구

도구 설명
list_online_repos 온라인 레지스트리 리포 목록
pull_online_repo 온라인 레지스트리에서 풀

스캔 도구

도구 설명
scan_claude_dirs .claude 디렉토리 스캔
get_scan_cache_info 스캔 캐시 정보 확인
clear_scan_cache 스캔 캐시 삭제

📐 아키텍처

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

디렉터리 구조

~/.clsync/
├── manifest.json           # 메타데이터 및 리포 추적
├── local/                  # 스테이지한 항목
│   ├── skills/
│   ├── agents/
│   └── output-styles/
└── repos/                  # 풀한 리포지토리
    ├── owner1/repo1/
    │   ├── clsync.json     # 리포 메타데이터
    │   ├── skills/
    │   └── agents/
    └── owner2/repo2/

clsync.json 스키마

{
  "$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
  }
}

🎯 워크플로우

개인: 여러 컴퓨터 간 동기화

컴퓨터 A (내보내기):

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

컴퓨터 B (가져오기):

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

팀: 설정 공유

# 팀 리더가 내보내기
clsync stage --all -u
clsync export ./team-settings -a "Team" -d "Shared team settings"

# 팀원들이 가져오기
clsync pull team/settings
clsync apply --all -s team/settings -u

커뮤니티: 여러 리포 사용

clsync pull user1/awesome-skills
clsync pull user2/productivity-agents
clsync repos                              # 모두 보기
clsync apply code-reviewer -s user2/productivity-agents -u

프로젝트: 스코프 관리

# 양쪽 스코프 보기
clsync scopes

# 프로젝트 설정을 사용자로 이동 (글로벌화)
clsync promote my-skill

# 사용자 설정을 프로젝트로 이동 (로컬화)
clsync demote my-agent

연결: 슬래시 명령어 생성

# 단일 skill을 슬래시 명령어로 연결
clsync link skill alarm
# 이제 Claude Code에서 /alarm 사용 가능

# Subagent를 슬래시 명령어로 연결
clsync link agent code-reviewer
# 이제 Claude Code에서 /code-reviewer 사용 가능

# 모든 skills와 agents를 한번에 연결
clsync link --all

# Skills만 연결
clsync link --all --skills-only

# 프로젝트 스코프에서 연결
clsync link skill my-skill --project

사용 사례: 자동 호출되는 skills를 명시적으로 호출 가능한 슬래시 명령어로 변환하여 더 정확한 제어 가능.

🤝 기여

Pull Request와 Issue 환영합니다!

📜 라이선스

MIT © 2026 workromancer