Codenotch란 무엇인가요?
Codenotch는 화면 가장자리에 작고 검은 노치를 고정하는 macOS 앱입니다. 링에는 지원되는 각 코딩 어시스턴트의 사용 한도 중 얼마나 소비되었는지와 세션이 활성 상태인지, 완료되었는지, 입력을 기다리는지를 표시합니다.
유휴 상태에서는 노치가 작은 알약 모양으로 유지되며, 포인터가 닿으면 펼쳐집니다. 제공업체 링에 마우스를 올리면 사용 한도 기간과 재설정 시간이 표시됩니다. Claude Code의 경우 기본 링에는 Claude Code의 /usage 명령에서 가장 먼저 표시되는 것과 동일한 현재 세션 기간이 나타납니다.
Codenotch는 세션 활동도 모니터링합니다. 세션이 작업 중이면 제공업체 링 안에서 얇은 호가 회전합니다. 세션에 사용자의 주의가 필요하면 링이 점멸하는 황색 상태로 바뀝니다. 마우스를 올리면 실시간 세션 이름, 실행 위치, 필요한 작업이 표시됩니다.
지원 제공업체 및 데이터 소스
Codenotch는 별도의 계정 시스템을 운영하지 않으며 로그인을 요구하지도 않습니다. Mac에서 지원되는 도구가 이미 보유한 자격 증명이나 세션을 읽습니다.
- Claude Code: 로그인 키체인에 저장된 OAuth 토큰을 사용하고 Claude Code의
/usage명령에서 사용하는 것과 동일한 엔드포인트를 조회합니다. - Cursor: 로컬 SQLite 상태에서 에디터의 로그인 세션을 읽습니다.
- Codex: 실행 중인 Codex 앱 서버에 현재 속도 제한을 요청합니다. Codex가 실행 중이 아니면 Codenotch는 롤아웃 로그로 대체합니다.
- Antigravity: 먼저 로컬 언어 서버를 시도한 다음 Google의 할당량 엔드포인트를 사용합니다. 두 곳 모두 계정의 할당량 데이터를 제공하지 않으면 단순 요청 횟수를 표시합니다.
- GLM: Claude Code의
settings.json, ZCode 또는 OpenCode가 이미 보유한 키를 사용해 Z.ai의 Coding Plan 모니터 엔드포인트를 호출합니다.
지원되는 도구를 평소처럼 설치하고 로그인하세요. Codenotch가 해당 도구의 로컬 세션이나 자격 증명을 발견하면 해당 링이 나타납니다. 설정에서 제공업체를 비활성화하면 Codenotch가 해당 자격 증명을 읽지 않으며 저장된 측정값도 삭제하지만, 원래 도구에서 로그아웃되지는 않습니다.
주요 기능
- Claude Code, Cursor, Codex, Antigravity 및 GLM 사용량 링
- 링에 마우스를 올리면 확인할 수 있는 재설정 기간 상세 정보
- 코딩 세션의 실시간 작업 중 및 대기 상태
- 여러 Claude Code 구성의 자동 검색
- 화면 상단, 하단, 왼쪽 또는 오른쪽 가장자리에 배치
- 사용 가능한 화면 영역, Dock 위치 및 하드웨어 노치에 맞춰 조정되는 레이아웃
- 선택 가능한 Dock 아이콘, 메뉴 막대 아이콘 또는 둘 다 표시하지 않기
- Sparkle을 통한 일일 백그라운드 업데이트 확인
- 추정 백분율 대신 표시되는
stale,needsAuth및error상태
Codenotch 빌드 및 실행
사전 요구 사항
이 프로젝트는 XcodeGen으로 생성된 macOS 애플리케이션입니다. Homebrew로 XcodeGen을 한 번 설치하세요.
brew install xcodegen저장소를 로컬에서 체크아웃한 뒤 프로젝트를 생성하고 빌드한 다음 Debug 빌드를 실행하세요.
make runDebug 빌드에는 서명 ID가 필요하지 않습니다.
테스트 실행
프로젝트의 테스트 대상을 사용해 제공업체 어댑터와 기타 동작을 확인하세요.
make test기반이 되는 내부 엔드포인트, 로컬 데이터베이스 및 RPC 인터페이스는 예고 없이 변경될 수 있으므로 제공업체 응답 형상을 테스트로 고정해 두었습니다.
데모 데이터 사용
실시간 제공업체 데이터를 읽지 않고 인터페이스를 확인하려면 CODENOTCH_DEMO=1로 앱을 실행하세요.
CODENOTCH_DEMO=1 make run데모 모드는 고정된 샘플 데이터를 제공하며 인터페이스 개발, 레이아웃 확인 및 스크린샷 촬영에 유용합니다.
make release는 일반적인 로컬 설정에 포함되지 않습니다. Developer ID 인증서와 App Store Connect 공증 프로필이 필요하며, 관리자가 보관, 공증 및 서명된 자동 업데이트 피드를 생성할 때 사용합니다.
기본 사용법
1. 제공업체의 도구를 통해 로그인
모니터링하려는 코딩 도구를 열고 해당 도구에서 로그인하세요. Codenotch는 로그인 자체를 수행하지 않습니다. 예를 들어 평소처럼 Claude Code 또는 Cursor에서 인증한 다음 Codenotch를 실행하세요.
2. 제공업체 링 확인
검색된 각 제공업체는 노치 안에 링으로 표시됩니다. 링을 통해 사용 가능한 한도 중 얼마나 소비되었는지 확인하세요. 링에 마우스를 올리면 사용 가능한 한도 기간과 재설정 시간을 살펴볼 수 있습니다.
3. 세션 상태 확인
지원되는 세션이 작업 중일 때는 해당 링 안에서 얇은 호가 회전하는지 확인하세요. 점멸하는 황색 링은 세션이 차단되어 사용자의 응답을 기다리고 있다는 뜻입니다. 마우스를 올리면 세션 이름, 위치 및 요청된 작업을 확인할 수 있습니다.
4. 노치 설정
노치 아래의 구체를 통해 설정을 여세요. 유휴 상태에서는 호로 표시되며, 마우스를 올리면 톱니바퀴로 바뀝니다. 설정에서 노치가 마우스를 올렸을 때 펼쳐질지, 계속 표시될지, 완전히 숨겨질지를 지정할 수 있습니다.
Codenotch에 Dock 아이콘이나 메뉴 막대 아이콘을 표시할지, 또는 둘 다 표시하지 않을지도 선택할 수 있습니다.
5. 화면 가장자리 선택
노치를 네 가장자리 중 원하는 곳에 배치하세요.
- 왼쪽 또는 오른쪽: 제공업체 측정값이 세로 열로 표시됩니다.
- 상단 또는 하단: 제공업체 측정값이 나란히 표시됩니다.
Codenotch는 화면의 사용 가능한 가장자리를 따라 배치됩니다. 하단에 배치하면 Dock 위에 놓이며 Dock이 숨겨지거나 이동할 때 이에 맞춰 반응합니다. 하드웨어 노치가 있는 Mac에서는 상단 배치가 하드웨어 노치의 정확한 형태를 사용하므로 물리적 노치와 소프트웨어 노치가 하나의 요소처럼 보입니다.
여러 Claude Code 계정 모니터링
Codenotch는 별도의 Claude Code 구성 디렉터리마다 별도의 링을 표시할 수 있습니다. 예를 들어 다음과 같이 업무용 계정을 실행합니다:
CLAUDE_CONFIG_DIR=~/.claude-work claudeClaude Code가 해당 디렉터리를 사용하면 Codenotch가 이를 검색하고 개인 계정 옆에 Claude (work) 링을 표시합니다. 업무용 계정에는 자체 제한, 세션 및 설정 행이 제공됩니다.
실행 시 Codenotch는 Claude Code가 사용한 ~/.claude-<slug> 형식의 디렉터리를 검색합니다. 기본 ~/.claude 계정은 항상 첫 번째에 배치되며, 추가 구성은 알파벳순으로 정렬되어 링의 위치가 예기치 않게 바뀌지 않습니다.
새로 고침 동작 및 속도 제한
Codenotch는 불필요한 요청을 줄이도록 폴링 주기를 조정합니다. 모니터링 중인 세션이 실행되고 있지 않으면 폴링 주기가 5분으로 느려집니다. 새 데이터를 수동으로 요청하려면 노치를 마우스 오른쪽 버튼으로 클릭하고 지금 새로 고침을 선택합니다.
Claude의 엔드포인트는 너무 자주 조회하면 HTTP 429를 반환할 수 있습니다. Codenotch는 60초부터 시작해 연속으로 속도 제한 응답을 받으면 두 배씩 늘어나고 최대 15분으로 제한되는 지연 시간을 적용합니다. 이 기한은 실행 간에도 유지되므로 재시작 직후 또 다른 요청이 소비되는 것을 방지합니다.
업데이트 및 보안
Codenotch는 Sparkle을 사용해 매일 업데이트를 확인하고 백그라운드에서 설치합니다. 자동 업데이트는 설정에서 비활성화할 수 있습니다. 공식 업데이트에는 EdDSA 서명이 적용되므로 앱은 유지 관리자가 제작하고 서명하지 않은 빌드를 설치하지 않습니다.
키체인 기반 제공자의 경우 공식 앱은 안정적인 Developer ID ID를 사용하므로 한 번 허용한 항상 허용 권한이 다시 빌드한 후에도 유지될 수 있습니다. Codenotch는 비밀 정보를 다시 읽기 전에 키체인 항목의 수정 날짜를 확인하여 일반적인 폴링 중 반복적인 접근 허용 요청을 줄입니다.
고급 개발 참고 사항
제공자 아키텍처
각 통합은 Sources/Providers/ 아래에서 UsageProvider를 구현합니다. 또한 제공자는 .official, .derived 또는 .manual 중 하나의 Fidelity 값을 선언합니다. 이를 통해 인터페이스가 추론된 값을 공급업체가 직접 게시한 값인 것처럼 표시하지 않도록 합니다.
Sources/Model/ 아래에 있는 UsageStore는 타이머에 따라 제공자를 폴링하고 마지막으로 성공한 측정값을 실행 간에 유지합니다. 제공자에 오류가 발생하면 저장소는 백분율을 임의로 만들어 내는 대신 stale, needsAuth 또는 error와 같은 상태를 표시합니다.
화면 가장자리 레이아웃
노치 레이아웃은 along 및 across 좌표를 사용해 1차원 스택 공간에서 작동합니다. NotchPlacement는 선택한 가장자리에 맞춰 해당 값을 실제 화면 좌표로 변환합니다. NotchLayout은 구현과 디자인 프레임을 비교하는 데 사용되는 측정값을 중앙에서 관리합니다.
진단 로그 확인
Codenotch에는 일반적인 앱 창이 없으므로 진단 정보가 macOS 통합 로그에 기록됩니다. 다음 명령으로 디버그 메시지를 스트리밍합니다:
/usr/bin/log stream --predicate 'subsystem == "com.vinz.codenotch"' --level debug이 로그는 제공자가 인증하지 못하거나, 오래된 데이터를 반환하거나, 응답 형식이 변경되었을 때 사용하는 기본 문제 해결 도구입니다.
제한 사항 이해하기
지원되는 공급업체 중 코딩 세션의 정확한 사용률을 보편적으로 보고하는 단순하고 안정적인 API를 제공하는 곳은 없습니다. 따라서 Codenotch는 엔드포인트, 데이터베이스, 언어 서버 및 로그를 포함해 해당 애플리케이션이 사용하는 것과 동일한 내부 또는 로컬 소스를 읽습니다.
이러한 인터페이스는 예고 없이 변경될 수 있습니다. Codenotch는 어댑터 테스트와 명시적인 오류 상태로 이러한 위험에 대응하지만, 업스트림 애플리케이션이 변경되면 제공자 통합이 일시적으로 작동하지 않을 수 있습니다.
결론
Codenotch는 코딩 어시스턴트 사용량, 재설정 기간 및 활성 세션 상태를 작은 macOS 화면 가장자리 표시 영역으로 가져옵니다. make run으로 시작하고 데모 모드에서 안전하게 인터페이스를 살펴본 다음, 지원되는 도구에 이미 구성된 계정을 앱이 검색하도록 하세요. 개발 및 기여에 관한 자세한 내용은 CONTRIBUTING.md를 참조하세요. 프로젝트는 MIT 라이선스로 제공됩니다.