Claude Code 공식문서 리뷰-Configuration[5] : 상태 줄 구성(Status line configuration)

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> [설정] 섹션의 내용 중 [상태 줄 구성(Status line configuration)]를 살펴 보려고 합니다.

이번 섹션 부터는 영문, 한글번역본이 모두 공식문서로 존재하는 섹션이니 한글 문서를 편하게 참고 하셔도 될 것 같습니다.

https://code.claude.com/docs/en/statusline

Status line configuration - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.

 

 

Claude Code 상태 줄 설정

원문 기준: 2025-12-23 | 공식 문서

이 문서에서 다루는 내용

• 상태 줄 개념: 인터페이스 하단의 커스텀 정보 표시
• 설정 방법: 대화형 및 수동 설정
• JSON 입력 구조: 상태 줄에서 사용할 수 있는 데이터
• 예제 스크립트: Bash, Python, Node.js 구현 예시

Claude Code에서 터미널 프롬프트(PS1)처럼 인터페이스 하단에 표시되는 커스텀 상태 줄을 구성할 수 있습니다.

상태 줄(Status Line)이란?

Oh-my-zsh의 터미널 프롬프트와 유사하게, Claude Code 인터페이스 하단에 현재 모델, 작업 디렉토리, Git 브랜치 등의 컨텍스트 정보를 표시하는 줄입니다.

왜 상태 줄이 필요한가?

Claude Code로 작업하다 보면 이런 궁금증이 생긴다:

• "지금 어떤 모델을 쓰고 있지?" (Sonnet? Opus? Haiku?)
• "이번 세션에서 비용이 얼마나 들었지?"
• "컨텍스트 윈도우를 얼마나 사용했지?"
• "지금 어느 브랜치에서 작업 중이지?"

상태 줄을 설정하면 이런 정보를 항상 화면 하단에서 확인할 수 있다.

이런 분들에게 유용하다

비용 관리가 중요한 경우	API 비용을 실시간으로 모니터링하고 싶을 때. 특히 팀에서 사용량 한도를 관리할 때 유용하다.
여러 프로젝트를 오가는 경우	Git 브랜치나 프로젝트 디렉토리를 표시하면 혼란 없이 작업 컨텍스트를 파악할 수 있다.
모델을 자주 전환하는 경우	현재 사용 중인 모델(Sonnet, Opus 등)을 바로 확인할 수 있다.
긴 대화를 하는 경우	컨텍스트 윈도우 사용량을 표시하면 대화가 언제쯤 초기화될지 예측할 수 있다.

 

시작하기 전에 준비할 것들

상태 줄 스크립트를 작성하려면 몇 가지 도구가 필요하다. 대부분 이미 설치되어 있을 것이다.

필수 항목

• jq - JSON 파싱 도구 (Bash 스크립트 사용 시)
  → 확인: jq --version
• 스크립트 실행 권한 - 스크립트 파일에 실행 권한 부여 필요
  → 설정: chmod +x ~/.claude/statusline.sh

언어별 요구사항

Bash	jq 필요 (JSON 파싱용)
Python	Python 3.x (추가 패키지 불필요)
Node.js	Node.js 18+ (추가 패키지 불필요)

jq 설치 방법

jq가 없다면 아래 명령어로 설치할 수 있다:

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Windows (Chocolatey)
choco install jq

 

설정

상태 줄을 설정하는 두 가지 방법:

방법	설명
대화형 설정	Claude Code에서 /statusline 실행하여 AI 지원 받기
수동 설정	.claude/settings.json에 직접 추가

수동 설정 예시

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

처음이라면 /statusline 명령어로 시작하자

/statusline 명령어를 사용하면 Claude가 대화형으로 상태 줄 설정을 도와준다. 어떤 정보를 표시하고 싶은지 물어보고, 스크립트 생성부터 설정 파일 수정까지 자동으로 처리해준다.

수동 설정 - 단계별 가이드

직접 설정하고 싶다면?

스크립트를 직접 작성하거나 커스터마이징하고 싶다면 아래 단계를 따르자.

1단계: 스크립트 파일 생성

먼저 상태 줄 스크립트를 저장할 위치를 정하고 파일을 생성한다.

# .claude 디렉토리가 없으면 생성
mkdir -p ~/.claude

# 스크립트 파일 생성 (아래 예제 스크립트 중 하나를 복사)
touch ~/.claude/statusline.sh

# 실행 권한 부여 (중요!)
chmod +x ~/.claude/statusline.sh

2단계: 스크립트 작성

아래 "예제 스크립트" 섹션에서 원하는 스크립트를 복사하여 파일에 저장한다.

3단계: settings.json에 등록

~/.claude/settings.json 파일을 열어 다음 내용을 추가한다:

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

💡 파일이 없으면 새로 생성하면 된다. 다른 설정이 있다면 해당 내용을 추가한다.

4단계: 테스트

Claude Code를 다시 시작하면 상태 줄이 표시된다. 작동하지 않으면 아래 명령어로 스크립트를 직접 테스트해보자:

echo '{"model":{"display_name":"Test"},"workspace":{"current_dir":"/test"}}' | ~/.claude/statusline.sh

 

작동 방식

항목	설명
업데이트 시점	대화 메시지가 변경될 때
업데이트 빈도	최대 300ms마다
출력 형식	명령어 stdout의 첫 줄이 상태 줄 텍스트로 사용
스타일링	ANSI 컬러 코드 지원
입력 데이터	Claude Code가 stdin으로 컨텍스트 JSON 전달

 

JSON 입력 구조

상태 줄 명령어가 받는 JSON 데이터:

{
  "hook_event_name": "Status",
  "session_id": "abc123...",
  "cwd": "/current/working/directory",
  "model": {
    "id": "claude-opus-4-1",
    "display_name": "Opus"
  },
  "workspace": {
    "current_dir": "/current/working/directory",
    "project_dir": "/original/project/directory"
  },
  "version": "1.0.80",
  "cost": {
    "total_cost_usd": 0.01234,
    "total_duration_ms": 45000,
    "total_lines_added": 156,
    "total_lines_removed": 23
  },
  "context_window": {
    "total_input_tokens": 15234,
    "total_output_tokens": 4521,
    "context_window_size": 200000,
    "current_usage": {
      "input_tokens": 8500,
      "output_tokens": 1200,
      "cache_creation_input_tokens": 5000,
      "cache_read_input_tokens": 2000
    }
  }
}

주요 필드 설명

필드	설명
model.display_name	현재 사용 중인 모델 이름
workspace.current_dir	현재 작업 디렉토리
workspace.project_dir	원본 프로젝트 디렉토리
cost.total_cost_usd	총 비용 (USD)
context_window	컨텍스트 윈도우 사용량

 

예제 스크립트

간단한 Bash 상태 줄

#!/bin/bash
input=$(cat)
MODEL_DISPLAY=$(echo "$input" | jq -r '.model.display_name')
CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir')
echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}"

Git 브랜치 표시 상태 줄

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

GIT_BRANCH=""
if git rev-parse --git-dir > /dev/null 2>&1; then
    BRANCH=$(git branch --show-current 2>/dev/null)
    if [ -n "$BRANCH" ]; then
        GIT_BRANCH=" | 🌿 $BRANCH"
    fi
fi

echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}$GIT_BRANCH"

Python 예제

#!/usr/bin/env python3
import json
import sys
import os

data = json.load(sys.stdin)
model = data['model']['display_name']
current_dir = os.path.basename(data['workspace']['current_dir'])

git_branch = ""
if os.path.exists('.git'):
    try:
        with open('.git/HEAD', 'r') as f:
            ref = f.read().strip()
            if ref.startswith('ref: refs/heads/'):
                git_branch = f" | 🌿 {ref.replace('ref: refs/heads/', '')}"
    except:
        pass

print(f"[{model}] 📁 {current_dir}{git_branch}")

Node.js 예제

#!/usr/bin/env node

const fs = require('fs');
const path = require('path');

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 currentDir = path.basename(data.workspace.current_dir);

    let gitBranch = '';
    try {
        const headContent = fs.readFileSync('.git/HEAD', 'utf8').trim();
        if (headContent.startsWith('ref: refs/heads/')) {
            gitBranch = ` | 🌿 ${headContent.replace('ref: refs/heads/', '')}`;
        }
    } catch (e) {
        // Git 레포가 아님
    }

    console.log(`[${model}] 📁 ${currentDir}${gitBranch}`);
});

컨텍스트 윈도우 사용량 표시

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size')
USAGE=$(echo "$input" | jq '.context_window.current_usage')

if [ "$USAGE" != "null" ]; then
    CURRENT_TOKENS=$(echo "$USAGE" | jq '.input_tokens + .cache_creation_input_tokens + .cache_read_input_tokens')
    PERCENT_USED=$((CURRENT_TOKENS * 100 / CONTEXT_SIZE))
    echo "[$MODEL] Context: ${PERCENT_USED}%"
else
    echo "[$MODEL] Context: 0%"
fi

 

팁

팁	설명
간결하게	상태 줄은 한 줄에 맞아야 함
이모지/컬러 사용	스캔하기 쉽게
jq 사용	Bash에서 JSON 파싱 시 권장
수동 테스트	아래 명령어로 스크립트 테스트

테스트 명령어

echo '{"model":{"display_name":"Test"},"workspace":{"current_dir":"/test"}}' | ./statusline.sh

실전 팁

비용이 많이 드는 연산(예: git 명령어)은 필요시 캐싱하세요. 상태 줄은 자주 업데이트되므로 성능이 중요합니다.

 

트러블슈팅

상태 줄 문제 해결 팁

상태 줄이 작동하지 않는 대부분의 경우는 스크립트 실행 권한, 경로, 또는 JSON 파싱 문제다. 아래 순서대로 확인해보자.

문제 1: 상태 줄이 나타나지 않음

증상

- Claude Code 화면 하단에 아무것도 표시되지 않음
- 설정했는데 상태 줄 영역 자체가 없음

가능한 원인

1. 스크립트 파일에 실행 권한이 없음
2. settings.json의 경로가 잘못됨
3. settings.json 문법 오류

해결 방법

# 1. 실행 권한 확인 및 부여
ls -la ~/.claude/statusline.sh
chmod +x ~/.claude/statusline.sh

# 2. 스크립트 직접 실행 테스트
echo '{"model":{"display_name":"Test"}}' | ~/.claude/statusline.sh

# 3. settings.json 문법 확인 (jq가 있다면)
cat ~/.claude/settings.json | jq .

문제 2: 출력이 없거나 빈 상태 줄

증상

- 상태 줄 영역은 있는데 내용이 비어있음
- 가끔 내용이 나타났다 사라짐

가능한 원인

1. 스크립트가 stderr로 출력 중 (stdout이 아님)
2. JSON 파싱 실패 (jq 미설치 또는 문법 오류)
3. 스크립트 내부 에러

해결 방법

# 1. stdout과 stderr 분리 테스트
echo '{"model":{"display_name":"Test"}}' | ~/.claude/statusline.sh 2>&1

# 2. jq 설치 확인
jq --version

# 3. 스크립트 디버깅 (임시로 간단한 출력 테스트)
#!/bin/bash
echo "테스트 상태줄"

💡 디버깅할 때는 간단한 echo만 출력하는 스크립트로 먼저 테스트해보자.

문제 3: jq 관련 에러

증상

- "jq: command not found" 에러
- "parse error" 메시지

해결 방법

# jq 설치
# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# 또는 Python 스크립트로 전환 (jq 필요 없음)

💡 jq 설치가 어렵다면 Python이나 Node.js 예제를 사용하자. 추가 패키지 없이 JSON 파싱이 가능하다.

문제 4: Git 브랜치가 표시되지 않음

증상

- Git 저장소에서 작업 중인데 브랜치 이름이 안 나옴
- 다른 정보는 나오는데 Git 정보만 비어있음

가능한 원인

스크립트가 실행되는 위치와 현재 작업 디렉토리가 다를 수 있다.

해결 방법

#!/bin/bash
input=$(cat)
CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir')

# 해당 디렉토리로 이동해서 Git 정보 가져오기
GIT_BRANCH=""
if [ -d "$CURRENT_DIR/.git" ]; then
    GIT_BRANCH=$(git -C "$CURRENT_DIR" branch --show-current 2>/dev/null)
fi

 

고급: ANSI 컬러 코드로 상태 줄 꾸미기

컬러풀한 상태 줄을 원한다면?

상태 줄은 ANSI 이스케이프 코드를 지원한다. 모델명은 초록색, 비용은 노란색으로 표시하는 등 시각적으로 구분하기 쉽게 만들 수 있다.

컬러 상태 줄 예제 (Bash)

#!/bin/bash
input=$(cat)

# ANSI 컬러 코드 정의
GREEN='\033[0;32m'
YELLOW='\033[0;33m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
RESET='\033[0m'  # 컬러 리셋

# JSON에서 값 추출
MODEL=$(echo "$input" | jq -r '.model.display_name')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
DIR_NAME="${DIR##*/}"  # 디렉토리 이름만 추출

# Git 브랜치 (있으면)
GIT_BRANCH=""
if git rev-parse --git-dir > /dev/null 2>&1; then
    BRANCH=$(git branch --show-current 2>/dev/null)
    [ -n "$BRANCH" ] && GIT_BRANCH=" ${CYAN}🌿 $BRANCH${RESET}"
fi

# 비용 포맷팅 (소수점 4자리)
COST_FMT=$(printf "%.4f" "$COST")

# 컬러 출력
echo -e "${GREEN}[$MODEL]${RESET} 📁 ${BLUE}$DIR_NAME${RESET}$GIT_BRANCH ${YELLOW}💰 \$$COST_FMT${RESET}"

실제 출력 예시

위 스크립트를 사용하면 터미널에서 다음과 같이 표시된다:

[Sonnet] 📁 my-project 🌿 feature/login 💰 $0.0234

자주 쓰는 ANSI 컬러 코드

\033[0;31m	빨간색 - 에러, 경고
\033[0;32m	초록색 - 성공, 모델명
\033[0;33m	노란색 - 비용, 주의
\033[0;34m	파란색 - 디렉토리
\033[0;36m	청록색 - Git 브랜치
\033[0m	리셋 (기본 색상으로 되돌림)

💡 컬러 사용 후에는 반드시 \033[0m으로 리셋해야 한다.

 

더 알아보기 - 유용한 자료

각 상황에 맞는 자료를 찾아보자

상태 줄 설정 중 막히거나, 더 커스터마이징하고 싶을 때 참고할 수 있는 문서들이다.

문서	이럴 때 보자
Status line 공식 문서 이 글의 원본	- JSON 입력 구조의 모든 필드를 확인하고 싶을 때 - 최신 업데이트된 내용을 확인하고 싶을 때
Terminal config 터미널 전체 설정	- 터미널 테마, 폰트 등을 함께 설정하고 싶을 때 - Claude Code의 터미널 환경을 전체적으로 커스터마이징하고 싶을 때
Settings 전체 설정 옵션	- settings.json의 다른 옵션들이 궁금할 때 - 프로젝트별/전역 설정 구분을 이해하고 싶을 때
Hooks 자동화 훅	- 상태 줄 외에 다른 자동화 기능을 알고 싶을 때 - 특정 이벤트에 스크립트를 실행하고 싶을 때

 

핵심 요약 - 빠른 설정 체크리스트

빠르게 확인하자

아래 항목들이 제대로 설정되어 있다면 상태 줄이 작동할 준비가 된 것이다.

항목	설정 내용
스크립트 파일	~/.claude/statusline.sh (또는 .py, .js) → 원하는 언어로 작성
실행 권한	chmod +x ~/.claude/statusline.sh → 이걸 빼먹으면 작동 안 함
settings.json	~/.claude/settings.json에 statusLine 설정 → type: "command", command: 스크립트 경로
jq (Bash용)	Bash 스크립트 사용 시 필수 → Python/Node.js는 불필요
출력 형식	stdout으로 한 줄 출력 → ANSI 컬러 코드 사용 가능

설정 후 테스트

설정이 완료되었다면 아래 명령어로 스크립트가 잘 동작하는지 확인하자:

# 테스트 JSON으로 스크립트 실행
echo '{"model":{"display_name":"Sonnet"},"workspace":{"current_dir":"/home/user/project"},"cost":{"total_cost_usd":0.0123}}' | ~/.claude/statusline.sh

# 예상 출력: [Sonnet] 📁 project 💰 $0.0123

→ 출력이 잘 나오면 Claude Code를 재시작하면 상태 줄이 표시된다.