clicky

Clicky는 macOS에서 커서 근처에 동반자로 위치하는 AI 기반 교육 보조 도구입니다. 화면을 관찰하고, 대화에 참여하며, 특정 인터페이스 요소를 시각적으로 가리킬 수 있습니다. 이 저장소는 MIT 라이선스로 공개된 Clicky의 오픈소스 버전을 포함하고 있어 개발자가 수정, 사용자 정의 또는 이를 기반으로 구축할 수 있습니다. ## 기능 - **화면 인식**: ScreenCaptureKit을 사용하여 화면 콘텐츠를 캡처하고 분석합니다. - **음성 상호작용**: AssemblyAI를 통한 실시간 전사와 함께 푸시 투 토크 음성 캡처를 지원합니다. - **대화형 AI**: 전사 내용과 스크린샷을 Claude로 스트리밍하여 상황 인식 응답을 생성합니다. - **텍스트 음성 변환**: ElevenLabs TTS를 통해 응답을 재생합니다. - **커서 가리키기**: Claude가 특수 태그를 삽입하여 여러 모니터에서 특정 UI 요소로 커서를 이동할 수 있습니다. - **메뉴 바 앱**: 제어 패널과 전체 화면 오버레이 창이 있는 가벼운 메뉴 바 애플리케이션으로 실행됩니다. ## 아키텍처 - **Swift 앱** (`leanring-buddy/`): 중앙 상태 머신, 패널 UI, Claude 스트리밍 클라이언트, ElevenLabs TTS 클라이언트, 오버레이 창, AssemblyAI 전사 제공자를 포함한 주요 애플리케이션 로직을 포함합니다. - **Cloudflare Worker** (`worker/`): API 키를 안전하게 보관하고 `/chat`, `/tts`, `/transcribe-token` 엔드포인트로 요청을 라우팅하는 작은 프록시입니다. - **CLAUDE.md**: AI 에이전트가 코드베이스를 이해할 수 있도록 작성된 포괄적인 아키텍처 문서입니다. ## 설정 ### 사전 요구 사항 - macOS 14.2+ (ScreenCaptureKit용) - Xcode 15+ - Node.js 18+ (Cloudflare Worker용) - Cloudflare 계정 (무료 티어 가능) - Anthropic, AssemblyAI, ElevenLabs용 API 키 ### Claude Code로 빠른 시작 1. Claude Code를 설치하고 실행합니다. 2. 제공된 프롬프트를 붙여넣어 저장소를 복제하고, `CLAUDE.md`를 읽고, 설정 안내를 받습니다. ### 수동 설정 1. **Cloudflare Worker 설정**: `worker/`로 이동하여 `npm install`을 실행한 다음, `npx wrangler secret put`을 사용하여 API 키를 시크릿으로 추가합니다. `wrangler.toml`에서 ElevenLabs 음성 ID를 설정합니다. `npx wrangler deploy`로 배포합니다. 2. **Worker를 로컬에서 실행** (선택 사항): `npx wrangler dev`를 사용하고 키가 포함된 `.dev.vars` 파일을 생성합니다. Swift 코드의 프록시 URL을 `http://localhost:8787`로 업데이트합니다. 3. **프록시 URL 업데이트**: Swift 코드에서 `clicky-proxy`를 검색하여 Worker URL로 교체합니다. 4. **Xcode에서 열기**: `leanring-buddy.xcodeproj`를 열고, 스킴을 선택하고, 서명 팀을 설정한 후 Cmd+R로 실행합니다. ### 필요한 권한 - 마이크 (푸시 투 토크용) - 손쉬운 사용 (전역 키보드 단축키용) - 화면 기록 (스크린샷용) - 화면 콘텐츠 (ScreenCaptureKit용) ## 프로젝트 구조 ``` leanring-buddy/ # Swift 소스 CompanionManager.swift # 중앙 상태 머신 CompanionPanelView.swift # 메뉴 바 패널 UI ClaudeAPI.swift # Claude 스트리밍 클라이언트 ElevenLabsTTSClient.swift # 텍스트 음성 변환 재생 OverlayWindow.swift # 파란 커서 오버레이 AssemblyAI*.swift # 실시간 전사 BuddyDictation*.swift # 푸시 투 토크 파이프라인 worker/ # Cloudflare Worker 프록시 src/index.ts # 세 가지 라우트: /chat, /tts, /transcribe-token CLAUDE.md # 전체 아키텍처 문서 ``` ## 기여 PR을 환영합니다. Claude Code를 사용하는 경우 `CLAUDE.md`를 읽어 코드베이스를 이해하고 기능 개발이나 버그 수정을 지원할 수 있습니다. 피드백은 X(@farzatv)의 작성자에게 전달할 수 있습니다.