개요
vinzdg/codenotch는 코딩 어시스턴트의 사용량 한도 소진율과 에이전트 상태(작업 중·완료·입력 대기)를 화면 가장자리의 작은 검은 노치에 링으로 고정해 보여주는 macOS 앱이다(Swift, MIT). Claude Code·Cursor·Codex·Antigravity를 전면에 내세우며, 실제로는 DeepSeek·GLM·Grok·Ollama·LM Studio까지 읽는다. 조회 시점(2026-09-12) stars 1465·forks 229 — 9월 5일 생성된 신생 프로젝트가 일주일 만에 모은 수치라 주목도가 높다.
스크린샷 (공식 저장소 docs/design/)
출처: vinzdg/codenotch docs/design/ (MIT) — 2026-09-12 fetch, main 기준.
지원 범위와 읽기 방식
- Claude Code: Claude Desktop 캐시 → 설치된
claude의/usage→ 키체인 OAuth 토큰 순으로 폴백. Claude/usage가 맨 앞에 두는 current session 창과 같은 값을 보여 둘이 어긋나지 않게 했다. - Cursor: 에디터 로컬 SQLite 세션 또는 키체인의
cursor-agent로그인 — 별도 로그인 불필요. - Codex: 로컬 Codex 로그인으로 ChatGPT 사용량 엔드포인트 조회. 5시간·주간 한드를 표시.
- 그 외: DeepSeek Platform(자체 WKWebView 로그인 후 잔액·30일 토큰/비용), Antigravity(로컬 언어 서버 → Google quota → 단순 카운트), GLM(Z.ai 플랜 모니터), Ollama·LM Studio(로컬 런타임), Grok(
~/.grok/auth.json). - 링에 호버하면 한도 창과 리셋 시점을 툴팁으로 보여준다.
설계 원칙 — 추측치를 공식 수치처럼 보이지 않게
- 모든 provider는
UsageProvider를 구현하고Fidelity(.official·.derived·.manual)를 선언한다. 실패는 날조된 퍼센트 대신stale·needsAuth·error같은 가시 상태로 떨어진다. - README가 솔직한 한계를 명시한다: 어떤 벤더도 “세션 한도 N% 사용” 같은 깨끗한 API를 주지 않으므로, 각 어댑터는 owning 앱이 읽는 것(내부 엔드포인트·로컬 DB·랭귀지 서버 RPC)을 그대로 읽으며, 벤더 변경 시 조용히 꺼지고 나머지가 이어받는다. 어댑터 응답 형태는 테스트에 pin되어 있다.
- Claude Desktop 캐시 읽기는 읽기 전용·범위 한정(해당 계정의 usage URL만, 30분 초과 스냅샷은 live로 표시 안 함). 키체인은 Claude Code가 설치된 경우 아예 쓰지 않고
claude에 물어 회피한다. Claude 429에는 60초 시작·2배·최대 15분 백오프(재실행에도 유지).
설치·실행 메모
- 정식:
releases/latest/download/Codenotch.dmg(서명·공증, 이후 자동 업데이트). 파일명이 매 릴리즈 동일해 latest 링크가 항상 최신을 가리킨다. - 프리뷰: 매 커밋 rebuild + Package 워크플로 커밋별 이미지 — ad-hoc 서명이라 격리 플래그(
xattr -dr com.apple.quarantine) 해제 필요. “damaged” 경고도 격리 플래그 문제다. - Universal binary, 본문 기준 macOS 15 이상 (배지는 macOS 26+ 표기 — 불일치). 소스 빌드 시 Xcode·로컬 서명 스크립트,
CODENOTCH_DEMO=1로 샘플 데이터 데모 가능. - Windows 포트는 Rust/Tauri 2로
windows/에 동봉 (동일 디자인·프로바이더).
확인 범위와 한계
- README 전문(19554 bytes)·REST 메타데이터 fetch로 확인했고, macOS 실기 설치·실행·어댑터 동작은 검증하지 않았다. 스타·이슈 수는 조회 시점 값이다.
- 볼트에는 9/7 @hivinz_의 Codenotch v1.5.0 릴리즈 언급(2026-09-10-x-bookmarks-weekly)이 이미 있어, 본 노트는 저장소 실체 쪽 심층 정리에 해당한다.
관련 위키
- moc-dev-tools — 개발 도구 MOC
- moc-ai-coding — AI 코딩 MOC
- 2026-09-11-astra-token-saving-strategies — Astra 토큰 절약 종합 (쿼터·한도 운용과 같은 문제의식)
- 2026-09-10-x-bookmarks-weekly — Codenotch v1.5.0 릴리즈 언급 포함 주간 다이제스트
검증
- GitHub REST API와
main브랜치 README 전문을 2026-09-12에 fetch했다. 원문은raw/articles/2026-09-12-github-vinzdg-codenotch.md에 보존했고 SHA-256을 기록했다.