[앱 무료 제공] 클로드 사용량, 맥 메뉴바·윈도우 트레이에서 실시간 확인…무료 오픈소스 ClaudeUsageBar

클로드 코드를 쓰다 보면 “한도에 도달했습니다”를 만나고 나서야 사용량을 돌아보게 됩니다. 클로드 코드 안에서 /usage를 입력하면 현황을 볼 수 있지만, 매번 대화창을 열어 확인하는 건 번거롭습니다. 그래서 만들었습니다.

ClaudeUsageBar는 맥 메뉴바와 윈도우 트레이에 상주하면서 5시간 창과 주간 한도 사용률을 계속 보여 주는 앱입니다. AI 매터스가 직접 사용하기 위해 만들었지만 여러분을 위해 깃허브에 공개합니다. 클로드 코드로 만들었고, 라이선스는 MIT입니다. 한도가 초록·노랑·빨강으로 표시되니 80%를 넘기 전에 작업 배분을 조절할 수 있습니다.

이 앱의 원리는 간단합니다. 클로드 코드가 로그인할 때 저장해 둔 인증 정보를 읽어, /usage 화면이 쓰는 것과 같은 사용량 조회 주소를 몇 분에 한 번씩 확인하는 방식입니다. 모델을 호출하는 게 아니라 지금 몇 퍼센트를 썼는지 숫자만 받아 오기 때문에 비용이 들지 않고, 사용량 한도를 깎지도 않습니다.

시작 전: 터미널 여는 법

아래 명령은 브라우저 주소창이나 클로드 코드 대화창이 아니라 맥의 터미널, 윈도우의 명령 프롬프트나 Windows PowerShell에 입력합니다. 컴퓨터에 글자로 명령을 내리는 검은 창입니다.

💻 맥: ⌘와 스페이스를 함께 눌러 검색창을 띄운 뒤 ‘터미널’을 입력합니다. 붙여넣기는 ⌘와 V입니다.

🪟 윈도우: 시작 버튼을 마우스 오른쪽으로 눌러 ‘명령 프롬프트’ 또는 ‘Windows PowerShell’을 고릅니다. 붙여넣기는 Ctrl과 V입니다.

이런 창이 처음이시라도 걱정하지 않으셔도 됩니다. 아래 명령을 한 줄씩 붙여넣고 엔터를 누르면 됩니다. 한 줄을 실행하면 글자가 주르륵 올라가는데, 멈추고 커서가 다시 깜빡일 때까지 기다렸다가 다음 줄을 넣으시면 됩니다. 그래도 어렵게 느껴진다면 클로드에게 이 기사를 통째로 붙여넣고 “나는 몰라, 네가 알아서 해줘”라고 떼를 쓰셔도 됩니다. 어떻게든 해 줍니다.

1. 인증 준비 — 클로드 코드에 로그인해 두기

🔑 이 앱은 클로드 코드가 저장해 둔 인증 토큰을 읽어서 움직입니다. 그래서 시작 전에 클로드 코드 로그인이 한 번 되어 있어야 합니다. 맥은 터미널에서, 윈도우는 파워셸에서 합니다.

클로드 코드를 데스크톱 앱으로만 써왔다면 여기서 설치가 막히는 경우가 많습니다. 괜찮습니다. 데스크톱 앱은 인증 정보를 자기 저장소에 따로 보관하기 때문에 앱이 읽을 토큰이 없을 뿐입니다. 아래를 따라 하시면 됩니다. 맥과 윈도우는 절차가 조금 다르니 쓰시는 쪽만 보시면 됩니다.

맥에서 하기

터미널을 열고 아래 한 줄을 붙여넣은 뒤 엔터를 누릅니다.

맥 터미널

claude auth login

브라우저가 저절로 열립니다. 클로드 계정으로 로그인하고 승인을 누르면 터미널로 돌아옵니다. 브라우저가 안 열린다면 터미널에 뜬 주소를 복사해 직접 열어도 됩니다.

제대로 됐는지 확인해 보겠습니다.

맥 터미널

claude auth status

"loggedIn": true가 보이면 성공입니다. 여기까지 오셨으면 어려운 부분은 지나갔습니다.

윈도우에서 하기

윈도우도 같은 로그인이 필요합니다. 다만 클로드 코드 자체가 깔려 있지 않은 경우가 많아 한 단계가 더 있습니다.

명령 프롬프트나 Windows PowerShell을 열고, 클로드 코드가 없다면 먼저 설치합니다. 이미 쓰고 계시다면 이 줄은 건너뛰셔도 됩니다.

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

설치가 끝나면 로그인합니다.

Windows PowerShell

claude auth login

브라우저에서 승인까지 마친 뒤 확인합니다.

Windows PowerShell

claude auth status

여기서도 "loggedIn": true가 나오면 준비 완료입니다.

이렇게 받은 토큰은 맥에서는 키체인의 Claude Code-credentials 항목에, 윈도우에서는 사용자 폴더의 .claude 안 .credentials.json에 저장됩니다. 맥에서 키체인을 읽지 못하면 ~/.claude/.credentials.json을 대신 봅니다. 앱은 이 값을 읽기만 하고, 토큰이 컴퓨터 밖으로 나가는 일은 없습니다.

2. 맥 설치 — 내려받아 스크립트 실행

🍎 맥은 저장소를 내려받아 설치 스크립트를 실행합니다. 저장소에는 완성된 앱 파일이 들어 있지 않고 설치할 때 직접 만들기 때문에, 애플이 제공하는 개발 도구가 하나 필요합니다. 아래 명령을 먼저 넣어 두시면 됩니다. 이미 깔려 있다면 이미 설치돼 있다는 안내만 뜨고 지나갑니다.

맥 터미널

xcode-select –install

별도 창이 뜨면서 설치가 시작되는데, 네트워크 상태에 따라 몇 분에서 십여 분까지 걸립니다. 끝날 때까지 기다렸다가 다음으로 넘어가시면 됩니다.

이제 앱을 받아 설치합니다. 세 줄을 한 줄씩 차례로 넣습니다.

맥 터미널

git clone https://github.com/dlitecomm/aimatters-ClaudeUsageBar.git

cd aimatters-ClaudeUsageBar/macos

./CUBR-설치.command

첫 줄은 앱을 내려받고, 둘째 줄은 그 폴더로 들어가고, 셋째 줄이 설치를 시작합니다. 설치 스크립트가 앱을 만들어 응용 프로그램 폴더에 넣고, 로그인할 때 자동으로 켜지도록 등록한 뒤 바로 실행합니다.

직접 입력하기가 번거로우시면 클로드 코드나 클로드 코워크에 https://github.com/dlitecomm/aimatters-ClaudeUsageBar.git을 알려 주고 대신 설치해 달라고 하셔도 됩니다. 저장소를 내려받고 설치 스크립트를 실행하는 것까지 알아서 해 줍니다.

첫 실행 때 키체인 접근을 물어보는 창이 뜹니다. 놀라지 않으셔도 됩니다. 앞서 저장해 둔 로그인 정보를 읽어도 되는지 맥이 확인하는 절차입니다. 비밀번호를 입력하고 ‘항상 허용’을 누르면 다시 묻지 않습니다.

이제 메뉴바에 ✳ 26% 같은 숫자가 보입니다. 이 숫자는 남은 양이 아니라 지금까지 쓴 비율입니다. 클릭하면 5시간 창과 주간 한도 각각의 사용률과 리셋 시각이 초록(여유)·노랑(50% 이상)·빨강(80% 이상) 게이지와 함께 나옵니다. 몇 줄이 뜨는지는 앤트로픽이 돌려주는 응답이 정합니다. 앱은 응답에 들어온 항목을 그대로 늘어놓기 때문에, 계정에 따라 줄 수가 다를 수 있습니다.

나중에 다시 설치하거나 새 버전을 받을 때도 CUBR-설치.command를 다시 더블클릭하면 덮어쓰기 때문에 이전 것을 지울 필요가 없습니다.

3. 윈도우 설치 — 설정 앱 목록에도 등록

🪟 윈도우는 따로 만드는 과정 없이 스크립트로 바로 돌아갑니다. 저장소 페이지에서 초록색 Code 버튼을 누르고 Download ZIP을 고르면 파일이 내려옵니다.

압축을 풀기 전에 한 가지만 먼저 해 두시면 보안 차단을 예방할 수 있습니다. 내려받은 zip 파일을 마우스 오른쪽으로 눌러 속성을 열고, 아래쪽의 ‘차단 해제’를 체크한 다음 압축을 푸는 것입니다. 인터넷에서 받은 파일이라는 표식을 지우는 절차인데, 이걸 건너뛰면 실행이 막힐 수 있습니다.

압축을 푼 폴더에서 windows 안의 CUBR-Install.bat을 더블클릭하면 설치가 끝납니다. 사용자 폴더에 파일이 복사되고, 시작 프로그램에 등록되고, 윈도우 설정의 ‘설치된 앱’ 목록에도 올라가서 나중에 일반 프로그램처럼 지울 수 있습니다. 관리자 권한은 필요하지 않습니다.

설치되면 작업표시줄 트레이에 숫자가 색깔과 함께 그려집니다. 맥과 달리 ✳ 기호 없이 숫자만 나오고, 주간 한도를 고르면 주26처럼 표시됩니다. 아이콘이 안 보인다면 트레이의 숨김 아이콘(^)을 펼쳐 보시고, 항상 보이게 하려면 아이콘을 작업표시줄 쪽으로 끌어다 놓으면 됩니다.

⚠️ 윈도우 버전은 맥에서 작성해 실제 윈도우 기기에서 검증하기 전 단계입니다. 문제가 생기면 트레이 아이콘이 ! 상태로 바뀌니 툴팁 메시지를 확인해 주세요.

한 가지 더 알려 드릴 것이 있습니다. 윈도우 11의 ‘스마트 앱 컨트롤’이 켜진 PC에서는 서명 없는 개인 제작 스크립트가 통째로 차단될 수 있습니다.

여기서 흔히 하는 오해가 하나 있습니다. 파일을 마우스 오른쪽으로 눌러 ‘관리자 권한으로 실행’을 고르면 풀릴 것 같지만, 스마트 앱 컨트롤은 권한이 아니라 서명과 평판을 보는 기능입니다. 권한을 높여도 결과는 같습니다. 스마트스크린과 달리 ‘무시하고 실행’ 같은 예외 버튼도 없습니다.

남은 방법은 설정 > 개인 정보 및 보안 > Windows 보안 > 앱 및 브라우저 컨트롤에서 스마트 앱 컨트롤을 끄는 것뿐인데, 한 번 끄면 되켜기가 까다롭고 윈도우 버전에 따라 다시 설치해야 할 수도 있습니다. 위의 차단 해제 절차로도 안 풀린다면 이 기능을 끌지는 각자 판단할 문제이니, 그 PC에서는 설치를 포기하는 쪽도 충분히 괜찮은 선택입니다.

4. 옵션 — 표시 기준과 갱신 주기

⚙️ 아이콘을 눌러 나오는 메뉴에서 두 가지를 고를 수 있습니다.

먼저 아이콘에 어떤 숫자를 띄울지 고릅니다. 5시간 창과 주간 한도 중에서 선택하는데, 맥에서 주간을 고르면 ✳ 주15%처럼 ‘주’ 글자가 붙어 어느 기준인지 헷갈리지 않습니다. 오늘 하루 작업 리듬을 볼 때는 5시간 창이, 일주일 예산을 관리할 때는 주간 한도가 편합니다.

갱신 주기는 1분, 2분, 3분 중에서 고릅니다. 기본값이자 가장 추천하는 쪽은 3분입니다. 만드는 과정에서 1분 간격으로 돌려 보니 사용량 조회 주소가 잦은 요청에 일시 제한(429)을 걸었습니다. 제한에 걸려도 앱이 마지막 정상 수치를 유지한 채 조용히 다시 시도하도록 만들어 두긴 했지만, 굳이 자주 부를 이유가 없습니다. 두 설정 모두 저장되어 재부팅 후에도 그대로 유지됩니다. 저장소의 README에는 아직 1분 갱신으로 적혀 있는데, 이 선택 기능은 그 뒤에 넣은 것이라 앱 메뉴 쪽이 최신입니다.

제거와 되돌리기

지우는 것도 간단합니다. 맥은 저장소 폴더의 CUBR-삭제.command를 더블클릭하면 앱 종료와 자동 시작 해제, 응용 프로그램 폴더 정리까지 한 번에 끝납니다. 윈도우는 설정 > 앱 > 설치된 앱에서 ClaudeUsageBar를 제거하거나 CUBR-Uninstall.bat을 더블클릭하면 됩니다. 어느 쪽이든 클로드 코드 로그인 정보는 앱 것이 아니므로 그대로 남습니다. 앱만 지워지고 클로드 코드는 계속 쓰실 수 있습니다.

쓰기 전 알아 두실 점

⚠️ 이 앱이 쓰는 사용량 조회 주소는 앤트로픽이 공식 문서로 공개한 API가 아닙니다. 클로드 코드의 /usage 화면이 안에서 쓰는 것과 같은 주소입니다. 문서로 공개된 것이 아닌 만큼 앤트로픽이 형식을 바꾸면 표시가 멈출 수 있습니다. 그 경우에도 비용이 발생하거나 계정에 문제가 생기지는 않고, 메뉴에 오류 메시지가 뜰 뿐입니다.

인증 토큰은 클로드 코드가 저장해 둔 곳에서 읽어 앤트로픽 서버에만 보내고, 제3자 서버로는 어디에도 가지 않습니다. 토큰이 만료되면 앱이 스스로 다시 받아 저장소에 되써 두기 때문에 클로드 코드 로그인도 함께 유지됩니다. 윈도우 버전은 트레이 특성상 툴팁에 넣을 수 있는 글자 수가 짧아, 자세한 내용은 아이콘을 오른쪽으로 눌러 메뉴에서 보시는 편이 낫습니다.

🔗 저장소: aimatters-ClaudeUsageBar

쓰시다가 막히는 부분이나 고쳤으면 하는 점이 있으면 저장소 이슈로 남겨 주세요. 자세한 내용은 저장소의 README에서 확인할 수 있습니다.

이미지 출처: 이디오그램 생성