Claude Code 상태줄(Status Line) 완벽 사용 가이드

Claude Code를 사용하다 보면 컨텍스트 윈도우가 얼마나 찼는지, 현재 비용이 얼마인지, 어떤 git 브랜치에서 작업 중인지 궁금해지는 순간이 있습니다. 이런 정보를 매번 명령어로 확인하는 대신, 터미널 하단에 항상 표시되도록 설정할 수 있는 기능이 바로 상태줄(Status Line)입니다.

상태줄은 사용자가 직접 작성한 셸 스크립트를 실행하여, Claude Code 세션의 JSON 데이터를 파싱한 뒤 원하는 형식으로 출력하는 구조입니다. 이 가이드에서는 기본 설정부터 고급 활용법, 커뮤니티 도구까지 체계적으로 안내합니다.

상태줄이란?

상태줄은 Claude Code 인터페이스 하단에 표시되는 커스터마이징 가능한 상태 표시줄입니다. 사용자가 설정한 셸 스크립트를 실행하고, 그 스크립트가 출력하는 텍스트를 화면에 표시합니다.

동작 원리는 간단합니다:

1. Claude Code가 세션 데이터를 JSON 형태로 스크립트의 stdin에 전달
2. 스크립트가 JSON을 파싱하여 필요한 정보를 추출
3. 스크립트가 stdout으로 출력한 텍스트가 화면에 표시

상태줄은 로컬에서 실행되며 API 토큰을 소비하지 않습니다. 어시스턴트 메시지가 새로 도착하거나, 권한 모드가 변경되거나, vim 모드가 토글될 때 업데이트됩니다(300ms 디바운싱 적용).

빠른 설정: /statusline 명령어

가장 간편한 방법은 /statusline 명령어를 사용하는 것입니다. 자연어로 원하는 내용을 설명하면 Claude Code가 자동으로 스크립트를 생성하고 설정까지 완료합니다.

이 명령어를 실행하면 ~/.claude/ 디렉터리에 스크립트 파일이 생성되고, ~/.claude/settings.json에 자동으로 설정이 추가됩니다. 삭제하려면 /statusline delete를 입력하면 됩니다.

수동 설정 방법

직접 스크립트를 작성하여 더 세밀하게 제어할 수도 있습니다. 단계별로 살펴보겠습니다.

Step 1: 스크립트 작성

~/.claude/statusline.sh 파일을 생성합니다. JSON 파싱에는 jq 도구가 필요합니다.

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

# 상태줄 출력
echo "[$MODEL] ${DIR##*/} | ${PCT}% context"

Step 2: 실행 권한 부여

chmod +x ~/.claude/statusline.sh

Step 3: settings.json에 등록

~/.claude/settings.json 파일에 다음 설정을 추가합니다:

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

padding은 상태줄 좌우에 추가되는 여백(문자 수)이며, 기본값은 0입니다. 스크립트 파일 대신 인라인 명령어를 사용할 수도 있습니다:

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

설정 파일 범위(Scope) 이해하기

상태줄 설정은 Claude Code의 설정 계층 구조를 따릅니다:

개인 상태줄은 User 범위(~/.claude/settings.json)에 설정하는 것이 일반적이며, 팀 전체가 동일한 상태줄을 사용하려면 Project 범위(.claude/settings.json)에 설정합니다.

사용 가능한 데이터 필드

Claude Code는 다양한 세션 정보를 JSON으로 제공합니다. 주요 필드를 카테고리별로 정리했습니다.

모델 및 세션 정보

컨텍스트 윈도우

비용 및 시간

요금 한도(Pro/Max 구독자)

실전 예제 모음

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%"

2. 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

3. 비용 및 소요 시간 추적

#!/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")
MINS=$((DURATION_MS / 60000))
SECS=$(((DURATION_MS % 60000) / 1000))

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

4. 멀티라인 종합 상태줄

여러 줄을 출력하면 각 echo 문이 별도의 행으로 표시됩니다. 컨텍스트 사용률에 따라 색상이 변합니다(70% 미만 초록, 70~89% 노랑, 90% 이상 빨강):

#!/bin/bash
input=$(cat)
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)
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 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// /░}"

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

echo -e "${CYAN}[$MODEL]${RESET} ${DIR##*/}$BRANCH"
echo -e "${BAR_COLOR}${BAR}${RESET} ${PCT}% | ${YELLOW}$(printf '$%.2f' "$COST")${RESET}"

5. 클릭 가능한 GitHub 링크

OSC 8 이스케이프 시퀀스를 사용하면 터미널에서 Cmd+클릭(macOS) 또는 Ctrl+클릭으로 링크를 열 수 있습니다. iTerm2, Kitty, WezTerm 등 지원 터미널에서 동작합니다:

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
REMOTE=$(git remote get-url origin 2>/dev/null \
  | sed 's/git@github.com:/https:\/\/github.com\//' \
  | sed 's/\.git$//')

if [ -n "$REMOTE" ]; then
    REPO=$(basename "$REMOTE")
    printf '%b' "[$MODEL] \e]8;;${REMOTE}\a${REPO}\e]8;;\a\n"
else
    echo "[$MODEL]"
fi

성능 최적화: 캐싱 기법

상태줄 스크립트는 세션 중 빈번하게 실행됩니다. git status나 git diff 같은 무거운 명령은 큰 저장소에서 지연을 유발할 수 있으므로, 캐시 파일을 활용하는 것이 좋습니다:

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

CACHE_FILE="/tmp/statusline-git-cache"
CACHE_MAX_AGE=5  # 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 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 ' ')
        echo "$BRANCH|$STAGED|$MODIFIED" > "$CACHE_FILE"
    else
        echo "||" > "$CACHE_FILE"
    fi
fi

IFS='|' read -r BRANCH STAGED MODIFIED < "$CACHE_FILE"
[ -n "$BRANCH" ] && echo "[$MODEL] $BRANCH +$STAGED ~$MODIFIED" || echo "[$MODEL]"

Python 및 Node.js로 작성하기

Bash 외에도 Python이나 Node.js로 상태줄 스크립트를 작성할 수 있습니다. JSON 파싱이 내장되어 있어 jq 설치가 필요 없습니다.

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

Node.js 예시

#!/usr/bin/env node
let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
    const data = JSON.parse(input);
    const model = data.model.display_name;
    const pct = Math.floor(data.context_window?.used_percentage || 0);
    const filled = Math.floor(pct * 10 / 100);
    const bar = '▓'.repeat(filled) + '░'.repeat(10 - filled);
    console.log(`[${model}] ${bar} ${pct}%`);
});

Windows 환경 설정

Windows에서 Claude Code는 Git Bash를 통해 상태줄 명령을 실행합니다. PowerShell 스크립트를 호출하려면 다음과 같이 설정합니다:

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

또는 Git Bash 스크립트를 직접 실행할 수도 있습니다. jq 없이 grep과 cut만으로 간단하게 파싱하는 경량 방식도 가능합니다.

커뮤니티 도구 활용

직접 스크립트를 작성하지 않고 커뮤니티에서 만든 도구를 활용할 수도 있습니다.

ccstatusline

ccstatusline은 20개 이상의 위젯(git 정보, 토큰 속도, 세션 비용 등)을 제공하는 고도로 커스터마이징 가능한 상태줄 포맷터입니다. React/Ink 기반의 인터랙티브 TUI로 설정할 수 있으며, Powerline 스타일 구분선과 멀티라인을 지원합니다.

# 설치 및 실행
npx -y ccstatusline@latest

# 또는 Bun 사용 (더 빠름)
bunx -y ccstatusline@latest

설정이 완료되면 settings.json에 자동으로 등록됩니다:

{
  "statusLine": {
    "type": "command",
    "command": "npx -y ccstatusline@latest",
    "padding": 0
  }
}

starship-claude

starship-claude는 터미널 프롬프트 프레임워크인 Starship과 Claude Code를 통합합니다. 컨텍스트 윈도우 사용률에 따라 색상이 변하는 프로그레스 바를 제공하며, TOML 파일로 세밀하게 커스터마이징할 수 있습니다.

# 설치 (Starship 필요)
curl -sS https://starship.rs/install.sh | sh

# settings.json에 등록
{
  "statusLine": {
    "type": "command",
    "command": "~/.local/bin/starship-claude"
  }
}

Vim 모드와의 연동

Claude Code에서 /vim 명령으로 vim 모드를 활성화하면, 상태줄 JSON에 vim.mode 필드가 추가됩니다(NORMAL 또는 INSERT). 이를 활용하면 현재 vim 모드를 상태줄에 표시할 수 있습니다:

VIM_MODE=$(echo "$input" | jq -r '.vim.mode // empty')
[ -n "$VIM_MODE" ] && echo "-- $VIM_MODE --"

트러블슈팅 가이드

테스트 방법

스크립트를 설정하기 전에 먼저 독립적으로 테스트할 수 있습니다:

echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":25}}' | ./statusline.sh

핵심 정리

• /statusline 명령으로 자연어 기반 자동 설정 가능
• Bash, Python, Node.js 등 원하는 언어로 스크립트 작성
• 모델명, 컨텍스트 사용률, 비용, git 상태, 요금 한도 등 다양한 데이터 표시 가능
• ANSI 색상 코드와 OSC 8 링크로 시각적 풍부함 추가
• 멀티라인 출력으로 여러 줄의 정보 동시 표시
• 무거운 명령은 캐싱으로 성능 최적화
• ccstatusline, starship-claude 같은 커뮤니티 도구 활용 가능