CLI 도구 두세 개의 사용량 한도를 신경 쓰는데, 화면의 숫자가 누구 몫인지 확신할 수 없다면 한곳에 모아 봐도 답답함은 남는다. UsageCheck의 기록에도 코덱스는 5시간 0%·주간 7%, 다른 사용자의 클로드 계정은 5시간 0%·주간 0%로 표시된 증상이 있다. 공유 계정과 동시 프로젝트 환경에서 로컬 로그가 한 행에 합산·오귀속되던 사례다. 이 앱의 구조에서 살펴볼 핵심은 숫자를 모으는 기능과 함께 계정 신원을 확인하고, 귀속이 모호한 값은 합계에서 제외하는 기준이다.

UsageCheck는 Codex·Claude Code·Antigravity 계열 사용량을 macOS 메뉴바와 Windows 작업표시줄에서 확인하기 위한 앱이다. 서버가 반환한 쿼터 퍼센트와 로컬 로그의 토큰 합계를 구분하고, 로컬 로그를 어느 계정 몫으로 셀지 별도로 판정한다. 이 글에서 다루는 귀속 알고리즘과 v0.1.10 변경은 코딩 에이전트가 구현하고 다른 모델의 독립 검토자가 검증한 작업이다.

맥 메뉴바에 여러 CLI 계정의 사용량 게이지가 한 트레이 팝업 안에 나란히 표시되는 모습을 그린 일러스트
여러 벤더의 계정 사용량을 한 트레이 팝업에 모아 보여주는 개념 일러스트다. 실제 화면이나 측정 결과가 아니다.

여러 CLI 사용량을 트레이 하나로

2026년 7월 8일 재작성 기록에는 기존 Swift 메뉴바 앱을 참고용으로 보존하고 Tauri v2와 Rust로 새 앱을 구성했다고 남아 있다. 구조는 사용량을 처리하는 코어와 운영체제·화면을 연결하는 앱 계층으로 나뉜다. 코어는 사용량 모델, 중복 제거 집계, 코덱스·클로드 쿼터 파서와 코덱스·클로드·제미나이 계열 로컬 JSONL 로그 스캐너를 담는다. 앱 계층은 트레이 팝업 UI, 운영체제 자격증명 저장소를 사용하는 계정 스토어, OAuth 로그인, 토큰 갱신과 60초 주기 상태 확인을 맡는다.

당시 화면 사양은 계정별 5시간/7일 게이지였다. 다만 Gemini 계열로 분류된 Antigravity 연동은 재작성 당시 서버 쿼터 API를 이용할 수 없어 퍼센트 게이지 대신 로컬 로그의 토큰 합계로 표시했다. 서버 쿼터 퍼센트와 로컬 토큰 합계는 시각적으로 구분해 유지한다는 경계가 기록돼 있다. 서버가 반환하는 한도 대비 비율과 로컬에서 수집한 토큰 수는 서로 다른 지표이기 때문이다.

Codex·Claude·Gemini 계열 CLI의 로컬 로그를 사용량 처리 코어가 수집하고 트레이 팝업이 계정별로 보여주는 구조도
사용량 처리 코어와 트레이 팝업의 역할을 설명하는 개념 구조도다. 로그 수집 뒤에는 계정 귀속 판정이 필요하다.

로그 파서는 이벤트와 토큰 수를 읽어 내는 역할을 한다. 그 로그를 어느 계정 몫으로 셀지 정하는 계정 귀속은 별도의 문제다. 재작성 완료 기록 뒤인 7월 11일 작업 기록에는 공유 계정·동시 프로젝트 환경의 오귀속과 이를 처리하는 2단계 알고리즘이 남아 있다.

공유 계정과 동시 프로젝트가 사용량을 오염시킨다

앞서 나온 표시는 두 벤더의 수치가 서로 뒤바뀐 사례가 아니다. 기록된 문제는 공유 CLI 계정과 동시 프로젝트 때문에 프로필 루트 단위 합계를 계정 하나에 안전하게 붙일 수 없다는 것이었다. 프로필 루트는 CLI가 설정과 인증 정보를 저장하는 기준 디렉터리다. 여러 계정 항목이 겹치는 루트를 스캔할 수 있으므로, 경로가 같다는 사실만으로 로그의 소유 계정을 확정할 수 없다.

이 앱에서는 계정 ID나 이메일처럼 계정을 특정할 수 있는 신원 증거를 먼저 확인하도록 귀속 방식이 바뀌었다. 증거가 없을 때만 프로필 루트의 단독 연관으로 돌아가고, 후보가 여러 개면 집계에서 제외한다. 이는 잘못된 계정에 숫자를 붙이는 것보다 귀속을 거부하는 편을 택한 설계 원칙이다.

같은 이벤트가 여러 프로필 루트에서 수집되는 경우를 위한 중복 제거도 적용됐다. 루트를 넘나드는 이벤트에는 정렬 기준이 고정된 고유 키를 사용한다. 어느 루트를 먼저 스캔하느냐에 따라 집계 결과가 달라지지 않도록 하는 처리다.

동시 프로젝트 실행도 프로필 루트 단위 합계를 흔드는 조건으로 기록돼 있다. 구조상 같은 계정의 여러 프로젝트 로그가 수집되더라도, 프로젝트나 경로만으로 계정 신원을 대신할 수는 없다. 계정 신원을 기준으로 삼는 방식은 계정 사이의 오귀속을 줄인다. 한 계정을 여러 사람이 나눠 쓰는 경우의 사람별 몫까지 구분해 주지는 않는다.

신원 증거 먼저, 프로필 루트는 그다음

로컬 사용량 귀속에는 2단계 알고리즘이 적용됐다. 1단계는 신원 증거를 확인하고, 2단계는 증거가 없을 때 프로필 루트의 연관 관계를 확인한다. 경로 기반 추정이 신원 증거보다 먼저 결론을 내리지 않도록 순서가 정해져 있다.

1단계에서 계정 ID나 이메일이 정확히 하나의 계정과 일치하면 그 계정으로 확정한다. 둘 이상과 일치하면 모호한 상태로, 증거는 있지만 어느 계정과도 맞지 않으면 충돌로 처리한다. 브라우저 OAuth 계정은 이 충돌 판정에서 제외된다. 같은 루트에 연관된 다른 계정에서 이미 소유자가 확인됐다면, 그 계정에는 값을 붙이지 않고 ‘이 루트를 공유하고 있다’는 신호만 남긴다.

2단계는 신원 증거가 아예 없을 때만 실행된다. 프로필 루트에 계정 하나만 연관되면 그 계정으로 귀속하되, 실제 이벤트가 있을 때만 추정 귀속으로 격하한다. 이벤트가 없는 빈 프로필에는 추정 표시를 붙이지 않고 기존 스캔 상태를 유지하는 조건이 v0.1.28에서 보정됐다. 루트 하나에 계정이 둘 이상 연관되면 아무 계정에도 귀속하지 않고 모호하다는 신호를 남긴다.

두 단계의 결과는 심각도 순서로 병합된다. 여러 신호가 겹치면 더 심각한 신호가 최종 표시를 결정하고, 모호하거나 충돌하는 몫은 합계에서 0으로 처리한다. 이때의 0은 실제 사용량이 없다는 확인이 아니라 귀속할 수 없는 값을 합계에서 제외한 결과다.

계정 귀속 2단계 알고리즘 플로우 — 신원 증거 매칭 단계와 프로필 루트 연관 단계를 거쳐 모호하면 합계 0으로 처리하는 흐름
귀속 판정의 개념도다. 신원 증거 단계를 먼저 거치고 증거가 없을 때만 프로필 루트로 넘어간다.
판정 결과 귀속 처리
신원 증거 단일 매칭 해당 계정으로 정상 귀속
신원 증거 2개 이상 매칭 모호한 몫은 합계에서 제외(0)
증거는 있으나 어느 계정과도 불일치 충돌한 몫은 합계에서 제외(0), 단 브라우저 OAuth는 충돌 판정 예외
같은 루트의 다른 계정 소유로 확인 소유자가 아닌 계정에는 값을 붙이지 않고 공유 신호만 남김
증거 없음 · 프로필 루트에 계정 하나만 연관 해당 계정에 귀속하되 실제 이벤트가 있을 때만 추정으로 표시, 빈 프로필은 기존 스캔 상태 유지
증거 없음 · 한 프로필 루트에 계정 2개 이상 연관 모호한 몫은 합계에서 제외(0)

신원 증거부터 보고, 없으면 루트 연관을 본다. 그래도 모호하면 어느 계정에도 임의로 배정하지 않는다.

토큰은 화면에도 로그에도 남기지 않는다

서버 쿼터를 가져오는 인증 흐름에는 PKCE 기반 OAuth가 사용됐다. PKCE는 가로챈 인증 코드만으로 토큰을 교환하지 못하도록 보호하는 방식이며, state 검증은 로그인 요청과 콜백의 연관성을 확인한다. 당시 보안 리뷰에는 PKCE S256, state 검증, 루프백 리디렉션과 HTTPS 사용이 확인됐다고 남아 있다. 자격증명은 운영체제 저장소에 보관하고 토큰을 로그·IPC 메시지·평문 디스크에 노출하지 않는 경계도 검토됐다.

다만 재작성 기록의 OAuth 클라이언트 식별자와 엔드포인트는 실제 로그인으로 검증해야 하는 공개 추정값이었다. 이 값들을 추정으로 둔 이유는 실제 OAuth 로그인이 미검증이었기 때문이다. Windows 트레이·OAuth 흐름도 실제 Windows 호스트에서 핵심 기능을 확인하기 전까지 미검증 상태다. CI 빌드 성공과 해당 운영체제에서 로그인부터 트레이 표시까지 실행한 결과는 구분해야 한다.

벤더별 신원 확인 경로도 구분돼 있다. 7월 13일 기록에서 코덱스는 앱 서버 상태 탐색 요청을, 클로드는 상태 표시줄 브리지를 사용했다. 터미널에서 로그인한 프로필은 CLI 토큰을 앱으로 가져오지 않고 격리하는 방식으로 연결됐다.

로컬 로그 스캔은 파일 수정 시각 대신 이벤트 자체의 타임스탬프를 기준으로 한다. 한 번에 훑는 파일 수에는 상한이 있다. 신원 정보를 추출하는 과정에서도 액세스 토큰을 로그에 남기지 않는 규칙이 적용됐다.

조직 ID가 아니라 계정 ID에 뿌리를 내린다

2026년 7월 17일 v0.1.10에서는 클로드의 기대 신원 기준을 바꾸는 수정이 이뤄졌다. 기존 기준은 여러 계정이 공유하는 조직 식별자였다. 같은 조직 안에서 다른 계정으로 재로그인하면 조직값은 그대로여서 라벨이 혼동됐다. 조직을 식별하는 값으로는 그 안의 개별 계정을 구분할 수 없었던 것이다.

이 릴리스에서는 기대 신원의 앵커, 즉 신원을 대조할 기준이 조직 공유 식별자에서 계정 고유 식별자로 전환됐다. 화면 라벨은 이메일로 표시하고, 기존의 라벨 덮어쓰기 로직은 제거됐다. 기존 데이터를 새 기준으로 옮기는 시작 시점 마이그레이션은 락으로 보호하고, 여러 번 실행해도 같은 결과가 나오며 계정이 유실되지 않도록 설계됐다. 당시 기록에는 무료판·유료판·코어 테스트 묶음 통과와 두 에디션의 정적 분석 통과가 남아 있다.

같은 릴리스에서 GUI 앱의 최소 PATH 환경 때문에 CLI 실행 파일을 찾지 못하던 신원 확인 경로도 수정됐다. 프로필 루트의 설정 파일을 직접 읽는 방식을 우선하고 CLI 상태 탐색은 대체 경로로 남겼다. 외부 명령 실행에 반드시 의존하지 않고 신원을 읽도록 우선순위가 바뀐 것이다.

계정 목록을 읽는 방식도 보완됐다. 무료판이 유료 전용 공급자 항목이 섞인 공유 저장소를 읽을 때, 모르는 항목 하나 때문에 계정 목록 전체가 조용히 비던 버그가 있었다. 수정 뒤에는 항목별로 읽어 인식하지 못하는 항목만 건너뛰고, 저장소를 다시 쓸 때도 그 항목을 보존하도록 했다. 다만 목록 데이터 자체가 손상된 경우까지 정상으로 통과시키지는 않는다.

이 프로그래밍 사례에서 계정 신원 기준과 검증 경로는 함께 살펴볼 대상이다. v0.1.10의 결함은 기대 신원 앵커를 조직 공유값에서 계정 고유값으로 전환한 문제다. 7월 27일 v0.1.32에서 확인된, 기대 신원을 사용하지 않은 채 자격증명을 귀속하던 별도 결함은 다계정 로그인과 자격증명 오귀속 글에서 다룬다. 계정을 구분할 기준이 있어도 실제 처리 분기가 그 기준을 검증해야 한다.

확인 범위 밖에 남은 항목도 있다. 재작성 당시 Antigravity 연동에 쓰인 로컬 토큰 합계가 실제 사용량과 얼마나 차이 나는지는 실측 근거가 없다. 이 초기 표시 방식을 모든 Gemini 계열 서비스의 현재 API 사양으로 일반화할 수는 없다. Windows 트레이·OAuth 흐름도 실제 호스트에서 로그인부터 표시까지 확인하는 검증이 남아 있다.

자주 묻는 질문

신원 증거가 모호한 로그를 합계에서 0으로 처리하면 사용량이 과소 집계되지 않나요?

과소 집계될 수 있다. 이 앱의 설계는 잘못된 계정에 값을 붙이지 않도록, 신원 증거가 여러 계정과 매칭되거나 충돌로 판정된 몫을 합계에서 제외한다. 브라우저 OAuth 계정은 충돌 판정에서 제외된다. 신원 증거가 없고 프로필 루트에 계정 하나만 연관될 때는 그 계정에 귀속하되, 실제 이벤트가 있을 때만 추정으로 표시하고 빈 프로필은 기존 스캔 상태를 유지한다.

계정 고유 ID를 기준으로 삼으면 공유 계정의 사람별 사용량도 나눌 수 있나요?

아니다. 계정 고유 ID는 서로 다른 계정 사이의 오귀속을 줄일 뿐, 여러 사람이 같은 계정 자격 증명을 공유한 경우 사람별 몫까지 구분해 주지는 못한다. 이 한계 때문에 공유 계정의 합계는 별도로 해석해야 한다.

Gemini 사용량을 Codex·Claude와 같은 퍼센트 게이지로 보여주지 않는 이유는 무엇인가요?

2026년 7월 8일 재작성 기록에서 Gemini 계열로 분류한 Antigravity 연동은 서버 쿼터 API를 이용할 수 없어 로컬 로그의 토큰 합계로 표시했다. 서버의 한도 대비 퍼센트와 로컬 토큰 수는 서로 다른 지표이므로 표시를 구분했다. 이는 당시 앱의 구현 범위이며, 모든 Gemini 계열 서비스의 현재 API 사양을 뜻하지 않는다.