Claude Code 터미널 꾸미기 — Statusline 상태바 설정 완전 가이드

안녕하세요.

Claude Code를 매일 쓰다 보면 "지금 컨텍스트가 얼마나 찼지?", "이 세션에서 얼마나 썼지?" 같은 생각이 자주 들게 됩니다. 매번 /context를 치거나 직접 확인하기가 번거로웠는데, Claude Code에는 이 정보를 터미널 하단에 항상 표시해 주는 Statusline 기능이 있습니다. 설정해두면 모델명, 컨텍스트 사용률, 누적 비용, git 브랜치까지 한눈에 볼 수 있어 실제로 아주 유용합니다. 이번 글에서는 Statusline을 처음부터 직접 설정하는 방법을 단계별로 공유하여 보도록 하겠습니다.

 

□ Statusline이란

Statusline은 Claude Code 인터페이스 하단에 표시되는 사용자 정의 가능한 막대입니다. Claude Code가 응답할 때마다 쉘 스크립트를 실행하고, 그 스크립트가 출력하는 내용을 그대로 화면에 표시하는 방식으로 동작합니다.

작동 원리는 단순합니다. Claude Code가 현재 세션 상태를 JSON 형태로 스크립트에 전달하면, 스크립트가 그 중 원하는 값을 꺼내서 터미널에 출력합니다. 모델명, 컨텍스트 사용 퍼센트, 세션 비용, git 브랜치 등 수십 가지 정보를 자유롭게 조합할 수 있습니다.

표시 업데이트 시점은 새 응답이 완료됐을 때, /compact 실행 후, 권한 모드가 바뀔 때, vim 모드가 전환될 때입니다. 상태바는 로컬에서만 실행되므로 API 토큰을 별도로 소비하지 않습니다.

 

□ 사전 준비 — jq 설치

Statusline 스크립트는 JSON을 파싱할 도구가 필요합니다. 가장 많이 쓰이는 방법은 jq라는 경량 JSON 파서를 사용하는 것입니다.

설치 방법은 OS별로 다릅니다.

macOS (Homebrew):

brew install jq

Ubuntu / Debian:

sudo apt install jq

설치 확인:

jq --version

jq-1.7 이상이 출력되면 준비 완료입니다. Python이나 Node.js가 설치되어 있다면 jq 없이 내장 JSON 파서로 스크립트를 작성할 수도 있습니다. 아래 예제에서 Bash/Python/Node.js 세 가지 버전을 모두 소개합니다.

 

□ 가장 빠른 방법 — /statusline 명령

Claude Code 안에서 바로 /statusline 명령을 치면 원하는 내용을 자연어로 설명할 수 있습니다. 스크립트 파일 생성과 settings.json 수정까지 자동으로 처리해 줍니다.

/statusline 모델명과 컨텍스트 퍼센트를 진행률 바와 함께 보여줘

또는 영어로:

/statusline show model name, context percentage with a progress bar, and session cost

명령이 완료되면 ~/.claude/statusline.sh 파일이 생성되고 ~/.claude/settings.json에 설정이 자동 추가됩니다. 간단하게 바로 써보고 싶다면 이 방법이 제일 빠릅니다.

삭제하거나 초기화하고 싶을 때는:

/statusline remove

 

□ 수동 설정 방법 — 직접 스크립트 만들기

자동 생성보다 직접 제어하고 싶다면 수동으로 설정하는 방법을 추천드립니다. 과정은 세 단계입니다.

1단계 — 스크립트 파일 작성

~/.claude/statusline.sh 파일을 만들고 아래 내용을 붙여넣습니다.

#!/bin/bash
# Claude Code가 stdin으로 전달하는 JSON 읽기
input=$(cat)

# jq로 필요한 값 추출
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

# 폴더명만 추출해서 출력 (${DIR##*/})
echo "[$MODEL] 📁 ${DIR##*/} | ${PCT}% context"

2단계 — 실행 권한 부여

chmod +x ~/.claude/statusline.sh

3단계 — settings.json에 등록

~/.claude/settings.json 파일을 열고 statusLine 항목을 추가합니다.

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

이미 다른 설정이 있다면 최상위 객체 안에 statusLine 키만 추가하면 됩니다. 설정 저장 후 Claude Code에서 다음 메시지를 주고받으면 하단에 상태바가 나타납니다.

 

□ 표시할 수 있는 데이터 항목

Claude Code가 스크립트에 전달하는 JSON에는 다양한 정보가 담겨 있습니다. 자주 사용하는 핵심 항목은 다음과 같습니다.

모델 정보:
- model.display_name — 현재 모델 표시 이름 (예: Opus, Sonnet)
- model.id — 모델 ID (예: claude-opus-4-8)

컨텍스트 윈도우:
- context_window.used_percentage — 사용된 컨텍스트 비율 (0~100)
- context_window.remaining_percentage — 남은 비율
- context_window.context_window_size — 최대 컨텍스트 크기 (토큰)
- context_window.total_input_tokens — 현재 입력 토큰 수

비용 및 시간:
- cost.total_cost_usd — 현재 세션 누적 비용 (USD)
- cost.total_duration_ms — 세션 시작부터 경과 시간 (밀리초)
- cost.total_lines_added / cost.total_lines_removed — 변경된 코드 줄 수

작업 공간:
- workspace.current_dir — 현재 작업 디렉토리 전체 경로
- workspace.project_dir — 세션 시작 시 디렉토리
- workspace.repo.name — git 저장소 이름

기타:
- version — Claude Code 버전
- session_id — 세션 고유 ID
- effort.level — 추론 노력 수준 (low / medium / high / max)
- rate_limits.five_hour.used_percentage — 5시간 사용률 (Pro/Max 구독자)
- vim.mode — 현재 vim 모드 (NORMAL / INSERT / VISUAL)

 

□ 실전 예제 1 — 컨텍스트 진행률 바

가장 유용한 예제입니다. 컨텍스트가 몇 % 찼는지를 시각적인 막대로 표시하고, 사용량에 따라 색상이 바뀝니다.

#!/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)

# 진행률 막대 구성 (10칸)
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}%"

Python 버전을 선호한다면:

#!/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}%")

스크립트 저장 후 아래 명령으로 동작을 미리 테스트할 수 있습니다.

echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":35},"workspace":{"current_dir":"/Users/me/project"},"session_id":"test"}' | ~/.claude/statusline.sh

 

□ 실전 예제 2 — git 브랜치 + 색상

현재 git 브랜치와 변경 파일 수를 색상으로 구분해 표시합니다. 스테이징된 파일은 초록색, 수정된 파일은 노란색으로 나타납니다.

#!/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 rev-parse --git-dir > /dev/null 2>&1; then
    BRANCH=$(git branch --show-current 2>/dev/null)
    STAGED=$(git diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')
    MODIFIED=$(git diff --numstat 2>/dev/null | wc -l | tr -d ' ')

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

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

git 디렉토리 안에 있을 때만 브랜치 정보가 나타나고, 그 외에는 모델명과 폴더명만 표시됩니다.

 

□ 실전 예제 3 — 비용 + 경과 시간 추적

세션 누적 비용과 경과 시간을 함께 표시합니다. API 사용료를 실시간으로 파악하고 싶을 때 유용합니다.

#!/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 '$%.4f' "$COST")
DURATION_SEC=$((DURATION_MS / 1000))
MINS=$((DURATION_SEC / 60))
SECS=$((DURATION_SEC % 60))

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

소수점 4자리($%.4f)로 표시하면 소액 세션에서도 변화를 확인할 수 있습니다. 2자리($%.2f)로 바꾸면 $0.01 같은 형태로 더 깔끔하게 보입니다.

 

□ 실전 예제 4 — 종합 다중 라인

위 예제들을 모두 합쳐 2줄로 표시하는 가장 풍부한 구성입니다. 첫 줄에 모델·폴더·git 브랜치, 둘째 줄에 진행률 바·비용·시간을 표시하며 컨텍스트 사용률에 따라 바 색상이 바뀝니다 (70% 미만 초록 → 90% 미만 노랑 → 90% 이상 빨강).

#!/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))
COST_FMT=$(printf '$%.2f' "$COST")

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

# 2줄 출력
echo -e "${CYAN}[$MODEL]${RESET} 📁 ${DIR##*/}$BRANCH"
echo -e "${BAR_COLOR}${BAR}${RESET} ${PCT}% | ${YELLOW}${COST_FMT}${RESET} | ⏱️ ${MINS}m ${SECS}s"

이 스크립트를 ~/.claude/statusline.sh에 저장하고 settings.json에 등록하면 됩니다. padding 옵션을 추가하면 좌우 여백도 조절할 수 있습니다.

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

 

□ 성능 팁 — git 명령 캐싱

git status나 git diff 같은 명령은 대형 저장소에서 느릴 수 있습니다. 상태바가 응답마다 실행되기 때문에 체감 속도에 영향을 줄 수 있습니다. 이럴 때는 결과를 임시 파일에 5초간 캐싱하는 방식을 사용합니다.

중요한 점은 캐시 파일명에 session_id를 사용해야 한다는 것입니다. $$(프로세스 ID)를 쓰면 호출마다 값이 달라져 캐시가 의미 없어집니다. session_id는 같은 세션 동안 고정되어 있습니다.

CACHE_FILE="/tmp/statusline-git-$SESSION_ID"
CACHE_MAX_AGE=5

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

캐시 만료 여부를 먼저 확인하고, 만료됐을 때만 git 명령을 실행해서 결과를 파일에 저장하면 됩니다.

 

□ 자주 묻는 문제 해결

상태바가 표시되지 않을 때:
- chmod +x ~/.claude/statusline.sh 실행 권한 확인
- 스크립트를 직접 실행해보고 출력이 나오는지 확인
- settings.json의 disableAllHooks가 true이면 상태바도 꺼짐
- claude --debug 모드로 실행하면 오류 로그 확인 가능

값이 --나 빈 칸으로 표시될 때:
- 첫 번째 API 응답 전까지는 일부 필드가 null일 수 있음
- jq에서 // 0 폴백 처리 확인 (예: .context_window.used_percentage // 0)

색상 코드가 그대로 보일 때:
- echo -e 대신 printf '%b' 사용
- 터미널이 ANSI 색상을 지원하는지 확인

 

□ 마무리

- /statusline 명령으로 자동 생성하거나, 직접 ~/.claude/statusline.sh + settings.json 조합으로 수동 설정
- jq 설치 후 JSON 파싱하여 모델명·컨텍스트·비용·git 브랜치 등 원하는 항목 자유 조합 가능
- 2줄 다중 라인 스크립트로 풍부한 정보를 한눈에 확인
- 대형 저장소에서는 session_id 기반 캐싱으로 성능 최적화 권장
- 상태바는 로컬 실행이므로 API 비용 추가 없음

한 번 설정해두면 매 응답마다 컨텍스트 상태를 직접 확인할 필요가 없어져서 Claude Code 사용이 훨씬 편해집니다. 특히 긴 세션에서 컨텍스트 한계에 가까워질 때 미리 파악할 수 있어 도움이 됩니다. 꼭 한 번 직접 설정해 보시는 것을 추천드립니다.

감사합니다.