macOS 메뉴바 앱. 두 Mac 간 Claude Code · Claude Desktop · Codex CLI의 설정 / 세션 / 메모리를 자동 동기화합니다.
⚠️ 현재 상태: 1:1 두 Mac 동기화. ad-hoc 서명 (Developer ID + 공증은 v1.2 예정). 외부 라이브러리 0, 외부 서비스 0.
- 설치 — 세 가지 path 중 하나
- 전체 흐름 — 두 Mac 처음부터 끝까지
- 무엇을 하나
- 🧑 For Human — 사용자 가이드
- 🤖 For LLM — Claude Code 등 AI 도구로 작업할 때
다른 Mac에서 git clone만 한 후 그 폴더에서 Claude Code를 열고 한 마디:
이 프로젝트 설치해서 실행해줘
Claude Code가 자동으로 CLAUDE.md의 "Install workflow" 섹션을 읽고 다음을 처리합니다:
bash scripts/install.sh실행 (Xcode CLT / Homebrew / xcodegen 자동)- Universal Release 빌드 +
/Applications/ClaudeSync.app설치 + launch - macOS가 묻는 GUI prompt들 (Remote Login, FDA, Local Network)을 사용자에게 명시적으로 안내
- Onboarding 6단계 마법사로 가이드
LLM이 못 하는 부분 (시스템 다이얼로그 클릭, Onboarding 버튼 클릭)은 사용자에게 정확히 어디를 클릭하라고 안내합니다.
💡 사전 요구: 다른 Mac에 Claude Code가 설치되어 있어야 함 + git clone이 끝나 있어야 함. Claude Code가 없으면 Path B 또는 C를 사용.
두 Mac 각각의 터미널에서 똑같이 한 번씩:
curl -fsSL https://raw.githubusercontent.com/Two-Weeks-Team/ClaudeSync/main/scripts/web-install.sh | bash이 한 줄이 자동으로:
- GitHub Releases에서 latest .dmg 다운로드 (SHA-256 verification)
- mount →
/Applications/ClaudeSync.app복사 → quarantine 제거 - launch + 메뉴바 등장 확인
Xcode/Homebrew/git 모두 없어도 동작합니다 — GitHub Actions가 미리 빌드한 Universal binary DMG를 받아서 설치만 합니다. 빈 macOS 15 Mac에서도 약 30초 안에 완료.
만약 GitHub Release가 아직 없거나 다운로드 실패하면, 자동으로 source build path(Xcode 필요)로 fallback. 강제로 source build 원하면
CLAUDESYNC_FORCE_SOURCE=1환경변수.
이 한 줄이 자동으로:
| 단계 | 무엇 | 사용자 입력 |
|---|---|---|
| 1 | Xcode Command Line Tools 설치 (없으면) | macOS 시스템 다이얼로그에서 "설치" |
| 2 | git → 소스 clone (~/.claudesync/source) |
없음 |
| 3 | Homebrew 설치 (없으면 비대화형) | 없음 |
| 4 | xcodegen 설치 | 없음 |
| 5 | Universal Release 빌드 (~60초) | 없음 |
| 6 | /Applications/ClaudeSync.app 설치 + Gatekeeper quarantine 제거 |
없음 |
| 7 | 앱 launch | 없음 |
종료 후 터미널에 다음 단계 안내가 한국어로 출력됩니다.
⚠️ Xcode 자체는 자동 설치 불가 — Apple 정책상 CLI로 설치 못 함. Mac App Store에서 "Xcode" 검색 후 한 번만 설치 (대용량, 30분~1시간 소요). 설치 후 위 명령 실행.
git clone https://github.com/Two-Weeks-Team/ClaudeSync.git
cd ClaudeSync
bash scripts/install.shinstall.sh는 기본 non-interactive (자동 yes). prompt 모드 원하면 CLAUDESYNC_INTERACTIVE=1.
| Path | 사용자 입력 | Xcode 필요? | LLM 필요? | 소요 시간 |
|---|---|---|---|---|
| B (curl 한 줄, DMG) ⭐ | curl ... 한 줄 | ❌ 없어도 됨 | ❌ | ~30초 |
| A (AI 위임, source) | "이 프로젝트 설치해서 실행해줘" 한 마디 | ✅ (LLM이 빌드) | ✅ Claude Code | ~2분 |
| C (수동, source) | git clone + cd + bash | ✅ | ❌ | ~2분 |
💡 추천 순서: 일반 사용자는 B (Xcode 안 받아도 됨). 코드를 살펴보거나 수정하려는 개발자는 A 또는 C.
| 조건 | 어떻게 확인 |
|---|---|
| macOS 15 (Sequoia) 이상 | 사과 메뉴 → 이 Mac에 관하여 |
| 같은 Wi-Fi / 같은 LAN | 양쪽 Mac의 Wi-Fi 이름 일치 확인 |
| Xcode 설치됨 | Mac App Store → "Xcode" 검색 |
양쪽 Mac에서 각각 터미널 열고:
curl -fsSL https://raw.githubusercontent.com/Two-Weeks-Team/ClaudeSync/main/scripts/web-install.sh | bash빌드 + 설치 + launch까지 총 1~2분. 양쪽이 동시에 실행되어도 무방.
설치 완료 후 양쪽 Mac의 화면 우측 상단 메뉴바에 안테나 아이콘이 등장합니다.
[화면 우측 상단 메뉴바]
┌─ 안테나 아이콘 (ClaudeSync)
│
… 🌐 ⚛ ☁ 🍴 🔵 💬 🖥 🕐 🌙 📡 ───→ 클릭
처음 launch하면 macOS가 다음을 묻습니다 — 모두 "허용" 클릭:
| Prompt | 답 |
|---|---|
| "ClaudeSync을(를) 여시겠습니까?" (첫 launch만) | 열기 |
| "ClaudeSync이(가) 로컬 네트워크에 있는 디바이스를 찾고 연결하려고 합니다." | 허용 |
메뉴바 안테나 아이콘 클릭 → popover 등장 → 하단 "Onboarding" 버튼 클릭 → 별도 윈도우 열림.
윈도우에는 6단계가 순서대로:
┌──────────────────────────────────────┐
│ Welcome to ClaudeSync │ ← 현재 step 표시
├──────────────────────────────────────┤
│ Step 1 of 3 — Remote Login │
│ │
│ ⚠ Remote Login is OFF │
│ [Open System Settings] [Check now] │
│ [Continue]
└──────────────────────────────────────┘
| Step | 무엇 | 사용자 액션 |
|---|---|---|
| ① Welcome | 환영 화면 | "Continue" 클릭 |
| ② Remote Login | sshd 활성 검사 | "Open System Settings" → 시스템 설정에서 "원격 로그인" 토글 ON → 윈도우로 돌아와 "Check now" → 녹색 ✓ → "Continue" |
| ③ Full Disk Access | FDA 검사 | "Open System Settings" → 잠금 해제 → "+" 버튼 → /Applications/ClaudeSync.app 선택 → "Continue" |
| ④ Discovery | 다른 Mac 발견 대기 | 다른 Mac이 같은 단계 도달하면 목록에 자동 등장 → 옆의 "Pair" 클릭 |
| ⑤ Pairing Code | 6자리 코드 표시 | 다른 Mac 화면의 코드와 시각적 일치 확인 |
| ⑥ Confirm | 최종 확인 | "Confirm — codes match" 클릭 → 자동으로 SSH 키 + TLS 핸드셰이크 + 동기화 시작 |
Mac A의 사용자가 ④에서 "Pair" 클릭하면, Mac B의 메뉴바 popover에 자동으로 배너가 등장:
┌───────────────────────────────────────┐
│ 🔵 ClaudeSync Searching for peer… │
├───────────────────────────────────────┤
│ Pair request from MacA │
│ │
│ 284579 │ ← 6자리 코드 (양쪽 동일해야 함)
│ │
│ [Accept — codes match] [Cancel] │
└───────────────────────────────────────┘
Mac B 사용자: 코드가 Mac A 화면과 일치하면 "Accept — codes match" 클릭 → Mac A의 Onboarding이 자동으로 Step ⑥로 넘어감 → Mac A 사용자가 "Confirm — codes match" 클릭 → 양쪽 모두 "Watching" 상태 → 동기화 시작.
페어링은 한 번만. 영속화되어 양쪽 Mac을 재시작해도 자동 복원.
| 항목 | 값 |
|---|---|
| 동기화 대상 | ~/.claude/, ~/Library/Application Support/Claude/, ~/.codex/, ~/Documents/GitHub/ |
| 발견 | Bonjour _claudesync._tcp (같은 LAN) |
| 페어링 | 6자리 시각 확인 코드 + 16-byte nonce + Ed25519 SSH 키 자동 교환 |
| 전송 | rsync over SSH (openrsync 호환) |
| 보안 | TLS + nonce + known_hosts strict + HMAC-signed prefs (10 layers) |
| 리소스 | Idle 25MB Physical Footprint, 0 leaks |
| 의존성 | macOS 15+ + Xcode 만 — 외부 라이브러리 0, 외부 서비스 0 |
사과 메뉴 → 시스템 설정 → 일반 → 공유 → 우측에서 "원격 로그인" 토글 ON.
해제되어 있으면 페어링 후 rsync가 "Connection refused (port 22)"로 실패합니다.
사과 메뉴 → 시스템 설정 → 개인정보 보호 및 보안 → 전체 디스크 접근 권한:
- 좌하단 자물쇠 클릭 → Touch ID 또는 비밀번호로 잠금 해제
- "+" 버튼 → Finder 다이얼로그 열림
/Applications/ClaudeSync.app선택 → "열기"- 목록에 ClaudeSync 등장하고 토글이 켜져있는지 확인
거부하면 ~/Library/Application Support/Claude 변경을 감시 못 함 → Claude Desktop 세션 동기화 안 됨.
첫 launch 시 자동 prompt. 거부했으면:
사과 메뉴 → 시스템 설정 → 개인정보 보호 및 보안 → 로컬 네트워크 → ClaudeSync 토글 ON.
┌─────────────────────────────────────────────┐
│ 🔵 ClaudeSync │
│ Watching for changes │ ← 현재 상태
├─────────────────────────────────────────────┤
│ Coordinator │
│ Watching for changes │
├─────────────────────────────────────────────┤
│ [pairing banner — 페어링 진행 중일 때만 표시]│
├─────────────────────────────────────────────┤
│ Peers on this network │
│ • MacBookAir (kim) [Paired ✓] │
├─────────────────────────────────────────────┤
│ Targets │
│ 📁 Claude Code 3분 전 [⟳] │
│ 📁 Claude Desktop 방금 [⟳] │
│ 📁 Codex CLI 1시간 전 [⟳] │
│ 📁 Projects — [⟳] │
├─────────────────────────────────────────────┤
│ Recent Activity │
│ ✓ Synced successfully │
│ ✓ Synced successfully │
├─────────────────────────────────────────────┤
│ [Onboarding] [Settings…] [Quit] │
└─────────────────────────────────────────────┘
| 증상 | 어디서 보이나 | 해결 |
|---|---|---|
| 메뉴바 안테나 아이콘이 없음 | 메뉴바 우상단 | LSUIElement 앱이라 Dock 없음. 다른 메뉴바 아이콘에 가려졌으면 ⌘드래그로 위치 조정 |
| "Searching for peer..." 무한 | 메뉴바 popover 상단 | (1) 양쪽 Mac이 같은 Wi-Fi인지 확인 (2) 회사/카페 Wi-Fi는 mDNS 차단 가능 (3) 양쪽 Mac이 메뉴바에 등장한 상태인지 확인 |
| "Failed: rsync exit=255" | 메뉴바 popover의 Recent Activity | 양쪽 Mac에서 시스템 설정 → 일반 → 공유 → "원격 로그인" ON 확인 |
| "Failed: peer clock skew Ns" | Onboarding 윈도우 또는 메뉴바 banner | 두 Mac의 시각 차이 30초 초과. 양쪽 Mac에서 시스템 설정 → 일반 → 날짜 및 시간 → "자동으로 시간 설정" 켜기 |
| "another instance is already running" | 터미널 (install.sh 재실행 시) | killall ClaudeSync 후 bash scripts/install.sh 다시 |
| "Control channel is plaintext" 주황 banner | 메뉴바 popover 상단 | openssl 누락. brew install openssl 후 ClaudeSync 재시작 (없어도 페어링/동기화는 정상 동작) |
| 동기화가 너무 자주 일어남 | Recent Activity가 5분 내 50+ 행 | Settings (⌘,) → Excludes 탭에서 자주 변경되는 파일 패턴 추가 |
| Onboarding 윈도우 사라짐 | 메뉴바 popover에서 다시 "Onboarding" 클릭 | |
| 페어링 후 다른 Mac이 안 보임 | Settings → "Forget paired peer" 클릭 → 처음부터 다시 |
killall ClaudeSync # 1) 앱 종료
rm -rf /Applications/ClaudeSync.app ~/.claudesync # 2) 앱 + 데이터 제거
sed -i '' '/claudesync@/d' ~/.ssh/authorized_keys # 3) (선택) authorized_keys 정리
# 양쪽 Mac에서 같이 진행- ❌ 3대 이상 Mac (1:1만)
- ❌ 클라우드 경유 (LAN 직결만)
- ❌ iCloud Drive · Dropbox 대체 (AI 도구 환경 전용)
- ❌ Windows / Linux
프로젝트: macOS 메뉴바 트레이 앱 (Swift 6, SwiftUI MenuBarExtra)
목적: 두 Mac 간 Claude/Codex 설정·세션·메모리 동기화
전송: rsync over SSH + Bonjour 발견 + Ed25519 키 페어링 + TLS
정책: 외부 의존성 0, sandbox 없음, macOS 15+ 전용
상태: v1.1.0 (코드는 v1.1.1 패치 포함), 214/214 tests green
다음: Developer ID 서명 + 두 Mac 실기 검증 (사용자 자격증명 필수)
HANDOFF.md— 가장 최신 상태, 어디서 이어야 할지CLAUDE.md— 프로젝트 규칙 (Tech stack, branch 정책, openrsync 호환 flag)docs/reports/2026-05-05-v1.1.0-defense-in-depth.html— 가장 최근 마일스톤docs/prd/PRD.md— 무엇을 만드는가docs/specs/TECHNICAL_SPEC.md— 어떻게 (5269 lines, 필요 시 grep)
# 빌드 확인
xcodegen generate # project.yml -> .xcodeproj
xcodebuild -scheme ClaudeSync -configuration Debug -destination 'platform=macOS' build
# 테스트 (전체 ~12초, 214/214 통과해야 함)
xcodebuild -scheme ClaudeSync -configuration Debug -destination 'platform=macOS' test
# Release + Universal binary + DMG
bash scripts/release-build.sh # -> .build/release-DD/.../ClaudeSync.app
bash scripts/measure-footprint.sh "<app>" # -> Physical Footprint vs PRD G4 50MB
bash scripts/package.sh # -> dist/ClaudeSync-1.1.0.dmg
# One-shot install (사용자가 두 Mac 각각에서 실행)
bash scripts/install.sh
# 서명·공증 (사용자 자격증명 필요 — LLM이 직접 못 함)
export CODESIGN_IDENTITY="Developer ID Application: ..."
export NOTARY_PROFILE=ClaudeSync
bash scripts/package.shClaudeSync/
├── App/ — @main + @Observable AppEnvironment (DI 컨테이너)
├── Coordinator/ — 3-pump 라우터 (watcher / batch / results)
├── Discovery/ — Bonjour (NWBrowser/NWListener) + ControlMessage + TLS
├── FileWatcher/ — FSEvents -> 2s debounce -> 3-Tier 라우터
├── Pairing/ — 6자리 코드 + nonce + clock skew + 단일 시도
│ └── Preflight/ — Remote Login / FDA / SSH connectivity
├── Persistence/ — preferences.json (HMAC) + history.json + paired peer
├── SSH/ — Ed25519 키 + authorized_keys + known_hosts + wrapper
├── Sync/ — rsync builder + queue + ConflictResolver (newer-wins)
├── UI/ — MenuBarRootView + Settings + Onboarding
├── Utilities/ — ProcessRunner + Logger + LaunchAtLogin
│ + NetworkResilience + SingleInstanceGuard
└── Resources/ — Info.plist + entitlements + AppIcon
ClaudeSyncTests/ — 26 스위트 / 214 테스트
scripts/ — install / web-install / release-build / measure-footprint / package
docs/
├── prd/ — PRD
├── specs/ — Technical spec, Test strategy
├── references/ — Tech references
├── reports/ — Phase 1~6 + v1.0/v1.0.1/v1.1.0 milestones (HTML)
├── screenshots/ — 메뉴바 / 사용자 가이드용 캡처
└── DEMO_TWO_MACS.md — 두 Mac 실기 시연 가이드
- ❌ 외부 라이브러리 추가 금지 (SPM dependency 0 정책)
- ❌ Sandbox 켜기 금지 (rsync/ssh-keygen/openssl 실행 못 함)
- ❌ GNU rsync 전용 flag 사용 금지 (openrsync 호환만:
--archive --compress --delete --update --itemize-changes --partial --timeout=30) - ❌ Squash merge 금지 (
gh pr merge --merge) - ❌ 사용자에게 텍스트로 묻지 마라 —
AskUserQuestion도구만 - ❌ 보고를 텍스트만으로 끝내지 마라 — HTML 보고서 (
docs/reports/) 생성
| 막힘 | 해결 |
|---|---|
| "matching destinations" warning | 무해. 무시 |
| Swift 6 actor 격리 에러 | nonisolated 또는 @MainActor 명시 |
| Settings 변경이 sync에 반영 안 됨 | AppEnvironment.applyPreferences()가 builder를 swap해야 함 |
| 새 Swift 파일이 컴파일 안 됨 | xcodegen generate 다시 |
setenv("HOME") 테스트 race |
parallelTesting 비활성화 또는 homeDirectory 주입 |
| TLS handshake 실패 | ~/.claudesync/tls/server.p12 권한 0o600 + openssl 경로 확인 (없으면 plaintext fallback 동작) |
xcodebuild test가 즉시 exit |
SingleInstanceGuard가 다른 ClaudeSync.app 발견 — XCTest 환경변수 감지로 자동 skip되지만, 안 되면 CLAUDESYNC_DISABLE_SINGLE_INSTANCE=1 |
HANDOFF.md의 "Resume Prompt" 섹션이 항상 최신. v1.1.0 기준:
이전 세션에서 ClaudeSync v1.1.0까지 완료했습니다 (TLS, nonce, known_hosts, HMAC, auto recovery, single-instance, install.sh, web-install.sh). HANDOFF.md를 읽고 현재 상태를 파악한 후, 서명+공증 / 두 Mac 실기 검증 / GitHub Release 중 사용자가 원하는 작업을 진행하세요. 테스트 214/214 그린.
스크린샷은 사용자가 직접 docs/screenshots/에 PNG로 추가하는 것이 가장 정확합니다. 권장 캡처 (Shift+Cmd+4 → 영역 드래그):
| 파일명 | 무엇을 캡처 |
|---|---|
docs/screenshots/menubar-tray.png |
메뉴바 우상단 안테나 아이콘 영역 (이미 자동 캡처됨) |
docs/screenshots/menubar-popover.png |
안테나 클릭 후 나타나는 popover 전체 |
docs/screenshots/onboarding-step1.png |
Onboarding의 Remote Login 단계 |
docs/screenshots/onboarding-pair.png |
Onboarding의 6자리 코드 표시 화면 |
docs/screenshots/menubar-pair-banner.png |
메뉴바의 Pair request 배너 |
추가 후 README의 해당 섹션에  추가.
내부 프로젝트.
- GitHub: https://github.com/Two-Weeks-Team/ClaudeSync
- 마일스톤별 결정 과정과 패치 이유:
docs/reports/의 HTML 보고서들
이 프로젝트는 Claude Code (Anthropic Opus 4.7)와 페어 코딩으로 작성되었습니다.