Claude Code 하단에 토큰 사용량·예상 비용 표시하기

Claude Code를 쓰다 보면 "지금까지 토큰 얼마나 썼지? 비용은 얼마지?"가 궁금해집니다. 화면 맨 아래 줄에 이런 정보를 띄울 수 있는데, 이걸 statusline(상태줄) 이라고 합니다.

statusline은 어떻게 동작할까?

원리는 단순합니다.

1. Claude Code가 매 턴마다 세션 정보가 담긴 JSON을 stdin으로 스크립트에 넘겨줍니다.
2. 그 스크립트가 출력한 텍스트를 화면 하단에 그대로 보여줍니다.

즉, 비용·토큰 표시는 이 JSON만 파싱하면 끝입니다. 주요 필드는 이렇습니다.

방법 1. ccusage 쓰기 (제일 쉬움, 추천)

커뮤니티 도구 ccusage가 비용·토큰·번레이트를 다 계산해서 한 줄로 보여줍니다. ~/.claude/settings.json에 아래 내용만 추가하면 끝입니다.

{
  "statusLine": {
    "type": "command",
    "command": "npx -y ccusage statusline",
    "padding": 0
  }
}

출력 예시:

🤖 Opus 4.8 | 💰 $0.23 session / $1.23 today | 🔥 $0.12/hr | 🧠 25,000 (12%)

• session: 이번 대화에서 쓴 비용
• today: 오늘 누적 비용
• /hr: 시간당 소비 속도(번레이트)
• 🧠: 컨텍스트에 들어있는 토큰과 사용률

Node.js만 깔려 있으면 npx로 바로 동작합니다. (Windows도 동일)

방법 2. /statusline 으로 직접 만들기

Claude Code 프롬프트에 자연어로 시키면 스크립트를 자동으로 만들어 줍니다.

/statusline 모델 이름, 예상 비용($), 컨텍스트 사용률을 프로그레스 바로 보여줘

직접 스크립트를 쓰고 싶다면 stdin으로 들어오는 JSON을 파싱하면 됩니다. 예를 들어 bash라면:

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
echo "[$MODEL] 💰 $(printf '$%.2f' "$COST") | 🧠 ${PCT}%"

이 스크립트를 ~/.claude/statusline.sh로 저장하고 settings.json에서 가리키면 됩니다.

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

방법 3. 그냥 가끔 확인만 하고 싶다면

상태줄을 항상 띄우지 않아도, 프롬프트에 명령어를 입력해서 확인할 수 있습니다.

• /usage (또는 /cost, /stats) — 세션 비용, 소요 시간, 토큰 사용량, 코드 변경 줄 수를 한 번에 보여줍니다.

정리

처음이라면 ccusage로 시작하는 걸 추천합니다. settings.json 한 줄이면 비용 관리가 훨씬 편해집니다.