sk-ruban/notchi
notch app for claude code & codex
Notchi – Claude Code 및 Codex용 macOS "노치" 동반자
무엇인가요 – MacBook Pro 화면의 노치에 상주하는 작고 가벼운 macOS 앱으로, Anthropic의 Claude Code와 OpenAI의 Codex에서 발생하는 실시간 이벤트에 따라 애니메이션되는 마스코트를 표시합니다. 또한, 보내는 프롬프트의 감정 분석을 수행하고 감정 반응을 표시하는 기능도 선택적으로 제공합니다.
핵심 기능 (README에 기술됨)
| 기능 | 제공되는 기능 |
|---|---|
| 실시간 이벤트 반응 | Notchi는 Claude Code 또는 Codex에 쉘 스크립트 훅을 등록합니다. 모델이 이벤트(사고, 도구 사용, 권한 요청, 오류, 완료 등)를 발생시키면 훅은 유닉스 소켓을 통해 JSON 페이로드를 전송합니다. Notchi는 페이로드를 파싱하고 해당 이벤트에 따라 마스코트를 애니메이션화합니다. |
| 감정 기반 감정 표현 | 설정에서 Anthropic 또는 OpenAI API 키를 붙여넣으면 Notchi는 해당 API를 호출해 각 프롬프트의 감정 분석을 수행하고, 마스코트를 기쁨, 슬픔, 기쁨, 중립 또는 "울고 있는" 상태로 표시합니다. |
| 사용량 추적 | 하단의 바에 지난 30일간의 일일 토큰 사용량과 추정 비용을 제공합니다. 제공자별 또는 통합으로 표시됩니다. 클릭하면 세션 시간, 할당량 바, 비용 차트를 포함한 대시보드가 표시됩니다. |
| 다중 동시 세션 지원 | 각 활성화된 Claude 또는 Codex 세션마다 고유한 스프라이트(클로드/Codex 스프라이트 패밀리 중에서 선택)가 노치를 클릭했을 때 나타나는 작은 "잔디 섬"에 배치됩니다. |
| 사용자 정의 사운드 효과 | 각 이벤트용 내장 사운드 제공; 사용자 사운드도 가져올 수 있습니다. 터미널 창에 포커스가 있을 경우 자동으로 사운드가 음소거됩니다. |
| 로컬라이제이션 | UI는 시스템 언어에 따라 자동으로 변경되며, 영어, 일본어, 간체/번체 중국어, 한국어, 베트남어로 제공됩니다. |
| 자동 업데이트 | 서명된, 노타라이즈된 업데이트를 제공하기 위해 Sparkle 프레임워크를 사용합니다. |
| 크로스플랫폼 커뮤니티 포트 | 커뮤니티 유지보수 Windows 포트 (notchi‑for‑windows, pixel‑companion)에 대한 링크가 있습니다. |
설치 단계 (README에서)
- 릴리스 페이지에서 최신 DMG를 다운로드합니다 (예:
Notchi‑1.2.7.dmg). - DMG를 열고 Notchi를 응용 프로그램 폴더로 드래그합니다.
- 앱을 실행 – 처음 실행 시 Claude Code 및/또는 Codex 훅을 자동으로 설치합니다.
- macOS가 키체인 접근을 요청하면 (API 사용 통계를 저장하기 위해 사용됨), 항상 허용을 클릭합니다.
- (선택 사항) 설정 → Anthropic 또는 OpenAI API 키를 붙여넣어 감정 분석 기능을 활성화합니다.
- Claude Code 또는 Codex를 평소처럼 사용하면 마스코트가 반응하기 시작합니다.
- 사용량 바를 클릭하여 비용/사용량 대시보드를 확인합니다.
내부 동작 방식 (고수준 흐름, README에서)
Claude Code / Codex → 훅 스크립트 (쉘) → 유닉스 소켓 →
이벤트 파서 → 상태 기계 → 애니메이션 스프라이트
- 훅 스크립트는 Notchi에 의해 설치되며, AI 에이전트가 발생시키는 JSON 이벤트를 수신합니다.
- 이벤트는 로컬 유닉스 소켓을 통해 Notchi 프로세스로 전달됩니다.
- 앱은 JSON을 파싱하고, 이벤트를 애니메이션 상태(대기, 작업 중, 수면, 압축 중, 대기 중 등)로 매핑하는 유한 상태 기계를 업데이트합니다.
- API 키가 존재하면 프롬프트 텍스트가 Anthropic 또는 OpenAI에 전송되어 감정 분석을 수행합니다. 그 결과는 마스코트의 표정에 영향을 미칩니다.
- UI는 적절한 스프라이트를 노치 영역에 그려 사용량 패널을 업데이트합니다.
요구 사항 및 호환성
- macOS 15.0+ (Sequoia) – 이 버전에서 도입된 노치 UI에 의존합니다.
- 물리적 노치가 있는 MacBook – 마스코트는 이 공간에 존재합니다.
- Claude Code 및/또는 OpenAI Codex가 머신에 설치되어 있어야 훅이 연결됩니다.
기여 및 지원
- 기여는 풀 리퀘스트를 통해 환영합니다. 지침은
CONTRIBUTING.md를 참조하세요. - 프로젝트는 GPL‑3.0 전용입니다.
- GitHub Sponsors를 통해 개발을 후원할 수 있습니다 (서명된 빌드에 필요한 Apple Developer 계정 비용을 커버합니다).
요약
Notchi는 Claude Code와 Codex의 내부 동작을 재미있게 시각화하는 소규모이지만 완전한 기능을 갖춘 macOS 동반자입니다. 동시에 개발자에게 토큰 사용량의 실시간 시각화와 선택적 감정 피드백을 제공합니다. 이것은 단순한 튜토리얼이나 목록이 아니라, AI 에이전트 상호작용에 집중한 진정한 소프트웨어 프로젝트입니다.
관련
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트