Claude Code Statusline 커스터마이징: 터미널 하단을 나만의 대시보드로

Claude Code 터미널 하단에 모델명, 컨텍스트 사용률, git 브랜치, 세션 비용을 실시간으로 표시할 수 있다. /statusline show model name and context percentage with a progress bar — 이 한 줄이면 Claude가 알아서 스크립트를 만들고 settings.json까지 잡아준다.

나는 처음에 기본 상태로 쓰다가, 컨텍스트가 얼마나 찼는지 몰라서 갑자기 자동 컴팩트가 걸리는 경험을 몇 번 하고 나서 statusline을 세팅했다. 한번 걸어두면 다시는 안 빼게 된다.

 

Claude Code statusline 기본 설정 — 모델명과 디렉토리, 컨텍스트 사용률이 표시된 화면

 

목차

• statusline이 뭔가
• 기본 설정법
  • 가장 빠른 방법: /statusline 명령어
  • 수동 설정
• 실용적인 statusline 레시피들
  • 1. 미니멀: 모델명 + 컨텍스트 프로그레스바
  • 2. 개발자용: git 브랜치 + 변경 파일 수 + 모델명
  • 3. 비용 추적: 세션 비용 + 시간
  • 4. 풀 대시보드: 전부 다
• 사용 가능한 데이터 필드
• 커뮤니티 도구들
• 실전 팁
• 핵심 요약

statusline이 뭔가

Claude Code 하단에 표시되는 정보 바다. 쉘 스크립트를 하나 돌려서, 그 출력을 터미널 아래쪽에 고정 표시하는 구조.

• 기본값: 거의 아무것도 안 보임
• 커스텀하면: 컨텍스트 %, git 브랜치, 세션 비용, 작업 시간, 레이트 리밋까지 표시 가능
• API 토큰을 소모하지 않음 — 로컬에서만 돌아감
• 어시스턴트 메시지가 올 때마다 갱신 (300ms 디바운스)

동작 원리는 단순하다. Claude Code가 JSON 세션 데이터를 stdin으로 넘기고, 내 스크립트가 그걸 파싱해서 stdout으로 출력하면 끝. 여러 줄 출력하면 멀티라인 statusline도 된다.

기본 설정법

가장 빠른 방법: /statusline 명령어

Claude Code 안에서 그냥 자연어로 말하면 된다.

/statusline show model name, context percentage, git branch, and session cost

이러면 Claude가 ~/.claude/statusline.sh 같은 스크립트를 자동 생성하고, settings.json까지 알아서 업데이트한다. 끝.

수동 설정

직접 컨트롤하고 싶으면 ~/.claude/settings.json에 이렇게 추가한다.

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

command에 스크립트 경로를 넣어도 되고, 인라인 커맨드를 넣어도 된다. jq 원라이너로 끝낼 수도 있다.

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

Windows에서는 Git Bash를 통해 실행되니까, bash 스크립트 그대로 써도 되고, PowerShell을 호출해도 된다.

{
  "statusLine": {
    "type": "command",
    "command": "powershell -NoProfile -File C:/Users/username/.claude/statusline.ps1"
  }
}

실용적인 statusline 레시피들

JSON으로 넘어오는 데이터가 꽤 풍부하다. 모델명, 컨텍스트, 비용, git 정보, 레이트 리밋, worktree까지. 이걸 조합해서 레시피별로 정리했다.

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)

# 프로그레스바 생성
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%"

출력 예: [Opus] ▓▓░░░░░░░░ 18%

Claude Code statusline git 브랜치와 변경 파일 표시 예시

2. 개발자용: git 브랜치 + 변경 파일 수 + 모델명

git 정보가 색상으로 들어오니까 한눈에 staged/modified 파일이 몇 개인지 보인다.

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

출력 예: [Opus] blog-poster | master +3 ~2 (숫자에 초록/노란 색상)

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

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

출력 예: [Opus] $0.47 | 12m 34s

4. 풀 대시보드: 전부 다

위 전부를 합치면 멀티라인 대시보드가 된다. echo를 두 번 하면 2줄이 표시된다.

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

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"
echo -e "${BAR_COLOR}${BAR}${RESET} ${PCT}% | ${YELLOW}${COST_FMT}${RESET} | ${MINS}m ${SECS}s"

 

claude-powerline 커뮤니티 테마 모음 — dark, nord, tokyo-night 등 6가지 스타일

 

90% 넘으면 빨간색, 70% 넘으면 노란색으로 바뀐다. 컨텍스트 위험 신호를 시각적으로 바로 알 수 있다.

사용 가능한 데이터 필드

스크립트로 넘어오는 JSON에 뭐가 있는지 알아야 커스텀할 수 있다. 주요 필드를 정리하면:

필드	설명
model.display_name	현재 모델 이름 (Opus, Sonnet 등)
context_window.used_percentage	컨텍스트 사용률 (%)
cost.total_cost_usd	세션 누적 비용 (USD)
cost.total_duration_ms	세션 경과 시간
cost.total_lines_added / removed	코드 변경 줄 수
workspace.current_dir	현재 작업 디렉토리
rate_limits.five_hour.used_percentage	5시간 레이트 리밋 사용률
rate_limits.seven_day.used_percentage	7일 레이트 리밋 사용률
worktree.name	워크트리 이름
vim.mode	vim 모드 (NORMAL/INSERT)

rate_limits는 Claude.ai Pro/Max 구독자에게만 표시된다. worktree는 --worktree 세션에서만 존재한다. 없는 필드는 jq에서 // empty나 // 0으로 처리하면 된다.

커뮤니티 도구들

직접 bash를 짜기 귀찮다면, 이미 잘 만들어진 도구들이 있다.

ccstatusline — 가장 인기 있는 옵션. Powerline 스타일, 테마 지원, 터미널 폭에 맞게 자동 트렁케이션까지 해준다.

npx -y ccstatusline@latest

인터랙티브 TUI로 설정할 수 있고, 실행하면 알아서 settings.json까지 세팅된다.

claude-powerline — vim-style powerline statusline. Owloops가 만든 프로젝트로, powerline 폰트 있으면 아주 예쁘게 나온다.

starship-claude — Starship prompt와 연동하는 방식. 기존에 Starship 쓰고 있다면 통합이 자연스럽다.

이런 커뮤니티 도구들의 장점은 ANSI 색상 처리, OSC 8 하이퍼링크, 터미널 폭 대응 같은 귀찮은 부분을 이미 해결해놨다는 것이다.

실전 팁

테스트는 이렇게 한다. 스크립트를 만들고 나서 Claude Code를 재시작할 필요 없이, mock 데이터로 바로 확인할 수 있다.

echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":72},"cost":{"total_cost_usd":0.35,"total_duration_ms":300000}}' | ~/.claude/statusline.sh

대형 레포에서는 캐싱하라. git diff나 git status는 레포가 크면 느리다. 스크립트가 매 업데이트마다 실행되니까, 5초 간격으로 캐싱하는 게 좋다.

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

if [ ! -f "$CACHE_FILE" ] || [ $(($(date +%s) - $(stat -c %Y "$CACHE_FILE" 2>/dev/null || echo 0))) -gt $CACHE_MAX_AGE ]; then
    BRANCH=$(git branch --show-current 2>/dev/null)
    echo "$BRANCH" > "$CACHE_FILE"
fi
BRANCH=$(cat "$CACHE_FILE")

삭제는 /statusline clear로. settings.json에서 statusLine 필드를 직접 지워도 된다.

안 보이면 체크할 것:

• chmod +x를 했는지
• stdout으로 출력하는지 (stderr 아님)
• disableAllHooks가 true로 되어 있진 않은지
• workspace trust를 수락했는지

---

핵심 요약

• /statusline + 자연어 설명 한 줄이면 Claude가 스크립트 자동 생성
• ~/.claude/settings.json의 statusLine.command에 스크립트 경로 지정
• stdin으로 JSON 받고, stdout으로 텍스트 출력하는 구조
• 모델명, 컨텍스트 %, 비용, git 브랜치, 레이트 리밋 등 표시 가능
• ANSI 색상 코드로 시각적 구분, 멀티라인도 지원
• ccstatusline, claude-powerline 같은 커뮤니티 도구로 빠르게 시작 가능
• 대형 레포에서는 git 명령어 캐싱 필수

---

관련글:

• Claude Code Buddy 리롤하는 법
• Claude Code vs Cursor vs Codex CLI 비교