클로드 코드 사용량 보고서 session-report 스킬 리뷰: 스킬 없이 5분·2달러, 넣으면 1분·0.5달러

클로드 코드를 한 주 쓰고 나면 사용량이 어디로 갔는지 궁금해집니다. 한도에 자주 걸린다면 더 그렇습니다. session-report(세션 리포트)는 앤트로픽(Anthropic)이 공식 플러그인 저장소에 올린 스킬로, 내 컴퓨터에 쌓인 클로드 코드 세션 기록을 읽어 토큰·캐시·서브에이전트·비싼 요청을 한 장의 HTML 보고서로 만들어 줍니다. 스킬은 무료이고, 보고서를 만들 때 클로드 사용량이 듭니다. 정답을 미리 심어 둔 가상 일주일 세션 기록으로 같은 요청을 스킬 없이 두 번, 스킬을 넣고 두 번 보내 비교했습니다.

스킬은 클로드가 특정 일을 할 때 꺼내 읽는 작업 설명서 폴더(SKILL.md)입니다. 처음이라면 클로드 스킬 뜻과 만드는 법을 먼저 보세요.

결과부터 보기: 같은 기록, 두 가지 보고서

직접 눌러 보기: 네 번 만든 보고서 열어 보기 (클로드가 만든 파일을 손대지 않고 올림, 세션 기록은 실험용 예시 데이터)

따라 해 보기: 요청문과 실습 재료

스킬을 넣은 폴더에서 클로드 코드를 열고 아래 요청을 보냈습니다. 스킬 이름은 말하지 않았습니다. 클로드 코드가 처음이라면 클로드 코드 설치 방법을 먼저 보세요. 실습 재료(zip)에는 예시 세션 기록(input/projects), 그 기록을 만든 파이썬 파일, 요청문, 채점 기준, 조건별 결과 보고서를 넣었습니다.

input/projects 폴더에 지난주 내 클로드 코드 세션 기록(jsonl)이 들어 있어. 이걸로 사용량 보고서를 HTML 파일 하나로 만들어 줘. 어디에 토큰을 많이 썼는지, 캐시는 잘 쓰였는지, 가장 비싼 요청이 뭐였는지, 줄이려면 뭘 바꾸면 되는지 알 수 있게.

내 기록으로 보려면 첫 문장을 “지난 7일 내 클로드 코드 사용량”으로 바꾸면 됩니다. 스킬은 폴더를 말하지 않으면 내 컴퓨터의 ~/.claude/projects(클로드 코드가 대화 기록을 저장하는 곳) 전체에서 최근 7일을 읽습니다. 좋은 결과라면 클로드가 보고서 파일 경로를 알려 주고, 가장 많이 쓴 프로젝트와 요청을 전체 대비 %로 짚어 줍니다.

session-report에 들어 있는 것

플러그인에는 스킬 하나만 들어 있고 명령(/…)·에이전트·훅·MCP 서버는 없습니다. 스킬 폴더의 파일은 세 개입니다.

파일	하는 일
SKILL.md (42줄)	클로드가 따를 5단계: 분석 스크립트 실행 → 결과 JSON 훑기 → 템플릿 복사 → 데이터·발견·제안 채우기 → 파일 경로 알리기
analyze-sessions.mjs (875줄)	세션 기록(jsonl)을 읽어 토큰·캐시·서브에이전트·스킬·비싼 요청을 집계하는 Node.js 스크립트. 기본은 최근 7일, --since 24h·30d로 범위를 바꿈
template.html (569줄)	정렬·펼치기·막대가 들어 있는 보고서 틀. 클로드는 데이터 칸과 “발견” “제안” 칸만 채움

SKILL.md가 정한 규칙은 이렇습니다. 발견은 3~5줄로, 가능하면 전체 토큰 대비 %로 씁니다. 빨강은 낭비, 초록은 건강한 신호, 파랑은 중립입니다. 찾아볼 것으로 “한 프로젝트·스킬이 지나치게 많이 쓴 경우, 캐시 적중률 85% 미만, 요청 하나가 전체의 2% 넘음, 서브에이전트 1회 평균 100만 토큰 넘음, 캐시 끊김이 몰린 곳”을 적어 두었습니다. 제안은 1~4개를 특정 행에 연결해 씁니다.

분석 스크립트를 읽어 보니 파일 읽기 모듈만 쓰고 인터넷으로 보내는 코드는 없었습니다. 스크립트만 따로 돌려도 요약이 터미널에 나옵니다. 클로드 사용량을 쓰지 않고 숫자만 보고 싶을 때 쓸 만합니다.

출력 읽는 법: sessions(세션 수), api calls(모델 호출 수), human msgs(내가 보낸 요청 수), uncached(캐시 없이 읽음)·cache-create(캐시에 새로 씀)·cache-read(캐시에서 읽음), cache breaks(한 번에 10만 토큰 넘게 새로 읽은 횟수), subagents(서브에이전트 호출과 1회 평균)입니다.

1단계. 설치하기 (약 1분)

이 단계에서는 스킬을 클로드 코드에 넣습니다. 공식 저장소 README에 적힌 방법은 클로드 코드 안에서 아래 명령을 입력하는 것입니다. 이 방법은 사용자 전체 설정에 플러그인을 넣기 때문에 이번에는 시험하지 않았습니다.

/plugin install session-report@claude-plugins-official

이번에는 스킬 폴더만 작업 폴더(my-project, 내 폴더 이름으로 바꿈)에 복사했습니다. 그 상위 폴더에서 터미널로 실행합니다. 저장소 전체 대신 이 플러그인 폴더만 받는 명령입니다.

git clone --depth 1 --filter=blob:none --sparse https://github.com/anthropics/claude-plugins-official.git cpo
git -C cpo sparse-checkout set plugins/session-report
mkdir -p my-project/.claude/skills && cp -r cpo/plugins/session-report/skills/session-report my-project/.claude/skills/

실제 실행 기록 · macOS 26.1 · 작업 폴더 · 2026-10-19

$ git clone --depth 1 --filter=blob:none --sparse https://github.com/anthropics/claude-plugins-official.git cpo
Cloning into 'cpo'...

$ git -C cpo sparse-checkout set plugins/session-report && mkdir -p my-project/.claude/skills && cp -r cpo/plugins/session-report/skills/session-report my-project/.claude/skills/

$ ls my-project/.claude/skills/session-report && wc -l my-project/.claude/skills/session-report/*
SKILL.md
analyze-sessions.mjs
template.html
      42 my-project/.claude/skills/session-report/SKILL.md
     875 my-project/.claude/skills/session-report/analyze-sessions.mjs
     569 my-project/.claude/skills/session-report/template.html
    1486 total

이렇게 나오면 성공 my-project/.claude/skills/session-report에 SKILL.md, analyze-sessions.mjs, template.html이 보입니다.

• node: command not found가 나오면: 분석 스크립트는 Node.js로 돌아갑니다. 클로드 코드를 npm으로 설치했다면 이미 있습니다.
• git이 없다는 오류가 나오면: 저장소 페이지에서 Code > Download ZIP(코드 > ZIP으로 받기)으로 받아 plugins/session-report/skills/session-report 폴더만 복사해도 됩니다.

필요 없어지면 작업 폴더에서 아래 명령으로 지웁니다. 플러그인으로 설치했다면 터미널에서 claude plugin uninstall session-report@claude-plugins-official입니다.

rm -r .claude/skills/session-report

2단계. 보고서 만들기 (약 1분)

이 단계에서는 위 요청문을 보내 보고서를 받습니다. 두 번 모두 클로드는 요청을 받자마자 session-report 스킬을 불렀고, 요청에 적힌 input/projects를 스크립트의 --dir 옵션으로 넘겨 그 폴더만 읽었습니다. 데이터를 넣은 뒤 발견 5개와 제안 4개를 한국어로 썼습니다. 두 번 모두 “브라우저로 열어 보지는 않았고 화면 이름표는 영어 그대로”라고 알려 줬습니다. 1회차는 대화창의 마지막 답이 통째로 영어로 왔고, 보고서 안의 발견·제안은 한국어였습니다.

이렇게 나오면 성공 작업 폴더에 session-report-날짜-시각.html이 생기고, 열면 맨 위에 총 토큰과 발견 목록, 아래로 프로젝트별 막대·날짜별 타임라인·비싼 요청·캐시 끊김·서브에이전트·스킬 표가 나옵니다.

보고서의 영어 이름표 뜻: findings(발견), summary(요약), tokens by project(프로젝트별 토큰), session timeline by day(날짜별 세션), most expensive prompts(가장 비싼 요청), cache breaks(캐시 끊김), subagent types(서브에이전트 종류), skills & slash commands(스킬과 명령), recommendations(제안).

스킬 없이 vs 있이 비교 결과

세션 기록은 실험용으로 만든 가상 일주일치입니다(프로젝트 4개, 세션 10개). 실제 대화 기록을 그대로 쓰지 않으려고 만들었고, 일부러 문제 네 가지를 심었습니다. ① 월간 보고서 프로젝트의 “폴더 전체 엑셀 파일 다시 읽어서 12개월 보고서를 처음부터” 요청(가장 비싼 요청) ② 그 직전 1시간 쉬어서 생긴 캐시 끊김 ③ 블로그 프로젝트의 무거운 조사용 서브에이전트 ④ 카페 홈페이지에서 같은 수정 요청을 5일 내내 반복한 것입니다. 정답은 분석 스크립트를 직접 돌린 값으로 정했고, 채점 기준 10개는 실행 전에 SKILL.md에서 뽑아 고정했습니다. 요청문에는 넣지 않았습니다.

채점 항목	스킬 없이 1·2	스킬 있이 1·2
총 토큰 15.79M을 맞게 표시	✓ ✓	✓ ✓
캐시 적중률 92% 표시	✓ ✓	✓ ✓
프로젝트 4개별 사용량	✓ ✓	✓ ✓
가장 비싼 요청(“폴더 전체…”) 1위	✓ ✓	✓ ✓
캐시 끊김(32만 토큰) 지목	✓ ✓	✓ ✓
무거운 서브에이전트 지목	✓ ✓	✓ ✓
발견 3~5개, % 포함	✓ ✓	✓ ✓
줄이는 방법을 특정 요청에 연결	✓ ✓	✓ ✓
외부 요청 없는 HTML 한 파일	✓ ✓	✗ ✗
지정한 폴더만 읽음	✓ ✓	✓ ✓
합계	10/10 · 10/10	9/10 · 9/10

스킬 있이 놓친 한 항목은 템플릿이 글꼴(JetBrains Mono)을 구글 폰트에서 불러오기 때문입니다. 보고서를 열 때 구글 글꼴 서버로 요청이 갑니다. 인터넷이 없으면 기본 글꼴로 보일 뿐 내용은 그대로 나옵니다.

실행 기록 · 작업 폴더 runs.tsv에서 옮김 · 2026-10-19

조건(회차)        걸린 시간   달러    턴  도구 호출  불린 스킬              채점
none-1 스킬 없이   5분 남짓    2.130   24  19        claude-api, dataviz   10/10
none-2 스킬 없이   6분 남짓    2.494   33  27        claude-api, dataviz   10/10
skill-1 스킬 있이  1분 남짓    0.570   13  11        session-report         9/10
skill-2 스킬 있이  1분 남짓    0.536   10   8        session-report         9/10

스킬 없이: 분석 코드를 직접 짜고 달러로 환산

스킬 없이는 두 번 모두 기록 파일 구조부터 살펴본 뒤 파이썬 분석 코드를 새로 짰습니다. 그사이 클로드 코드에 들어 있는 claude-api 스킬로 Opus 5.5 단가를 찾고, dataviz 스킬로 차트 색을 골랐습니다. 그래서 보고서가 한국어 화면에 달러 금액, 비용 구성 막대, 요청별 비용 표까지 갖췄습니다. “엑셀 원본을 직접 읽히지 말고 집계 스크립트를 실행시켜 결과만 받기”처럼 절감액을 붙인 제안도 나왔습니다.

대신 두 번의 합계가 달랐습니다. 1회차는 12.97달러, 2회차는 16.7달러였습니다. 2회차 보고서에는 캐시 쓰기를 1시간 보관 단가로 셌고, 5분 보관 단가로 셈하면 약 13.0달러라고 적혀 있습니다. 같은 기록인데 가정 하나로 4달러 가까이 차이가 난 셈입니다. 시간은 스킬 쪽의 4~6배, 사용량은 4배 안팎이었습니다.

스킬 있이: 매번 같은 틀, 같은 숫자

스킬 쪽은 정해진 스크립트와 틀을 쓰므로 두 번의 숫자와 화면 구성이 같았습니다. 발견 5개도 거의 같은 내용이었습니다. “월간 보고서 요청 한 건이 전체의 37.5%”, “‘표 서식만 고쳐 줘’가 호출 3번에 139만 토큰(8.8%)”, “같은 블로그 조사를 두 번 돌려 37.0%”, “카페 홈페이지 같은 수정 5번 반복”, “캐시 적중률 92%로 양호”였습니다. 제안도 “바뀐 달만 반영”, “큰 작업 뒤 /clear”, “조사 결과를 파일로 저장해 재사용”, “반복 수정 규칙을 CLAUDE.md에” 네 가지로 같았습니다.

달러 금액은 없습니다. 보고서는 토큰과 비율만 보여 줍니다. 구독 요금제로 쓴다면 달러 환산보다 “어디서 한도를 빨리 쓰는지”가 중요하니 큰 문제는 아닙니다. 달러가 필요하면 스킬로 보고서를 만든 뒤 “API 단가로 환산해 줘”를 이어서 요청하면 됩니다(이 요청은 시험하지 않음).

이런 사람에게 권합니다

• ✅ 클로드 코드 사용량 한도에 자주 걸려서 어디서 많이 쓰는지 알고 싶은 사람. 1분 남짓이면 프로젝트별·요청별 비중이 나옵니다.
• ✅ 매주 같은 형식으로 사용량을 비교하고 싶은 사람. 틀이 고정이라 지난주 보고서와 나란히 볼 수 있습니다.
• ✅ 서브에이전트나 스킬을 많이 쓰는 사람. 서브에이전트 종류별·스킬별 표가 따로 나옵니다.
• ❌ 화면이 모두 한국어여야 하거나 달러 금액이 꼭 필요한 사람. 스킬 없이 요청하는 편이 맞지만, 시간과 사용량이 더 듭니다.

한계와 주의할 점

• 가상 세션 기록 한 벌로 조건마다 두 번씩만 돌렸습니다. 실제 기록은 더 길고 복잡해서 분석 시간과 결과가 다를 수 있습니다.
• 기본으로 ~/.claude/projects 전체를 읽습니다. 보고서에는 프로젝트 이름과 내가 보낸 요청 문장이 그대로 들어가니, 남에게 보여 주기 전에 확인하세요. 분석 요약은 대화를 거쳐 클로드에게 전달됩니다.
• SKILL.md는 중간 결과를 /tmp/session-report.json에 쓰라고 적었지만, 이번 두 번은 클로드가 세션 전용 임시 폴더에 저장했습니다. 여러 보고서를 동시에 만들면 같은 파일을 덮어쓸 수 있으니 하나씩 만드는 편이 안전합니다.
• 클로드 앱(웹·데스크톱 채팅)이나 다른 컴퓨터에서 쓴 사용량은 이 기록에 없습니다. 이 컴퓨터의 클로드 코드 기록만 셉니다.

대안

방법	다른 점	이럴 때 고르세요
session-report(이 글)	정해진 스크립트와 틀로 토큰·캐시·서브에이전트·비싼 요청을 한 장에	프로젝트별·요청별로 어디서 많이 쓰는지 빨리 보고 싶을 때
스크립트만 직접 실행	node analyze-sessions.mjs로 터미널 요약만, 클로드 사용량 없음	숫자만 보면 될 때
클로드 코드의 /usage	지금 요금제 한도를 얼마나 썼는지 보여 주는 기본 명령	남은 한도만 알면 될 때
스킬 없이 요청	클로드가 분석 코드를 짜서 한국어 화면·달러 환산까지	모양을 자유롭게 정하고 싶을 때, 시간·사용량이 4배 안팎 더 들어도 될 때

한도에 걸렸을 때 서버 장애인지 한도인지 가르는 법은 클로드 오류·먹통일 때 확인하는 법, 요금제별 차이는 클로드 요금제 정리에 있습니다.

자주 묻는 질문

클로드 코드 사용량은 어디서 확인하나요?

남은 한도는 클로드 코드의 /usage로, 어디에 썼는지는 이 스킬로 봅니다. 스킬이 읽는 원본은 ~/.claude/projects 안의 jsonl 파일입니다. 프로젝트(작업 폴더)마다 폴더가 하나씩 있습니다.

스킬 이름을 말해야 불리나요?

이번에는 “세션 기록으로 사용량 보고서를 HTML로”라는 요청만으로 두 번 다 불렸습니다. 확실히 하려면 “session-report 스킬로”를 앞에 붙이면 됩니다.

기간을 바꿀 수 있나요?

SKILL.md에 “24시간, 30일, 전체처럼 다른 범위를 말하면 따르라”고 적혀 있습니다. “지난 30일 사용량 보고서”처럼 요청하면 됩니다. 이번에는 기본 7일만 시험했습니다.

session-report 스킬은 무료인가요?

Apache 2.0 라이선스로 무료입니다. 보고서를 만들 때 이번 실험 기준 0.5달러대의 클로드 사용량이 들었고, 구독 요금제라면 요금제 한도에서 빠집니다. 다른 공식 플러그인은 클로드 스킬·플러그인 디렉터리 사용법에서 찾을 수 있습니다.

출처

session-report 플러그인 폴더, SKILL.md, anthropics/claude-plugins-official 저장소 README (모두 2026-10-19 확인, 저장소 별 42,965개, 플러그인 추가 2026-04-08)