Claude Code 및 Codex 사용량을 CSV로 집계하는 CLI 'aiUsage' 제작

Claude Code나 Codex를 사용하면서 '이번 달에는 어떤 모델을 얼마나 사용했는지' 확인하고 싶었던 적이 없으신가요?

저는 매달 AI 이용량을 기사로 정리하고 있습니다. 그럴 때마다 저장된 로그를 조사하여 모델별 토큰 수를 집계하고, API 단가로 환산하는 작업을 수반했습니다. 이 작업을 하나의 명령어로 실행할 수 있게 만든 것이 Rust로 제작한 CLI aiUsage입니다.

macOS와 Windows 모두 지원합니다. 배포판은 Rust, Python, API 키가 필요 없으며, 설치 후 기간만 지정하면 CSV 파일을 출력할 수 있습니다.

무엇을 할 수 있나요

Claude Code 및 Codex의 로컬 저장 로그에서 지정한 기간의 이용량을 모델별로 집계합니다. 출력되는 항목은 다음 6가지입니다.

구분	일반 입력 (Normal Input)	캐시 읽기 (Cache Read)	캐시 쓰기 (Cache Write)	출력 (Output)	API 참고 환산 USD
모델명	토큰 수	토큰 수	토큰 수	토큰 수	API 단가로의 환산액

모델별로 한 줄씩 출력하며, 합계 행은 만들지 않습니다. 총합이나 그래프, 구독료와의 비교는 Excel이나 Google 스프레드시트 등에서 자유롭게 가공할 수 있습니다.

집계는 로컬에서 이루어집니다. 저장 로그를 외부로 전송하지 않으며, CSV에도 대화 본문은 포함되지 않습니다.

설치

OS에 맞는 명령어를 한 번 실행하면 됩니다. 최신 공식 릴리스를 가져와 SHA-256과 버전을 확인한 후 설치하는 것이 좋습니다. 관리자 권한은 필요하지 않습니다.

macOS

터미널에서 실행합니다. Apple Silicon 및 Intel 공통입니다.

curl -fsSL https://raw.githubusercontent.com/ttokunaga-ja/aiUsage/main/install.sh | sh

설치 경로는 ~/.local/bin/aiUsage 입니다. PATH도 자동으로 설정되므로, 새 터미널을 열고 다음 명령어로 확인합니다.

aiUsage --version

Windows

Windows x64에서는 PowerShell에서 실행합니다.

irm https://raw.githubusercontent.com/ttokunaga-ja/aiUsage/main/install.ps1 | iex

설치 경로는 %USERPROFILE%\.localin aiUsage.exe 입니다. 사용자 PATH와 현재 PowerShell의 PATH에 추가되므로, 그대로 동작 확인이 가능합니다.

aiUsage --version

실행 파일을 수동으로 가져오고 싶다면 GitHub Releases에서 다운로드할 수 있습니다.

먼저 한 달 치를 집계해 보기

Claude Code의 2026년 9월분이라면 다음 명령어를 사용합니다.

aiUsage claude --month 2026-09

Codex의 경우, 서비스 지정자를 chatgpt로 합니다.

aiUsage chatgpt --month 2026-09

여기서 chatgpt는 Codex의 로컬 저장 로그를 집계하는 지정자입니다. ChatGPT 웹 버전이나 iOS 버전의 대화 기록은 대상에 포함하지 않습니다.

결과는 명령어를 실행한 폴더의 usage.csv 에 저장됩니다. 초기 설정이나 로그인 작업이 필요 없습니다.

Claude Code와 Codex 결과를 모두 남기기

파일명은 항상 usage.csv 입니다. 두 가지 결과 모두를 남기고 싶다면, 저장할 폴더를 분리하는 것이 편리합니다. 다음 예시는 macOS 및 Windows의 PowerShell에서 사용할 수 있습니다.

mkdir claude-usage
cd claude-usage
aiUsage claude --month 2026-09
...

동일한 이름의 CSV가 있는 경우 덮어쓸지 확인합니다. y · yes · はい로 허용했을 때만 대체하고, Enter만 누르면 중지합니다.

일/월/년 및 임의 기간 지정 가능

집계하고 싶은 기간	명령어 예시
1일분	`aiUsage claude --day 2026-09-15`
...
날짜는 일본 시간으로 처리하며, `--to`

지정된 날짜를 포함합니다. 기간을 지정하지 않고 실행할 경우에도, 저장 로그의 전체 기간을 현재까지 집계합니다.

--day

・--month

・--year

・--all

은 이 중 하나를 지정해야 합니다. 이들과 --from

・--to

는 함께 사용할 수 없습니다.

어떤 기간을 지정하든, 출력은 해당 기간 전체를 모델별로 집계한 CSV입니다. --year

을 지정해도 월별 행으로 나뉘지 않습니다. 월별로 비교하고 싶다면 월별로 실행하여 CSV를 저장해야 합니다.

캐시를 분리하는 이유

API 환산 시에는 총 토큰 수에 보통 입력의 단가를 곱하는 것만으로는 금액이 크게 달라집니다. 일반 입력, 캐시 읽기, 캐시 쓰기, 출력 각각 단가가 다르기 때문입니다.

aiUsage는 로그에 기록된 내역을 사용하여 환산합니다.

Claude Code는 캐시 쓰기의 5분/1시간 차이도 환산에 반영합니다.
Codex는 입력에서 캐시 읽기를 제외한 부분을 일반 입력으로 취급합니다.
Codex의 추론 토큰은 출력에 포함되어 있으므로, 별도로 더하여 이중 계산하지 않습니다.

Claude Code의 동일 응답 업데이트나, Codex의 동일 누적 카운터 반복도 그대로 중첩해서 가산하지 않도록 했습니다. Codex는 누적 값의 차이분을 사용하며, 기간 시작 전 기록도 차이분의 기점(시작점)으로 읽습니다.

API 참고 환산 USD는 실행 파일에 동봉된 단가표를 사용한 금액입니다. 구독 실지불액이 아니라, 동봉된 단가를 지정 기간의 토큰 수에 적용한 비교용 값으로 사용할 수 있습니다. 단가가 미수록 모델 등 환산할 수 없는 경우에는 토큰 수를 제시하고 금액란을 공백으로 두어 기기(터미널)에 경고합니다.

읽는 로그

기본적으로 다음 위치를 읽습니다.

대상	저장소
Claude Code	`~/.claude/projects/*/.jsonl`
Codex	`~/.codex/sessions/*/.jsonl` 및 `~/.codex/archived_sessions/*/.jsonl`

CLAUDE_CONFIG_DIR나 CODEX_HOME을 설정한 경우에는 해당 저장소를 사용합니다. 원본 로그나 설정은 수정하지 않습니다.

집계에 사용하는 것은 남아있는 로그입니다. 스크린샷 보완이나 캐시 비율 추정은 하지 않으므로, 필요한 가공은 출력된 CSV 측에서 할 수 있습니다.

업데이트 및 제거

새 버전으로 업데이트할 때는 다음 명령어를 실행합니다.

aiUsage update

최신 정식 릴리스를 다운로드하여 검증한 후 실행 파일을 자동으로 교체합니다. 단가표도 함께 업데이트됩니다. 일반적인 집계 시에는 업데이트 확인을 수행하지 않습니다.

더 이상 사용하지 않을 때는 다음 명령어로 제거할 수 있습니다.

aiUsage uninstall

제거할 실행 파일의 경로를 표시하여 확인합니다. Windows에서는 프로세스 종료 후에 삭제하는 방식입니다. 출력된 CSV나 Claude Code 및 Codex의 저장 로그는 남아있습니다.

자세한 사용법은 aiUsage --help,
구현 또는 소스로부터 빌드하는 방법은 README에 정리되어 있습니다.

매월 이용량을 확인하고 싶거나, 모델별 사용법을 스프레드시트 프로그램으로 분석하고 싶은 분들에게 유용했으면 좋겠습니다.