PITIR-TECH/claudecode-local-sync

claudecode-local-sync은(는) 무엇을 하나요?

Claude Code CLI를 위한 크로스 디바이스 및 플랫폼 동기화. Mac과 Windows 간에 세션, 메모리, 플러그인, 에이전트, 스킬, 훅, MCP 설정 및 프로젝트 설정을 GitHub를 통해 동기화합니다. 프로젝트별 또는 전체 동기화, 자동 경로 수정, 플랫폼 감지, 대용량 파일 처리 및 상태 확인을 지원합니다. 한 PC에서 푸시하고 다른 PC에서 풀하여 계속 작업할 수 있습니다.

주요 기능

기능	설명
세션 동기화	Claude Code CLI 세션 기록을 기기 간에 동기화
메모리 동기화	Claude의 장기 및 단기 메모리 동기화
플러그인 및 스킬	설치된 플러그인, 스킬, 에이전트 동기화
MCP 설정	MCP 서버 및 도구 설정 동기화 (경로 자동 변환)
훅 동기화	사용자 정의 훅 스크립트 동기화
프로젝트 설정	CLAUDE.md, .clauderc, .claude/settings.json 등의 프로젝트별 설정 동기화

플랫폼 지원

• macOS: Intel 및 Apple Silicon |
• Windows: Windows 10/11 (PowerShell 5.1+) |
• Linux: (실험적 지원, 테스트 필요) |

설치

사전 요구 사항

• Git 설치 및 설정 완료
• GitHub 계정 및 저장소 (공개 또는 비공개)
• Claude Code CLI 설치

빠른 시작

1. GitHub 저장소 생성 (예: claude-sync)
2. 동기화 저장소 클론

git clone https://github.com/YOUR_USERNAME/claude-sync.git
cd claude-sync

3. 동기화 도구 설정

# 자동 설정
npx @pitir-tech/claudecode-local-sync init

# 또는 수동 설정
mkdir -p .claude/sync

사용법

기본 명령어

명령어	설명
claude sync push	로컬 설정을 GitHub로 푸시
claude sync pull	GitHub에서 로컬로 설정 풀
claude sync status	동기화 상태 확인
claude sync project <name>	특정 프로젝트만 동기화

프로젝트별 동기화

# 프로젝트 선택 동기화
claude sync project my-project push

# 특정 프로젝트 풀
claude sync project my-project pull

전체 동기화

# 모든 설정 한 번에 동기화
claude sync push --all

# 모든 설정 풀
claude sync pull --all

상태 확인

# 동기화 상태 확인
claude sync status

# 자세한 상태 확인 (--verbose)
claude sync status --verbose

설정

환경 변수

변수	기본값	설명
CLAUDESYNC_GIT_REPO	현재 디렉토리	Git 저장소 경로
CLAUDESYNC_BRANCH	main	동기화 브랜치
CLAUDESYNC_INCLUDE_PROJECTS	false	프로젝트 설정 포함 여부
CLAUDESYNC_AUTO_FIX_PATHS	true	플랫폼 간 경로 자동 변환
CLAUDESYNC_LARGE_FILE_THRESHOLD	10MB	대용량 파일 처리 임계값

설정 파일

설정 파일은 .claude/sync-config.json에 저장됩니다:

{
  "gitRepo": "https://github.com/YOUR_USERNAME/claude-sync",
  "branch": "main",
  "includeProjects": true,
  "autoFixPaths": true,
  "largeFileThreshold": "10MB",
  "exclude": [
    "*.log",
    "node_modules",
    ".git"
  ]
}

작동 방식

1. 수집: Claude Code CLI 설정 파일을 스캔하여 동기화할 항목 수집
2. 변환: 플랫폼 간 경로 차이를 자동으로 변환 (예: C:\Users\... ↔ /Users/...)
3. 저장: 수집된 설정을 Git 저장소에 커밋
4. 푸시: 변경 사항을 GitHub에 푸시
5. 풀: 다른 기기에서 변경 사항을 풀
6. 적용: 설정을 로컬 환경에 적용하고 경로를 현재 플랫폼에 맞게 변환

문제 해결

일반적인 문제

문제	해결 방법
Git 인증 오류	SSH 키 설정 또는 Personal Access Token 사용
경로 변환 실패	CLAUDESYNC_AUTO_FIX_PATHS=false로 설정하고 수동 수정
대용량 파일 동기화 실패	CLAUDESYNC_LARGE_FILE_THRESHOLD 값 증가
병합 충돌	git pull --rebase 후 충돌 해결

지원 및 기여

• GitHub Issues: 버그 신고 및 기능 요청
• Discussions: 질문 및 아이디어 공유

라이선스

MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.