Claude 컨텍스트 위젯

클로드 데스크탑 앱에 지금 열려 있는 세션의 컨텍스트 사용량을 보여주는 작은 창.

앱 우측 하단의 원은 2026년 8월 말 업데이트부터 컨텍스트 사용량 대신 플랜 한도(5시간/주간)를 그린다. 그 수치가 사라진 건 아니고 원의 접근성 이름에는 그대로 남아 있어서, 그걸 읽어다 따로 띄운다. 앱을 고치거나 건드리지 않는다.

33.6%   336.2k / 1.00M
주간·전체 모델 13% · 수 오후 6:00에 재설정

필요한 것

• 윈도우 10 / 11
• 클로드 데스크탑 앱이 켜져 있고 한국어 UI일 것

앱 화면의 글자를 읽는 방식이라 UI 언어를 탄다. 영어 UI에서는 컨텍스트 수치(Context 325.8k / 1M)까지는 읽지만 아랫줄(플랜 한도)은 비어 있을 수 있다. 다른 언어는 알 수 없음 만 뜬다.

빠른 시작

Releases 에서 ClaudeContextWidget.exe 를 받아 더블클릭. 파이썬 없이 이 파일 하나로 돈다.

소스로 돌리려면 저장소를 받아 컨텍스트위젯.cmd 더블클릭(콘솔 창 없이 뜬다). 표준 라이브러리 외에 comtypes 만 있으면 된다. 개발·빌드는 파이썬 3.13에서 했다.

pip install comtypes

설정과 로그는 실행한 파일 옆에 생긴다. exe를 바탕화면에 두면 바탕화면에 생기므로, 폴더 하나 만들어 그 안에 두는 편이 깔끔하다.

화면

• 윗줄 — 컨텍스트 사용률, 사용 토큰 / 상한.
• 막대 — 같은 값.
• 아랫줄 — 플랜 한도 쪽 정보. 앱 문구를 한 줄로 정리해 옮긴다.

글자와 막대 색은 컨텍스트 사용률을 따른다.

사용률	색
40% 이하	초록
55% 이하	노랑
70% 이하	주황
그 이상	빨강

테마는 다크(기본)와 화이트 둘이다. 배경·글자뿐 아니라 위 네 색도 같이 바뀐다 — 다크용 색은 흰 배경에서 너무 흐려 읽기 어렵기 때문이다. 설정창도 고른 테마를 따른다.

값을 못 읽으면 알 수 없음 이라고만 쓴다. 다른 데서 끌어와 채우지 않는다.

조작

어디서	무엇
창 끌기	위치 이동. 자리는 기억된다
창 오른쪽 클릭	메뉴
트레이 아이콘 왼쪽 클릭	숨기기 / 표시
트레이 아이콘 오른쪽 클릭	메뉴
Esc	종료 (창에 포커스가 있을 때)

메뉴는 숨기기(또는 표시) · 설정… · 종료 셋이다. 트레이 아이콘을 못 만든 경우에는 숨길 방법도 없으므로 숨기기 없이 둘만 나온다.

숨기기는 창을 내리는 대신 투명하게 만들고 클릭이 통과하도록 한다. 창을 내리면 그 창의 메뉴가 뜨지 않아, 트레이에서 되돌릴 방법이 없어지기 때문이다. 숨긴 상태는 저장하지 않으니 다시 실행하면 보이는 상태로 뜬다.

트레이 아이콘

시계 옆 알림 영역에 초록 링으로 상주한다. 마우스를 올리면 현재 사용률과 아랫줄 내용이 풍선으로 뜬다.

윈도우 11은 새 트레이 아이콘을 처음에 숨긴다. 시계 왼쪽 ∨ 안에 들어가 있으니, 항상 보이게 하려면 그 아이콘을 작업표시줄로 끌어다 놓는다.

설정 창

오른쪽 클릭 → 설정…. 위젯 옆에서 열리되 화면(작업표시줄 제외) 밖으로 나가면 안쪽으로 밀어 넣는다.

테마 — 다크 / 화이트. 고르는 즉시 반영되고 그대로 저장된다. 설정창도 새 테마로 다시 그려진다.

크기 — 작게 / 보통 / 크게. 고르는 즉시 반영되고 그대로 저장된다. 적용 을 누르지 않아도, Esc 로 닫아도 되돌아오지 않으니 되돌리려면 원래 크기를 다시 고른다. 실측 창 크기는 212×60, 256×76, 300×94 픽셀.

색 구간 — 위 표의 세 경계값. 순서가 뒤바뀌거나 범위를 벗어난 값은 알아서 정리된다. 기본값 단추로 되돌린다. 적용 을 눌러야 저장된다.

윈도우 시작 시 자동 실행 — 켜면 지금 실행 중인 파일(exe 또는 스크립트)을 HKCU\Software\Microsoft\Windows\CurrentVersion\Run 에 ClaudeContextWidget 이름으로 등록하고, 끄면 지운다. 관리자 권한은 필요 없다.

폴더를 옮겨도 다음 실행 때 등록된 경로를 현재 경로로 알아서 고친다. 단 같은 종류끼리만 고친다 — exe로 등록해 둔 것을 소스로 한 번 실행했다고 스크립트 경로로 바꿔치지 않는다.

테마·크기·색 구간·창 위치는 ctx_widget.state.json 에 남는다.

값을 어디서 가져오나

앱의 사용량 원(우측 하단) 버튼의 접근성 이름에 수치가 그대로 들어 있다.

사용량: 5시간 한도의 39% 1시간 9분 후 재설정 컨텍스트 325.8k / 1M (33%)

위젯은 Windows UI Automation으로 이 한 줄을 읽는다. 앱이 고른 세션을 그대로 따라가므로, 세션 목록에서 다른 세션을 누르면 2초 안에 그쪽 수치로 바뀐다. 상한(1M / 200k)도 여기서 같이 읽으니 따로 맞출 필요가 없다.

앞부분(플랜 한도)의 문구는 대표 한도가 무엇이냐에 따라 앱이 바꿔 쓴다. 두 형식 다 받는다.

사용량: 5시간 한도의 39% 1시간 9분 후 재설정
    → 5시간 한도 39% · 1시간 9분 후 재설정

사용량: 주간 · 전체 모델: 12% (수) 오전 6:00에 재설정
    → 주간·전체 모델 12% · 수 오전 6:00에 재설정

알아둘 것

• 갱신 시점 — 값은 응답이 끝날 때 갱신된다. 응답이 진행되는 동안에는 직전 값이 보인다. 창은 2초마다 다시 읽는다.
• 알 수 없음 — 앱이 꺼져 있거나, 세션에 따라 앱이 저 문구에서 컨텍스트 부분을 빼는 때가 있다. 그 세션에서 한 번 주고받으면 대개 다시 나온다. 컨텍스트만 없고 플랜 한도는 읽힌 경우 윗줄만 알 수 없음 이 되고 아랫줄은 그대로 나온다.
• 앱 UI 문구에 기댄다 — 앱 업데이트로 접근성 문구가 또 바뀌면 알 수 없음 만 뜬다. 그때는 실제 문구를 다시 확인해 ctx_widget.py 위쪽 정규식을 고치면 된다.
• 에러 로그 — 예기치 못한 오류는 ctx_widget.error.log 에 쌓인다. 창이 조용히 이상해지면 여기부터 본다.

파일

파일	무엇
ctx_widget.py	본체 전부 (읽기·창·트레이·설정)
ctx_widget.ico	창·트레이·실행 파일 아이콘
make_icon.py	위 아이콘을 그린다
build_exe.py	독립 실행 파일을 만든다
컨텍스트위젯.cmd	소스로 실행

아래는 저장소에 없다. 실행하거나 빌드하면 생긴다.

파일	무엇
dist\ClaudeContextWidget.exe	빌드 결과 (약 11MB)
ctx_widget.state.json	설정
ctx_widget.error.log	오류 기록 (생길 때만)
ctx_widget.debug.log	--debug 로 실행했을 때만

개발

python ctx_widget.py --self-check   # 라벨 파싱·색 구간·테마·크기·좌표 계산 점검
pythonw ctx_widget.py --debug       # 드래그 로그를 ctx_widget.debug.log 에
python make_icon.py                 # 아이콘 다시 그리기
python build_exe.py                 # exe 다시 빌드 (PyInstaller 필요)

한 파일(onefile)로 만든다 — 복사할 게 하나뿐이라서. 대가는 시작 속도다. 한 파일은 실행할 때마다 내용물을 임시 폴더에 푼다. 같은 코드로 각각 3~4회 실측한 값:

방식	창이 뜨기까지	디스크
한 파일 (지금)	평균 1160 ms	10.8MB (압축)
폴더 (--onedir)	평균 244 ms	24.7MB

시작이 거슬리면 build_exe.py 의 --onefile 을 --onedir 로 되돌리면 된다. 그때는 dist\ClaudeContextWidget\ 폴더째 옮겨야 한다.

빌드 크기는 build_exe.py 의 EXCLUDES 가 좌우한다. 특히 numpy는 반드시 빼야 한다 — comtypes._npsupport 가 numpy가 깔려 있으면 무조건 import해서, 쓰지도 않는 numpy와 OpenBLAS가 26MB나 딸려 들어간다. 남은 용량은 대부분 파이썬 런타임과 Tcl/Tk라 더 줄이려면 Tk를 걷어내야 한다.

만듦새

개인용으로 만든 도구다. 앤트로픽과 무관하고, 클로드 앱을 고치거나 후킹하지 않는다 — 화면에 이미 떠 있는 접근성 텍스트를 읽을 뿐이다. 앱이 그 문구를 바꾸면 동작이 멈출 수 있다.

MIT 라이선스. 문제가 생겨도 책임지지 않는다.