본 기사는 macOS / Linux 환경을 전제로 작성되었습니다.

Windows의 경우에는 Git Bash 등 bash를 이용할 수 있는 환경을 사용하면 동작합니다.

안녕하세요, 트라이벡(Tribec) 주식회사의 스즈키입니다.

Claude Code를 사용하다 보면, 지금 어떤 모델을 사용하고 있는지, 앞으로 토큰을 얼마나 더 사용할 수 있는지 궁금할 때가 자주 있습니다.

그때마다 /model

이나 /status

를 입력하는 것은 번거롭습니다.

그래서 이번에는 Claude Code의 스테이터스 라인(Status Line)을 커스텀하여,

• 현재 이용 중인 모델
• 토큰 소비량
• 컨텍스트(Context) 사용량

등을 상시 표시할 수 있도록 해보았습니다.

특히 컨텍스트 잔량을 상시 확인할 수 있어,

"슬슬 새로운 세션으로 전환하는 것이 좋겠군"

을 판단하기 쉬워졌습니다.

완성된 모습은 다음과 같습니다!

필요한 정보를 항상 확인할 수 있게 되어 상당히 쾌적해졌습니다.

다음과 같은 배치로 표시하고 있습니다.

📁 디렉토리명 | 🌿 브랜치명
🤖 모델명 | 💪 Effort 레벨 | 📚 컨텍스트 점유량 | 🕔 토큰 사용량

※본 기사는 Claude Code v2.1.142에서 동작을 확인했습니다.

Claude Code의 채팅창 하단에는 자유롭게 커스텀할 수 있는 스테이터스 라인(Status Line)이 있습니다.

여기에는 설정한 쉘 스크립트(Shell Script)가 출력한 내용을 그대로 표시할 수 있습니다.

공식 문서

Windows 사용자분들께

스테이터스 라인의 스크립트는 Bash로 실행되기 때문에, PowerShell이나 명령 프롬프트(Command Prompt)에서는 동작하지 않습니다.

Git Bash 등 Bash를 이용할 수 있는 환경을 사전에 설치해 주세요.

이후의 설명은 Bash 환경을 전제로 기재합니다.

~/.claude/ 디렉토리에 쉘 스크립트를 생성합니다.

생성한 스크립트를 Claude Code에서 실행할 수 있도록 권한도 변경해 둡니다.

touch ~/.claude/statusline-command.sh
chmod +x ~/.claude/statusline-command.sh

JSON 처리 도구인 jq를 사용합니다.

설치되어 있지 않다면 아래 명령어로 도입해 주세요.

이번에는 Homebrew를 사용하여 설치합니다.

brew install jq

Windows의 경우 (※필자 미검증)

Windows의 경우, winget 또는 Scoop을 사용하면 간단히 도입할 수 있는 것 같습니다.

winget의 경우

winget install jqlang.jq

Scoop의 경우
※별도로 scoop을 설치해야 합니다.

scoop install jq

생성한 파일에 다음 내용을 작성합니다.

#!/bin/bash
# Claude Code 스테이터스 라인 — stdin에 전달되는 JSON을 표시할 뿐 (공식: https://code.claude.com/docs/ja/statusline )
input=$(cat)
...

포인트는 input=$(cat)으로 stdin으로부터 JSON을 받는 것입니다.

Claude Code는 스테이터스 라인을 업데이트할 때마다 이 스크립트를 호출하여 상태 정보를 JSON으로서 전달합니다.

~/.claude/settings.json을 열고, 다음을 추가합니다.

{
"statusLine": {
"type": "command",
...

<your-username>은 실제 사용자 이름으로 바꿔주세요.

refreshInterval은 스테이터스 라인의 업데이트 간격(초)입니다.

위 설정에서는 60초마다 스크립트가 재실행되어 최신 상태로 자동 업데이트됩니다.

Windows 사용자의 경우, command의 경로 형식이 다릅니다.

"command": "bash C:/Users/<your-username>/.claude/statusline-command.sh"

설정을 반영하기 위해 Claude Code를 한 번 종료한 후 재시작합니다.

채팅창 하단에 스테이터스 라인이 표시되면 설정 완료입니다.

※ 표시되지 않는 경우에는 터미널을 재시작해 보세요.

Claude Code 실행 시에는 컨텍스트 사용량과 5시간 제한 정보가 표시되지 않으므로, 아무 말이나 한마디 던져 봅시다.

모든 정보가 표시되었습니다!

이제부터 설정 내용을 자세히 설명하겠습니다.

스크립트는 크게 다음과 같은 블록으로 나뉩니다.

① JSON 수신
② 각 값 추출
③ 표시 색상 정의
...

순서대로 살펴보겠습니다.

input=$(cat)

Claude Code는 스테이터스 라인(Status Line)을 업데이트할 때마다 이 스크립트를 표준 입력 (stdin)을 통해 JSON을 전달하며 실행합니다.

cat으로 stdin을 그대로 읽어 들여, 변수 input에 저장하고 있습니다.

전달되는 JSON의 구조에 대해서는 공식 문서에 기재되어 있습니다.

MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
EFFORT=$(echo "$input" | jq -r '.effort.level // "—"')
...

jq -r로 JSON에서 값을 추출하고 있습니다. -r은 raw 모드 (따옴표 없이 문자열을 출력)입니다.

// "—"는 jq의 폴백(Fallback) 연산자입니다. 값이 null이거나 존재하지 않을 경우 대신할 값을 반환합니다. EFFORT를 취득할 수 없을 때는 —를 표시하고, PCT를 취득할 수 없을 때는 0을 사용합니다.

cut -d. -f1은 소수점 이하를 버림 하여 정수로 만듭니다.

GREEN='\033[32m'
YELLOW='\033[33m'
RED='\033[31m'
...

ANSI 이스케이프 코드(ANSI Escape Code)로 색상을 정의하고 있습니다. echo -e와 조합함으로써 터미널에 색상이 있는 텍스트를 출력할 수 있습니다.

if [ "$PCT" -ge 70 ]; then BAR_COLOR="$RED"
elif [ "$PCT" -ge 50 ]; 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// /░}"

바(Bar)는 **10칸으로 100%**를 나타냅니다.

• FILLED: 채워진 칸 수 (예: PCT=42 → 4칸)
• EMPTY: 빈 칸 수 (예: 10 - 4 = 6칸)
• printf -v FILL "%${FILLED}s": 공백을 FILLED 개만큼 생성하여 변수에 저장
• ${FILL// /█}: 공백을 모두 █ (전각 블록)로 치환

최종적으로 BAR는 ████░░░░░░ 42%와 같은 모습이 됩니다.

Claude Code의 구독 플랜에는 「5시간마다의 이용 한도」가 있습니다.

이 블록에서는 해당 사용 상황과 제한이 리셋될 때까지 남은 시간을 표시합니다.

FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
FIVEH_RESET=$(echo "$input" | jq -r '.rate_limits.five_hour.resets_at // empty')

// empty는 값이 존재하지 않을 경우 아무것도 출력하지 않음 (빈 문자열)을 의미하는 jq의 작성 방식입니다. // "—"와는 달리, 후속되는 if [ -n "$FIVE_H" ]에서 "값이 있는지 없는지"를 판정하기 위해 빈 문자열을 사용하고 있습니다.

if [ -n "$FIVE_H" ]; then
FIVEH_INT=$(printf '%.0f' "$FIVE_H")
if [ "$FIVEH_INT" -ge 90 ]; then FH_COL="$RED"
...

-n은 "변수가 비어 있지 않음"을 나타내는 조건입니다. 레이트 제한 (Rate Limit) 정보가 JSON에 포함되어 있는 경우에만 처리를 수행합니다.

printf '%.0f'를 사용하여 소수점 이하를 반올림하여 정수화하고 있습니다 (cut -d. -f1을 사용한 버림과는 다릅니다).

if [ -n "$FIVEH_RESET" ] && [ "$FIVEH_RESET" != "null" ]; then
NOW=$(date +%s)
DELTA=$((FIVEH_RESET - NOW))
...

resets_at은 Unix 타임스탬프 (Unix Timestamp, 초 단위)이므로, 현재 시각 date +%s와의 차이를 구함으로써 리셋까지 남은 시간을 계산합니다.

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

git rev-parse --git-dir은 현재 디렉토리가 Git 리포지토리 (Git Repository)인지 확인하는 명령어입니다.

• > /dev/null 2>&1: 표준 출력(Standard Output)과 표준 에러 출력(Standard Error)을 모두 버림 (에러 메시지를 화면에 표시하지 않음)
• &&: 앞의 명령어가 성공했을 경우에만 우변을 실행

Git 리포지토리 외부의 디렉토리에서는 BRANCH가 빈 문자열로 유지되므로, 브랜치 표시가 나타나지 않습니다.

echo -e "📁 ${DIR##*/}$BRANCH"
echo -e "🤖 ${MODEL}${RESET} | 💪 ${EFFORT}${RESET} | 📚 ${BAR_COLOR}${BAR}${RESET} ${PCT}% | 🕔 5h ${FIVEH_SHOW}${FIVEH_UNTIL}"

echo -e는 \033[32m 등과 같은 이스케이프 코드 (Escape Code)를 활성화하는 옵션입니다.

${DIR##*/}는 Bash의 파라미터 확장 (Parameter Expansion)으로, 전체 경로에서 디렉토리 이름만 추출하는 표기법입니다.

DIR="/Users/suzuki/myproject"
echo ${DIR##*/} # → myproject

##*/는 "처음부터 마지막 /까지를 삭제한다"는 의미입니다.

이상이 각 명령어에 대한 설명입니다.

현재의 AI 주도 개발 (AI-Driven Development)에서는 컨텍스트 (Context) 관리가 매우 중요합니다.

컨텍스트 잔량을 항상 표시해 둠으로써, 장시간 작업 시 조금씩 줄어드는 것을 시각적으로 파악할 수 있어 세션 관리 (Session Management)에 대한 의식이 높아졌습니다.

셸 스크립트 (Shell Script)로 자유롭게 확장할 수 있으므로, 예를 들어 현재 시각이나 TODO 항목 수 등을 표시하는 등 아이디어에 따라 자유롭게 커스터마이징할 수 있습니다. 관심이 있다면 꼭 한번 시도해 보세요.