클로드 코드 상태줄: 터미널 하단을 나만의 대시보드로

클로드 코드로 긴 작업을 하다 보면 궁금한 게 생깁니다. 컨텍스트 윈도우를 얼마나 쓴 거지? 비용은 지금 얼마쯤 됐지? 매번 /cost나 /model을 쳐서 확인할 수 있긴 한데 작업 흐름이 끊기죠.

상태줄(statusline)은 이런 정보를 터미널 하단에 항상 띄워주는 기능입니다. 셸 스크립트 하나로 컨텍스트 사용량이나 비용, Git 브랜치 같은 걸 실시간 대시보드처럼 꾸밀 수 있어요. 한번 설정해두면 작업 흐름을 끊지 않고 세션 상태를 한눈에 파악할 수 있습니다.

상태줄이 뭔가요?

상태줄은 클로드 코드 화면 맨 아래에 붙는 커스텀 바입니다. 사용자가 지정한 셸 스크립트를 실행하고 그 출력을 화면 하단에 표시하는 단순한 구조예요.

동작 원리는 간단합니다. 클로드 코드가 JSON 형태의 세션 데이터를 스크립트의 stdin으로 넘기면 스크립트가 거기서 필요한 정보를 뽑아 stdout으로 출력해요. 그러면 그게 화면 하단에 나타납니다.

스크립트가 다시 실행되는 타이밍은 어시스턴트 응답 직후, 권한 모드 변경, vim 모드 토글 이렇게 세 가지예요. 빠르게 연속으로 바뀌는 경우엔 300ms 디바운스가 걸려서 깜빡임 없이 부드럽게 갱신됩니다. 로컬에서 실행되니까 API 토큰을 소비하지도 않고요.

가장 쉬운 설정법: /statusline

처음 설정할 때는 /statusline 명령어가 가장 편합니다. 자연어로 원하는 걸 설명하면 Claude가 스크립트를 자동으로 생성해줘요.

/statusline 모델 이름이랑 컨텍스트 사용률을 프로그레스 바로 보여줘

이렇게 입력하면 ~/.claude/ 디렉토리에 스크립트 파일이 생기고 settings.json도 자동으로 업데이트됩니다. 더 이상 상태줄이 필요 없어지면 /statusline delete로 깔끔하게 제거할 수 있어요.

수동으로 설정하기

직접 스크립트를 작성하고 싶다면 settings.json에 statusLine 필드를 추가하면 됩니다.

~/.claude/settings.json

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

type은 현재 "command"만 지원하고, command에는 실행할 스크립트 경로나 인라인 명령어를 넣습니다. padding은 좌우 여백을 문자 단위로 지정하는 선택 옵션이에요.

스크립트 파일 대신 한 줄짜리 인라인 명령어를 쓸 수도 있습니다.

~/.claude/settings.json

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

간단한 정보만 표시할 때는 이쪽이 파일 하나 덜 관리해도 되니까 편해요. 다만 조건 분기나 색상 같은 게 필요해지면 스크립트 파일로 분리하는 게 낫습니다.

어떤 데이터를 쓸 수 있나요?

클로드 코드가 스크립트에 넘겨주는 JSON에는 꽤 다양한 필드가 들어 있습니다.

가장 기본적인 건 모델과 워크스페이스 정보예요. model.display_name으로 현재 모델명을, workspace.current_dir로 작업 디렉토리를 확인할 수 있습니다.

아마 가장 자주 쓰게 될 필드는 컨텍스트 윈도우 관련 필드일 텐데요. context_window.used_percentage로 사용률을 바로 가져올 수 있고 context_window.context_window_size로 전체 크기(기본 200k, 확장 시 1M)도 확인됩니다. context_window.remaining_percentage는 남은 비율을 미리 계산해주니까 스크립트에서 직접 산수할 필요가 없어요.

비용 추적도 가능합니다. cost.total_cost_usd가 세션 누적 비용이고 cost.total_duration_ms가 세션 총 경과 시간이에요. cost.total_lines_added와 cost.total_lines_removed로 이 세션에서 코드를 얼마나 수정했는지까지 볼 수 있습니다.

Claude.ai Pro/Max 구독자라면 rate limit 필드도 활용할 수 있어요. rate_limits.five_hour.used_percentage로 5시간 롤링 윈도우 사용률을, rate_limits.seven_day.used_percentage로 7일 사용률을 확인하면 됩니다.

그 외에 session_id, version, vim.mode, agent.name, 워크트리 정보(worktree.branch, worktree.path) 같은 필드도 있습니다.

주의할 점이 하나 있는데 첫 번째 API 호출 전에는 일부 필드가 null일 수 있어요. 스크립트에서 jq의 // 0 같은 폴백 처리를 꼭 넣어줘야 빈 화면이 뜨는 걸 막을 수 있습니다.

실전 예제: 컨텍스트 진행 바

가장 인기 있는 상태줄은 모델 이름과 컨텍스트 사용률을 프로그레스 바로 보여주는 형태입니다.

~/.claude/statusline.sh

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

BAR_WIDTH=10
FILLED=$((PCT * BAR_WIDTH / 100))
EMPTY=$((BAR_WIDTH - FILLED))
BAR=""
[ "$FILLED" -gt 0 ] && printf -v FILL "%${FILLED}s" && BAR="${FILL// /▓}"
[ "$EMPTY" -gt 0 ] && printf -v PAD "%${EMPTY}s" && BAR="${BAR}${PAD// /░}"

echo "[$MODEL] $BAR $PCT%"

출력 예시

[Claude 4.6 Opus] ▓▓░░░░░░░░ 25%

cat으로 stdin을 읽고, jq로 필요한 필드를 추출한 다음, 프로그레스 바를 문자열로 조립해서 출력합니다. 간단하지만 컨텍스트 윈도우가 차오르는 걸 시각적으로 바로 알 수 있어서 실용적이에요.

같은 걸 Python으로도 작성할 수 있습니다.

~/.claude/statusline.py

#!/usr/bin/env python3
import json, sys

data = json.load(sys.stdin)
model = data["model"]["display_name"]
pct = int(data.get("context_window", {}).get("used_percentage", 0) or 0)

filled = pct * 10 // 100
bar = "▓" * filled + "░" * (10 - filled)

print(f"[{model}] {bar} {pct}%")

Python이 편하다면 이쪽이 jq 없이도 동작하니까 더 나을 수 있어요.

실전 예제: Git 상태 + 컬러

프로젝트 디렉토리와 Git 브랜치, 스테이징된 파일 수까지 한눈에 보여주는 버전입니다. ANSI 이스케이프 코드로 색상도 넣었어요.

~/.claude/statusline.sh

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')

GREEN='\033[32m'
YELLOW='\033[33m'
RESET='\033[0m'

if git -C "$DIR" rev-parse --git-dir > /dev/null 2>&1; then
    BRANCH=$(git -C "$DIR" branch --show-current 2>/dev/null)
    STAGED=$(git -C "$DIR" diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')
    MODIFIED=$(git -C "$DIR" diff --numstat 2>/dev/null | wc -l | tr -d ' ')

    GIT_INFO=""
    [ "$STAGED" -gt 0 ] && GIT_INFO="${GREEN}+${STAGED}${RESET}"
    [ "$MODIFIED" -gt 0 ] && GIT_INFO="${GIT_INFO} ${YELLOW}~${MODIFIED}${RESET}"

    echo -e "[$MODEL] ${DIR##*/} | $BRANCH $GIT_INFO"
else
    echo "[$MODEL] ${DIR##*/}"
fi

스테이징된 파일은 초록색 +로, 수정된 파일은 노란색 ~로 표시됩니다. 여기서 git 명령어에 -C "$DIR"을 붙인 이유가 있는데요. 상태줄 스크립트는 클로드 코드의 작업 디렉토리가 아닌 별도 환경에서 실행될 수 있어서 디렉토리를 명시해줘야 합니다.

실전 예제: 비용과 시간 추적

API 요금제를 쓰고 있다면 세션별 비용 추적이 중요할 텐데요.

~/.claude/statusline.sh

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')

COST_FMT=$(printf '$%.2f' "$COST")
DURATION_SEC=$((DURATION_MS / 1000))
MINS=$((DURATION_SEC / 60))
SECS=$((DURATION_SEC % 60))

echo "[$MODEL] $COST_FMT | ${MINS}m ${SECS}s"

출력 예시

[Claude 4.6 Opus] $1.37 | 12m 34s

Opus 같은 고성능 모델로 긴 작업을 할 때 비용이 실시간으로 보이니까 모델 전환 타이밍을 잡기 좋아요.

멀티라인으로 종합 대시보드 만들기

상태줄은 echo를 여러 번 하면 여러 줄로 표시됩니다. 이걸 활용하면 꽤 풍성한 대시보드를 만들 수 있어요.

~/.claude/statusline.sh

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')

CYAN='\033[36m'; GREEN='\033[32m'; YELLOW='\033[33m'; RED='\033[31m'; RESET='\033[0m'

# 컨텍스트 사용률에 따라 색상 변경
if [ "$PCT" -ge 90 ]; then BAR_COLOR="$RED"
elif [ "$PCT" -ge 70 ]; then BAR_COLOR="$YELLOW"
else BAR_COLOR="$GREEN"; fi

FILLED=$((PCT / 10)); EMPTY=$((10 - FILLED))
printf -v FILL "%${FILLED}s"; printf -v PAD "%${EMPTY}s"
BAR="${FILL// /█}${PAD// /░}"

MINS=$((DURATION_MS / 60000)); SECS=$(((DURATION_MS % 60000) / 1000))

BRANCH=""
git rev-parse --git-dir > /dev/null 2>&1 && BRANCH=" | $(git branch --show-current 2>/dev/null)"

# 첫째 줄: 모델, 디렉토리, 브랜치
echo -e "${CYAN}[$MODEL]${RESET} ${DIR##*/}$BRANCH"
# 둘째 줄: 컨텍스트 바, 비용, 시간
COST_FMT=$(printf '$%.2f' "$COST")
echo -e "${BAR_COLOR}${BAR}${RESET} ${PCT}% | ${YELLOW}${COST_FMT}${RESET} | ${MINS}m ${SECS}s"

첫째 줄에 모델과 Git 정보를, 둘째 줄에 컨텍스트 바와 비용을 배치했습니다. 컨텍스트 사용률이 70%를 넘으면 노란색, 90%를 넘으면 빨간색으로 바뀌니까 컨텍스트가 부족해지기 전에 대응할 수 있어요.

Rate Limit 모니터링 (Pro/Max)

Claude.ai Pro나 Max 요금제를 쓰고 있다면 rate limit을 상태줄에 표시할 수 있습니다.

~/.claude/statusline.sh

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
WEEK=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')

LIMITS=""
[ -n "$FIVE_H" ] && LIMITS="5h: $(printf '%.0f' "$FIVE_H")%"
[ -n "$WEEK" ] && LIMITS="${LIMITS:+$LIMITS }7d: $(printf '%.0f' "$WEEK")%"

[ -n "$LIMITS" ] && echo "[$MODEL] | $LIMITS" || echo "[$MODEL]"

5시간 윈도우와 7일 윈도우 사용률을 함께 표시합니다. rate_limits 필드는 Pro/Max 구독자의 첫 API 응답 이후에만 나타나기 때문에 // empty로 빈 값 처리를 해줘야 해요. API 요금제 사용자에게는 이 필드가 아예 없으니까 자연스럽게 모델 이름만 표시됩니다.

대규모 저장소에서의 성능 팁

Git 명령어는 큰 저장소에서 느려질 수 있습니다. 상태줄이 매번 git diff를 돌리면 응답이 끝날 때마다 살짝 지연이 생겨요. 이럴 때 캐싱이 도움이 됩니다.

~/.claude/statusline.sh

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')

CACHE_FILE="/tmp/statusline-git-cache"
CACHE_MAX_AGE=5

cache_is_stale() {
    [ ! -f "$CACHE_FILE" ] || \
    [ $(($(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || echo 0))) -gt $CACHE_MAX_AGE ]
}

if cache_is_stale; then
    if git -C "$DIR" rev-parse --git-dir > /dev/null 2>&1; then
        BRANCH=$(git -C "$DIR" branch --show-current 2>/dev/null)
        STAGED=$(git -C "$DIR" diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')
        MODIFIED=$(git -C "$DIR" diff --numstat 2>/dev/null | wc -l | tr -d ' ')
        echo "$BRANCH|$STAGED|$MODIFIED" > "$CACHE_FILE"
    else
        echo "||" > "$CACHE_FILE"
    fi
fi

IFS='|' read -r BRANCH STAGED MODIFIED < "$CACHE_FILE"

if [ -n "$BRANCH" ]; then
    echo "[$MODEL] ${DIR##*/} | $BRANCH +$STAGED ~$MODIFIED"
else
    echo "[$MODEL] ${DIR##*/}"
fi

/tmp/statusline-git-cache 파일에 Git 정보를 저장하고 5초마다 갱신합니다. 5초 사이에 업데이트가 여러 번 일어나도 캐시된 값을 쓰니까 Git 명령어를 반복 실행하지 않아요. 모노레포 같은 대규모 저장소에서 특히 효과적입니다.

문제가 생겼을 때

상태줄을 설정했는데 안 보이거나 이상하게 동작할 때 확인할 것들이 있습니다.

상태줄이 아예 안 나타나는 경우에는 스크립트 실행 권한부터 확인하세요. chmod +x ~/.claude/statusline.sh를 빠뜨리기 쉽습니다. 스크립트가 stderr가 아닌 stdout으로 출력하는지도 확인해야 해요. 설정에서 disableAllHooks가 true로 되어 있으면 상태줄도 함께 비활성화되니까 이 부분도 체크하세요. 그래도 안 되면 claude --debug로 실행해서 에러 메시지를 확인해보면 됩니다.

값이 --나 빈칸으로 나오는 경우는 대부분 첫 API 호출 전이라 필드가 null인 상태입니다. jq에서 // 0이나 Python에서 or 0 같은 폴백을 넣어주면 해결돼요.

ANSI 컬러 코드가 그대로 보이는 경우에는 echo -e 대신 printf '%b'를 써보세요. 터미널에 따라 echo -e가 이스케이프 시퀀스를 처리하지 못할 수 있거든요. macOS 기본 Terminal.app은 OSC 8 링크(클릭 가능한 텍스트)를 지원하지 않으니까 iTerm2나 Kitty, WezTerm을 쓰는 게 좋습니다.

workspace trust도 확인해야 합니다. 상태줄은 hooks와 마찬가지로 workspace trust를 승인한 디렉토리에서만 동작해요. statusline skipped · restart to fix 알림이 보이면 workspace trust 다이얼로그를 다시 확인해보세요.

스크립트 테스트하기

상태줄 스크립트는 클로드 코드 없이도 독립적으로 테스트할 수 있습니다. JSON을 파이프로 넘겨주기만 하면 돼요.

echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":42},"cost":{"total_cost_usd":0.73,"total_duration_ms":180000}}' | ~/.claude/statusline.sh

실제로 클로드 코드가 보내는 것과 같은 구조의 JSON을 넣으면 스크립트 출력을 바로 확인할 수 있습니다. 새 필드를 추가하거나 조건문을 바꿀 때 클로드 코드를 매번 재시작하지 않아도 되니까 반복 작업이 훨씬 빨라요.

마치며

상태줄은 작은 기능이지만 한번 설정하면 생각보다 자주 쳐다보게 됩니다. 컨텍스트 사용률이 빨간색으로 바뀌면 새 세션을 시작할 타이밍이라는 걸 바로 알 수 있어요. 비용이 올라가는 게 보이면 모델을 바꿔볼까 싶어지고, Git 브랜치가 항상 눈에 들어오니까 엉뚱한 브랜치에서 작업하는 실수도 줄어듭니다.

처음에는 컨텍스트 진행 바 하나만 넣어보세요. 쓰다 보면 뭐가 더 보고 싶은지 자연스럽게 알게 되고, /statusline 명령어로 자연어 한 줄이면 바로 수정할 수 있으니까요. 실시간 모니터링이 아니라 일별/월별 사용량 추이가 궁금하다면 ccusage도 살펴보세요.

더 자세한 내용은 Claude Code 상태줄 공식 문서를 참고하세요.

This work is licensed under CC BY 4.0

상태줄이 뭔가요?

가장 쉬운 설정법: /statusline

수동으로 설정하기

어떤 데이터를 쓸 수 있나요?

실전 예제: 컨텍스트 진행 바

실전 예제: Git 상태 + 컬러

실전 예제: 비용과 시간 추적

멀티라인으로 종합 대시보드 만들기

Rate Limit 모니터링 (Pro/Max)

대규모 저장소에서의 성능 팁

문제가 생겼을 때

스크립트 테스트하기

마치며

개발자를 위한 뉴스레터

관련 포스트

클로드 코드: 터미널 기반 코딩 에이전트

클로드 코드 설정 가이드: settings.json 파헤치기

클로드 코드 Hooks: AI 코딩 에이전트의 동작을 커스터마이징하기

클로드 코드의 언어 모델 선택과 추론 강도 조절