Cluxo

macOS 메뉴바 앱. 마우스 커서를 시각적으로 강조해 화면 녹화, 발표, 페어 프로그래밍 시 커서 위치를 명확하게 보여줍니다. 그리기 도구·라디얼 메뉴·키스트로크 표시 등 발표/스크린캐스트 워크플로우를 위한 종합 도우미.

🇺🇸 English README

🪟 Windows 사용자라면 → Cluxo for Windows (네이티브 재구현)

• 커서 링 — 마우스 주위에 색상 링 표시 (원형/둥근 사각형/둥근 마름모/둥근 육각형, 4단계 크기, 투명도·테두리 두께/스타일, 글로우, 호흡 애니메이션)
• 클릭 효과 — 좌클릭(원형 파동), 우클릭(2중 파동), 더블클릭(버스트), 휠 클릭(회전 호)
• 드래그 인디케이터 — 드래그 시 링이 방향대로 늘어남
• 스크롤 인디케이터 — 스크롤 방향 화살표 (↑↓←→) 표시 + 진폭 비례 크기 (정밀 스크롤과 큰 page 스크롤 한눈에 구분)
• 커서 트레일 — 잔상 효과 (글로우 코멧 테일)
• 돋보기 — 커서 주변 화면 1.5×–4× 실시간 확대. 렌즈 크기 조절, Lanczos 업스케일+샤프닝으로 선명하게, 이동 시 떨림 최소화
• 스포트라이트 — 커서 주변만 밝게 나머지 어둡게. 켜고 끌 때 부드럽게 fade in/out(Mousepose 스타일), 경계 부드러움(feather)·반경 조절
• 키스트로크 표시 — 누른 단축키를 화면 하단에 오버레이. 낯선 외장 모니터(회의실 등) 연결 시 자동 활성화 옵션 (신뢰 모니터는 제외)
• 흔들기 감지 — 마우스를 빠르게 흔들면 커서 위치에 퍼지는 링 표시 ("커서 어디 갔지?" 찾기용). on/off + 민감도 3단계
• 스크린샷 모드 — 메뉴바 토글. 평소엔 자체 돋보기가 자기 overlay를 재캡처하지 않게 외부 캡처에서 제외되지만, 발표 자료/데모 GIF 만들 땐 이 토글로 외부 screencapture/OBS에 잡히게 풀어줌. 앱 재시작 시 자동 OFF.
• 라디얼 메뉴 (⌃⌥, 또는 길게 누름) — 커서 위치에 8 sector 메뉴가 빙 둘러 펼쳐짐. 효과·색·모양·스포트라이트·돋보기·링 외형을 메뉴 유지 상태로 연속 조정 (발표 중 빠른 다중 변경).
  • 2단계 계층 — 항목을 잡고 더 바깥으로 끌면 세부 값이 부채꼴로 펼쳐짐: 스포트라이트(반경·경계), 돋보기(배율·렌즈 크기), 링 외형(크기·투명도·테두리 두께/스타일). 현재 값은 옅은 액센트로 강조.
  • 메뉴 잡아끌기 — 중심을 잡고 드래그하면 메뉴를 원하는 위치로 이동 (모니터 간 이동 포함).
  • 여는 법 — ⌃⌥, 외에 마우스 좌클릭 길게 누름(0.5초) 또는 트랙패드 길게 누름으로도 열림 (트랙패드만 쓰는 노트북에 유용). 5pt deadband로 일반 드래그·클릭과 충돌 없음.
• 그리기 모드 (⌃⌥D) — 발표·스크린캐스트용 화면 annotation. 7종 도구: 자유 펜·직선(Shift)·화살표(Opt)·사각형(Cmd)·타원(Cmd+Shift)·형광펜(Cmd+Opt)·번호 뱃지(Shift+Opt 클릭). 모드 활성 중 Cmd+Z로 마지막 도형 제거, [/]로 두께 5단계 조절. 색은 링 색을 따름.
• 트랙패드 제스처 시각 피드백 (실험적) — 4손가락 핀치 인/아웃, 3·4손가락 4방향 스와이프, 5손가락 핀치 등 시스템 제스처에 라벨/효과 표시. 발표 중 손동작을 청중에게 보여줄 때 유용. 비공식 MultitouchSupport API 의존이라 환경설정에서 기본 OFF — "동작" 탭에서 켜세요.

모든 단축키는 ⌃⌥ (Control + Option) 조합:

환경설정에서 일부 단축키는 변경 가능 (메뉴바 아이콘 → 환경설정).

색상 8슬롯 (커스텀 포함), 모양 4종, 크기 4단계, 투명도·테두리·속도·효과 토글, 스포트라이트 경계, 흔들기 민감도까지 한 곳에서 조정. UI 언어는 "일반" 탭에서 시스템 기본 / 한국어 / English 선택.

• macOS 13.0 이상
• Apple Silicon (현재 빌드 기준; Intel은 Universal 빌드 필요)

brew install --cask kykim79/tap/cluxo

Homebrew가 다운로드 시 quarantine flag를 자동으로 제거해주므로 Gatekeeper 우회 절차 없이 바로 동작. 업데이트도 brew upgrade --cask cluxo 한 줄.

Releases에서 Cluxo.zip 다운로드 후:

1. 압축 해제 → Cluxo.app을 /Applications로 이동
2. 첫 실행: Finder에서 우클릭 → 열기 → "열기" 확인 (Gatekeeper 우회, 한 번만)

우클릭→열기도 안 되면:

xattr -dr com.apple.quarantine /Applications/Cluxo.app

시스템 설정 → 개인정보 보호 및 보안에서:

• 손쉬운 사용 (필수): 마우스/키보드 이벤트 캡처
• 입력 모니터링 (필수): 단축키 감지
• 화면 녹화 (선택): 돋보기 사용 시

권한 부여 후 앱 재시작 → 메뉴바에 cursorarrow.rays 아이콘 표시되면 정상.

다른 Mac에서 처음 받았을 때:

# 사전 도구 설치
brew install xcodegen

# 클론
gh repo clone kykim79/Cluxo
cd Cluxo

# .xcodeproj 생성 (git에는 없음, project.yml에서 재생성)
xcodegen

# Xcode 열기
open Cluxo.xcodeproj

Xcode 외부 에디터에서 SourceKit-LSP가 모듈을 정확히 인식하게 하려면 build server 설정:

brew install xcode-build-server
xcode-build-server config -project Cluxo.xcodeproj -scheme Cluxo

→ buildServer.json 생성 (gitignore됨, user-specific path 포함). 한 번 실행하면 이후 LSP가 cross-file 타입을 정확히 인식.

이후 Xcode에서 ⌘R로 빌드/실행 가능.

# Release 빌드
xcodebuild -project Cluxo.xcodeproj \
  -scheme Cluxo \
  -configuration Release \
  build

# /Applications에 설치
pkill -x Cluxo 2>/dev/null
rm -rf /Applications/Cluxo.app
cp -R "$HOME/Library/Developer/Xcode/DerivedData/Cluxo-"*"/Build/Products/Release/Cluxo.app" /Applications/
open /Applications/Cluxo.app

tccutil reset Accessibility com.ktoy.Cluxo
tccutil reset ScreenCapture com.ktoy.Cluxo
tccutil reset ListenEvent com.ktoy.Cluxo
tccutil reset PostEvent com.ktoy.Cluxo

Cluxo/
├── project.yml                          # XcodeGen 설정 (소스 of truth)
├── Sources/Cluxo/
│   ├── main.swift                       # 앱 진입점
│   ├── AppDelegate.swift                # 메뉴바 + 서비스 oikkeo·이벤트 라우팅
│   │
│   │   # State (CursorState God Object 분할)
│   ├── CursorSettings.swift             # @Persisted 영구 설정 + enums
│   ├── CursorRuntimeState.swift         # cursor 위치·motion·드래그
│   ├── EffectsState.swift               # 효과 큐 (클릭/스크롤/트레일/흔들기)
│   ├── KeystrokeOverlayState.swift      # 키스트로크 알림 큐
│   ├── Persisted.swift                  # @Persisted PropertyWrapper (UserDefaults bridging)
│   ├── ShakeState.swift                 # 흔들기 감지 알고리즘 (각 축 독립)
│   │
│   │   # Services (AppDelegate God Object 분할)
│   ├── PermissionsManager.swift         # Accessibility·ScreenRecord·ListenEvent 권한
│   ├── AppActivationDetector.swift      # 발표·녹화·회의 앱 활성화 감지 (NSWorkspace)
│   ├── MagnifierCaptureService.swift    # 돋보기 ScreenCaptureKit (SCStream)
│   ├── KeyboardHotkeyHandler.swift      # 전역 단축키 + 키스트로크 표시
│   ├── MouseEventMonitor.swift          # CGEventTap (백그라운드 스레드)
│   │
│   │   # Views
│   ├── OverlayWindowController.swift    # 전체화면 투명 오버레이 NSWindow
│   ├── OverlayContentView.swift         # SwiftUI 뷰 (링·효과·트레일·앵커라인·컴맷테일)
│   ├── PreferencesView.swift            # 환경설정 윈도우
│   │
│   ├── Info.plist                       # LSUIElement, 권한 설명
│   ├── Cluxo.entitlements
│   └── Assets.xcassets/AppIcon.appiconset/
├── Tests/CluxoTests/          # 단위 테스트 38개 (standalone bundle)
├── .github/workflows/release.yml        # tag push → 빌드 + zip + Release + tap 갱신
├── docs/screenshots/                    # README 이미지
├── CHANGELOG.md
└── README.md

.xcodeproj는 xcodegen이 매번 생성하므로 git ignore. project.yml이 진짜 프로젝트 정의.

• LSUIElement = true: Dock 아이콘 없는 메뉴바 전용 앱
• CGEventTap (백그라운드 스레드): 메인 RunLoop와 격리되어 NSMenu 트래킹, 앱 활성화 변화에 영향받지 않음
• 이벤트 기반 커서 추적: 폴링 Timer 없음. onMouseMove로 push, idle 감지는 DispatchWorkItem
• 좌표계 변환: CGEvent의 Quartz 좌표(top-left)를 Cocoa 좌표(bottom-left)로 변환 후 cursorPosition 저장
• 멀티 모니터: 각 NSScreen마다 별도 오버레이 윈도우. screenFrame.contains(point) 필터로 같은 효과가 다른 화면에 중복 렌더링 안 됨
• 돋보기 캡처: ScreenCaptureKit SCStream 20Hz push, CIImage cropping. cursor가 다른 디스플레이로 옮기면 stream을 그 디스플레이로 자동 재구성
• Overlay sharingType: 평소 .none이라야 자체 돋보기가 자기 overlay를 다시 capture 안 함. 메뉴바 "스크린샷 모드" ON 시 .readOnly로 일시 풀어 외부 screencapture/OBS가 잡게 함 (앱 재시작 시 자동 OFF)

MIT License — 자세한 내용은 LICENSE 파일 참조.

Copyright (c) 2026 kykim79