Status Line

claude-code 2026-02-16

Status Line

[!tldr] 한줄 요약 Claude Code 터미널 하단에 셸 스크립트 기반으로 모델 정보, 컨텍스트 사용량, 비용 등을 실시간 표시하는 커스터마이징 가능한 상태 표시줄이다.

핵심 내용

동작 원리

Status Line은 사용자가 작성한 셸 스크립트를 실행하여 세션 정보를 터미널 하단에 표시한다. API 토큰을 소비하지 않고 로컬에서 동작한다.

Claude Code가 세션 데이터를 JSON으로 사용자 스크립트(bash/node/python)의 stdin에 전달하고, 스크립트의 stdout 출력이 터미널 하단에 Status Line으로 표시된다.

업데이트 타이밍:

JSON 스키마

스크립트가 stdin으로 받는 주요 필드:

필드설명
model.id / model.display_name현재 모델 (예: claude-opus-4-6, Opus)
cost.total_cost_usd세션 총 비용 (USD)
cost.total_duration_ms세션 경과 시간 (밀리초)
cost.total_lines_added / removed추가/삭제된 라인 수
context_window.used_percentage컨텍스트 윈도우 사용률 (%)
context_window.context_window_size컨텍스트 윈도우 크기 (200,000)
workspace.current_dir / project_dir현재/프로젝트 디렉토리
vim.modeVim 모드 활성화 시에만 존재
agent.name--agent 플래그 사용 시에만 존재

[!warning] Null 처리 필수 context_window.current_usage는 첫 API 호출 전에 null이다. 모든 필드에 fallback 값을 제공해야 한다 (jq: // 0, JS: ?? 0).

설정 방법

방법 1: /statusline 명령어 (자동 설정)

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

자연어로 설명하면 Claude Code가 스크립트를 자동 생성하고 settings.json까지 등록한다.

방법 2: 수동 설정 (3단계)

1단계 — 스크립트 작성:

#!/bin/bash
# ~/.claude/statusline.sh
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
echo "[$MODEL] $PCT% context"

2단계 — 실행 권한 부여:

chmod +x ~/.claude/statusline.sh

3단계 — settings.json에 등록:

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

padding은 선택사항으로 좌우 여백(문자 단위)을 설정한다. 기본값은 0.

커스터마이징

ANSI 색상 코드: 터미널 색상으로 시각적 구분이 가능하다.

GREEN='\033[32m'
YELLOW='\033[33m'
RED='\033[31m'
RESET='\033[0m'
echo -e "${GREEN}OK${RESET}"

여러 줄 출력: 각 echo가 별도 행으로 표시된다.

클릭 가능한 링크: OSC 8 이스케이프 시퀀스를 지원한다 (iTerm2, Kitty, WezTerm).

printf '%b' "\e]8;;https://github.com/user/repo\aRepo\e]8;;\a\n"

[!tip] 성능 최적화 Git 명령어 같은 무거운 작업은 /tmp/statusline-git-cache에 5초 TTL로 캐싱하면 Status Line이 빠르게 유지된다.

예시

컨텍스트 + 비용 프로그레스 바

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

FILLED=$((PCT * 10 / 100))
EMPTY=$((10 - FILLED))
BAR=$(printf "%${FILLED}s" | tr ' ' '▓')$(printf "%${EMPTY}s" | tr ' ' '░')

echo "[$MODEL] $BAR $PCT% | \$$(printf '%.2f' $COST)"

[!example] 실행 결과 [Opus] ▓▓▓░░░░░░░ 25% | $0.05

Git 상태 + 색상

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
GREEN='\033[32m'; YELLOW='\033[33m'; RESET='\033[0m'

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 -e "[$MODEL] 🌿 $BRANCH ${GREEN}+${STAGED}${RESET} ${YELLOW}~${MODIFIED}${RESET}"

[!example] 실행 결과 [Opus] 🌿 main +2 ~3

테스트 방법

echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":25},"cost":{"total_cost_usd":0.05}}' | ~/.claude/statusline.sh

참고 자료

관련 노트

Other TILs in claude-code