Claude Code 세션에 실제로 많은 양을 차지하는 것은 무엇일까? 툴 결과를 계산해 보세요.

만약 Claude Code 사용 한도를 예상보다 빠르게 소진하고 있다면, 아무것도 변경하기 전에 어떤 툴이 가장 많은 텍스트를 세션에 넣었는지 확인하세요. 세션 로그는 사용자 디스크에 있으니 간단한 스크립트로 순위를 매길 수 있으며, 그 답은 종종 당신이 비난하려던 것이 아닐 때가 많습니다.

먼저 측정해야 합니다. 그래야 저의 말이나 다른 누구의 말도 믿을 필요가 없습니다. 저는 jCodeMunch를 작성했기 때문에, 솔직히 이 조사에 매우 크지만 또한 매우 인기 있는 개(dog)를 가지고 있습니다.

툴 결과가 계산되어야 하는 이유

Claude Code는 모든 요청과 함께 전체 대화 내용을 전송하며, 모델이 툴을 사용할 때마다 그 툴 결과를 담은 또 다른 요청을 보냅니다. 이는 Anthropic의 자체 비용 문서를 따른 것이지 제가 만든 것이 아닙니다. 따라서 큰 파일 읽기(file read)가 세션에 한 번 들어가면, /clear를 하거나 세션이 압축될 때까지 모든 요청에서 계속 따라다닙니다. 캐싱은 재읽기를 더 저렴하게 만듭니다. 하지만 무료로 만드는 것은 아니며, 구독의 경우 여전히 사용량 창(window)을 차지합니다.

내장된 보기 기능들

이것들을 먼저 실행하세요. 비용은 들지 않습니다.

/context는 현재 컨텍스트 창을 무엇이 점유하고 있는지 보여줍니다. Pro 또는 Max 플랜의 경우, /usage는 최근 사용량을 스킬(skills), 서브 에이전트(subagents), 플러그인(plugins) 및 개별 MCP 서버별로 세분화하여 보여주며, 이 중 하나가 최근 사용량의 10%를 초과하는 경우 긴 컨텍스트나 캐시 누락 등의 문제를 표시합니다.

하지만 어느 것 하나는 어떤 툴 호출과 파일이 그 텍스트를 넣었는지 알려주지 않습니다. 그것은 로그에 있습니다.

로그

Claude Code는 각 세션을 ~/.claude/projects/ 아래의 JSONL 파일로 보관합니다. 툴 호출(tool call)은 ID와 이름이 있는 tool_use 블록입니다. 그 결과는 같은 ID를 가진 tool_result 블록으로 나중에 라인에 돌아옵니다. 이 두 가지를 결합하고, 각 결과의 토큰 수를 세고, 툴별로 그룹화하세요.

# toolcost.py
import collections, glob, json, os, sys

...

pip install tiktoken
python toolcost.py                        # 가장 최근 세션
python toolcost.py path/to/session.jsonl  # 또는 특정 파일

로컬 파일을 읽고 테이블을 출력합니다. 기기를 벗어나는 것은 없기 때문에 중요하며, 이 로그에는 사용자의 프롬프트와 소스 코드가 담겨 있습니다.

두 가지 솔직한 제한 사항이 있습니다. cl100k_base는 Claude의 토크나이저가 아니므로, 이를 사용하여 순위를 매기고 청구서로 취급하지 마십시오. 그리고 각 결과는 도착한 크기 기준으로 한 번 계산됩니다. 따라서 긴 세션 초기에 큰 파일을 읽은 것이 마지막에 큰 파일을 읽은 것보다 더 많은 비용을 발생시키지는 않습니다.

로그 형식은 문서화되어 있지 않으며 버전별로 변경됩니다. 스크립트가 빈 테이블을 출력하면, 파일을 열어 몇 줄을 확인해 보세요(오늘 제 경우인 2026-10-12에는 작동했습니다).

테이블 읽기

Bash가 위에 있는 경우? 그것은 보통 테스트 출력이나 빌드 로그입니다. 모델이 보기 전에 필터링하거나 (Anthropic의 비용 페이지에는 실패한 줄만 유지하는 기능이 있습니다) 소음이 많은 작업은 서브 에이전트에게 맡겨서 요약본만 돌아오게 하세요.

MCP 도구가 위에 있는 경우 서버가 텍스트 벽으로 답변합니다. 더 적게 요청할 수 있는지 확인해 보세요. 만약 불가능하다면, 하루 종일 연결할 필요가 있는지 결정하세요.

Read가 위에 있고 그 아래에 소스 파일 목록이 있는 경우는 에이전트가 여러 파일을 열어 일부를 살펴보는 것을 의미합니다. 나머지 내용은 이 경우에 관한 것입니다.

필요한 부분 옆에서 전체 파일이 비용을 차지하는 것

여기에 기본 Python으로 확인할 수 있는 예시가 있습니다. CPython 3.12.4에서 json/decoder.py는 3,024 토큰(tiktoken cl100k_base)입니다. 그 안에 있는 하나의 함수인 py_scanstring은 557 토큰입니다.

import ast, json.decoder, tiktoken

enc = tiktoken.get_encoding("cl100k_base")
...

따라서 그 함수가 필요하고 파일을 읽어야 했던 에이전트는 자신이 필요한 것보다 5배 이상을 사용했습니다. 이것은 356줄짜리 파일입니다. 이 간격은 파일 크기에 따라 커지며, 작은 파일에서는 존재하지 않습니다.

해결책, 가장 저렴한 순서대로

더 좁은 질문을 하세요.

만약 여러분이 타입 언어(typed language)로 작업한다면, 해당 언어의 코드 인텔리전스 플러그인을 설치하세요. Anthropic의 문서에 따르면 단일 'go-to-definition' 호출은 grep을 사용한 후 여러 후보 파일을 읽는 것과 동일합니다. 이는 1차 제공(first-party) 기능이며 무료입니다.

또는 jCodeMunch가 하는 것처럼 심볼 인덱스(symbol index)를 사용하세요. 이 도구는 저장소 전체를 한 번 색인화(index)하고, 에이전트에게 파일 전체를 읽어야 할 경우 바이트 오프셋(byte offset)을 통해 하나의 함수나 클래스를 전달합니다. 설정은 두 개의 명령어만 필요하며 API 키 없이 실행됩니다:

pip install jcodemunch-mcp
jcodemunch-mcp init

제가 발표한 벤치마크 결과에 따르면, 3개의 실제 저장소(real repos)에서 15가지 작업에 걸쳐 코드 읽기 토큰(code-reading tokens)이 평균 95% 감소했습니다. 홈페이지의 99.8% 수치는 fastapi/fastapi에 대한 단일 쿼리이며, 전체 소스 트리(source tree)를 읽는 데 214,312 토큰이 필요했지만 인덱스를 통해 약 480 토큰으로 줄었습니다. 어떤 에이전트도 전체 트리를 읽지는 않으므로 이 수치는 최대치로 간주하세요.

어떤 것을 선택하든, 동일한 종류의 작업을 수행하는 세션에 대해 toolcost.py를 다시 실행하세요. 인덱스 자체의 결과도 표에 나타나며(제 경우 mcp__jcodemunch__ 행), 이 또한 비용으로 계산됩니다. 만약 'Read' 행이 추가된 행들보다 더 많이 줄어들지 않았다면, 그것은 도움이 되지 않는 것입니다. 제거하세요.

짧은 답변

토큰 수가 적다는 것이 청구서가 작다는 의미인가요? API 키를 사용하는 경우, 입력 지출(input spend)도 비례하여 감소합니다. Pro 또는 Max에서는 어느 쪽이든 동일한 금액을 지불합니다. 달라지는 것은 한도에 도달하기까지 작업할 수 있는 시간입니다.

tiktoken으로 Claude에게 충분한가요? 세션 내에서 하나의 도구를 다른 도구와 순위를 매기기에는 그렇습니다. 정확한 계산을 위해서는 그렇지 않습니다.

Cursor나 Codex에도 적용되나요? 이 스크립트는 Claude Code의 로그만 읽습니다. 이 방법은 자신의 도구 결과를 기록하는 모든 에이전트에 적용됩니다. 저는 그들의 형식을 확인하지 않았습니다.

파일들이 모두 작다면요? 그렇다면 파일 읽기는 아마도 문제가 아닐 것이고, 인덱스는 큰 도움이 되지 않을 것입니다. 다른 행들을 살펴보세요.

만약 여러분의 표에 제가 다루지 않은 내용이 있다면, 저는 그것을 보고 싶습니다...