상태 표시줄 (Status Line)

읽는 시간: 5분 | 난이도: 초급자

상태 표시줄(Status Line)은 Claude Code 화면 하단에 표시되는 커스터마이징 가능한 바입니다. 설정한 쉘 스크립트를 실행하여 컨텍스트 창 사용량, 세션 비용, git 상태 등 원하는 정보를 항상 한눈에 볼 수 있게 해줍니다.

상태 표시줄이 유용한 경우:

작업 중 컨텍스트 창 사용량을 모니터링할 때
세션 비용을 추적할 때
여러 세션을 구분해야 할 때
git 브랜치와 상태를 항상 표시하고 싶을 때

상태 표시줄 설정하기

/statusline 명령 사용

/statusline 명령에 원하는 내용을 자연어로 설명하면 Claude Code가 스크립트를 자동으로 생성하고 설정을 업데이트합니다:

/statusline 모델 이름과 컨텍스트 비율을 프로그레스 바로 표시

수동 설정

사용자 설정 파일(~/.claude/settings.json) 또는 프로젝트 설정에 statusLine 필드를 추가합니다:

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

command 필드는 쉘에서 실행되므로 인라인 명령도 사용할 수 있습니다:

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

padding 필드는 상태 표시줄 내용에 추가 수평 간격(문자 단위)을 설정합니다. 기본값은 0입니다.

상태 표시줄 비활성화

/statusline delete, /statusline clear, /statusline remove it 등으로 제거하거나, settings.json에서 statusLine 필드를 직접 삭제합니다.

단계별 스크립트 만들기

현재 모델, 작업 디렉토리, 컨텍스트 창 사용 비율을 표시하는 상태 표시줄을 만들어 보겠습니다.

1단계: JSON을 읽어 출력하는 스크립트 작성

Claude Code는 JSON 데이터를 스크립트의 stdin으로 전송합니다. 아래 스크립트를 ~/.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')
# "// 0"은 null일 경우 대체값 제공
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단계: 설정에 추가

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

동작 방식

Claude Code는 스크립트를 실행하고 JSON 세션 데이터를 stdin으로 파이프합니다. 스크립트는 JSON을 읽어 필요한 값을 추출하고, 텍스트를 stdout으로 출력합니다.

업데이트 시점: 새 어시스턴트 메시지 후, 권한 모드 변경 시, vim 모드 토글 시에 실행됩니다. 업데이트는 300ms로 디바운스됩니다.

출력 가능한 내용:

여러 줄: 각 echo 또는 print가 별도 행으로 표시됩니다
색상: ANSI 이스케이프 코드 사용 가능 (예: \033[32m = 초록색)
링크: OSC 8 이스케이프 시퀀스로 클릭 가능한 링크 생성 가능

참고: 상태 표시줄은 로컬에서 실행되며 API 토큰을 소비하지 않습니다.

사용 가능한 데이터

Claude Code는 다음 JSON 필드를 스크립트에 전송합니다:

필드	설명
`model.id`, `model.display_name`	현재 모델 ID 및 표시 이름
`workspace.current_dir`	현재 작업 디렉토리
`workspace.project_dir`	Claude Code가 실행된 디렉토리
`cost.total_cost_usd`	세션 총 비용 (USD)
`cost.total_duration_ms`	세션 시작 이후 경과 시간 (ms)
`cost.total_api_duration_ms`	API 응답 대기 시간 합계 (ms)
`cost.total_lines_added`, `cost.total_lines_removed`	변경된 코드 줄 수
`context_window.context_window_size`	최대 컨텍스트 창 크기 (토큰)
`context_window.used_percentage`	사용된 컨텍스트 창 비율
`context_window.remaining_percentage`	남은 컨텍스트 창 비율
`session_id`	고유 세션 식별자
`version`	Claude Code 버전
`vim.mode`	vim 모드 상태 (`NORMAL` 또는 `INSERT`)
`agent.name`	`--agent` 플래그로 실행 시 에이전트 이름

예시 스크립트

컨텍스트 창 사용량 프로그레스 바

#!/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 ] && BAR=$(printf "%${FILLED}s" | tr ' ' '▓')
[ "$EMPTY" -gt 0 ] && BAR="${BAR}$(printf "%${EMPTY}s" | tr ' ' '░')"

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

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

비용 및 시간 추적

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

팁

모의 입력으로 테스트하기: echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":25}}' | ./statusline.sh
출력을 짧게 유지하기: 상태 바의 너비는 제한되어 있으므로 긴 출력은 잘릴 수 있습니다
느린 작업 캐싱: 스크립트는 빈번하게 실행되므로 git status 같은 명령은 지연을 유발할 수 있습니다. 임시 파일에 결과를 캐싱하고 5초마다 갱신하는 방식을 사용하세요.

문제 해결

상태 표시줄이 나타나지 않을 때

스크립트에 실행 권한이 있는지 확인: chmod +x ~/.claude/statusline.sh
스크립트가 stderr가 아닌 stdout으로 출력하는지 확인
설정에서 disableAllHooks가 true로 설정되어 있으면 상태 표시줄도 비활성화됩니다

-- 또는 빈 값이 표시될 때

필드가 첫 번째 API 응답 이전에는 null일 수 있습니다
스크립트에서 // 0 등의 대체값을 사용하세요

다음 단계

키보드 단축키 — 단축키 커스터마이징
모델 설정 — 모델 변경 및 설정
설정 파일 가이드 — 전체 설정 옵션 참조