Claude Code 스테이터스라인: 생산성을 위한 터미널 상태 표시줄 설정(2026)

저자: Jasmine, Windows에서 매일 Claude Code를 끼고 사는 개발자예요.

Claude Code 스테이터스라인이란?

Claude Code 스테이터스라인은 모든 Claude Code 세션 맨 아래에 렌더링되는 커스터마이즈 가능한 줄로, 직접 설정하는 셸 스크립트가 생성해요. 세션 상태가 바뀔 때마다 Claude Code는 그 스크립트를 호출하고, 세션 전체 상태를 stdin으로 전달되는 JSON으로 넘긴 뒤, 스크립트가 stdout으로 되돌려 쓴 내용을 그대로 스테이터스라인으로 출력해요. 다시 말해, JSON 덩어리를 받아서 원하는 필드를 고르고, 원하는 대로 서식을 입혀 출력하면, Claude Code는 그 결과를 표시만 해요.

바로 새겨둘 핵심은, 스테이터스라인은 내 컴퓨터에서 로컬로 실행되고, API 호출을 하지 않으며, 토큰을 소모하지 않는다는 점이에요. 이것은 "AI" 기능이 아니라 stdin을 읽는 bash/PowerShell/Python 스크립트일 뿐이에요. 그래서 세션 요금에 영향을 주지 않고 원하는 만큼 많이 또는 적게 표시할 수 있어요. Claude Code는 이벤트(모델 전환, 도구 호출, 컨텍스트 업데이트 등)에서만 스크립트를 다시 실행하고, 호출을 가볍게 디바운스하므로 끊임없이 실행되지는 않아요. 즉, 남용하지만 않는다면 조금 무거운 스크립트도 괜찮아요(아래 성능 섹션 참고).

작업 디렉터리만 보여주는 기본 상태 표시줄과 달리, 커스텀 스테이터스라인은 코딩하는 동안 정말 중요한 것만 골라 끌어올 수 있게 해줘요. 이제 막 시작했다면, 먼저 Claude Code란 무엇이고 무엇에 쓰는지를 읽어 맥락을 잡은 다음, 여기로 돌아와 설정하세요.

더 생산적이려면 스테이터스라인에 무엇을 표시해야 할까?

스테이터스라인에 모든 필드를 욱여넣지 마세요. 0.5초 만에 훑어보고 바로 행동으로 옮길 수 있는 짧은 줄이 좋은 줄이에요. 몇 달 실제로 써 본 뒤, 표시할 가치가 가장 크다고 느낀 것은 다음과 같아요:

• 남은 컨텍스트 비율 - 가장 중요한 항목이에요. 컨텍스트가 위험 구간에 들어가면, 작업 도중에 Claude Code가 대화를 마음대로 압축하기 전에 직접 /compact를 하거나 작업을 나눌 수 있어요.
• 사용 중인 모델 - Opus인지 Sonnet인지 알아야 압정에 큰 망치를 쓰는(또는 그 반대의) 실수를 피할 수 있어요. 방금 모델을 바꾼 걸 깜빡하기 쉽거든요.
• 세션 비용 - 실시간으로 갱신되는 USD 금액이 있으면 어떤 작업이 돈을 태우고 있는지 감이 와요. 특히 API 토큰 단위로 과금될 때 유용해요.
• Git 브랜치 + 스테이징/수정된 파일 수 - 잘못된 브랜치에 커밋하는 것을 피하고, 저장하지 않은 변경이 몇 개인지 확인할 수 있어요.
• 5시간 / 7일 사용량 제한(Pro/Max 플랜) - 남은 한도가 줄어드는 것이 보이므로 긴 작업 도중에 끊기지 않아요.
• 디렉터리 / worktree - 여러 worktree를 동시에 열어 둘 때 유용해요.

제 규칙은, 1번째 줄에는 항상 모델 + 컨텍스트 %를 두고, 비용/Git/사용량 제한은 정말 필요할 때만 추가하는 거예요. 매일 즐겨 쓰는 명령을 더 보려면 Claude Code 치트 시트를 참고하세요.

가장 빠른 방법: /statusline 명령

설정 파일을 건드리고 싶지 않다면, 가장 빠른 길은 Claude Code 세션 안에서 그냥 평범한 말로 요청하는 거예요. /statusline 뒤에 보고 싶은 내용을 설명해서 입력하세요:

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

Claude Code가 대신 스크립트를 작성해 ~/.claude/ 아래에 저장하고, settings.json에 설정 블록을 자동으로 추가해줘요. 이 단계는 새 파일을 만들고 설정을 편집하므로, Claude Code는 쓰기 전에 변경 사항 승인을 요청해요. 내용을 훑어보고 수락하세요. 끝나면 바로 다음 상호작용부터 스테이터스라인이 나타나요.

이것은 빠르게 초안을 얻는 가장 좋은 방법이고, 이후에 열어서 취향껏 손볼 수 있어요. 기본 조작과 워크플로를 먼저 이해하고 싶다면 초보자를 위한 Claude Code 가이드를 참고하세요.

settings.json으로 수동 설정하기(단계별)

완전한 제어를 원하나요? 직접 설정하세요. 단 3단계예요.

1단계 - 스크립트 만들기 ~/.claude/statusline.sh — stdin에서 JSON을 읽고, jq로 원하는 필드를 뽑아, 한 줄을 출력해요:

#!/bin/bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name // "?"')
dir=$(echo "$input" | jq -r '.workspace.current_dir // "."' | xargs basename)
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0')
printf "[%s] 📁 %s | %s%% context" "$model" "$dir" "$pct"

2단계 - 실행 가능하게 만들기:

chmod +x ~/.claude/statusline.sh

⚠️ 가장 흔한 실수: chmod +x를 잊으면 스테이터스라인은 뚜렷한 오류도 없이 아무것도 표시하지 않아요. 스테이터스라인이 "조용하다면" 먼저 실행 권한을 확인하세요.

3단계 - 다음 파일에 선언하기 ~/.claude/settings.json:

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

Claude Code는 다음 상호작용에서 이를 다시 불러와요 - 재시작은 필요 없어요. 유용한 옵션 몇 가지: padding은 왼쪽 여백을 제어하고(0으로 두면 가장자리에 딱 붙어요), refreshInterval(밀리초 단위)은 시계나 사용량 제한 같은 시간 기반 데이터를 위해 스크립트를 타이머로 다시 실행하게 해요. 아주 짧은 스크립트라면 별도 파일 없이 jq -r 명령을 command 필드에 직접 인라인으로 넣을 수도 있어요 - 하지만 별도 파일이 훨씬 유지보수하기 쉬워요.

JSON 데이터 표 - 스테이터스라인이 받는 내용

실행할 때마다 스크립트는 stdin으로 완전한 JSON 객체를 받아요. 가장 자주 쓰게 될 필드에 대한 참고 자료를 아래에 정리했어요(출처: 공식 문서 code.claude.com/docs/en/statusline, 2026년 8월 접속):

중요한 참고: 많은 필드는 특히 첫 API 응답 전에는 없거나 null일 수 있어요. jq에서는 항상 폴백을 사용하세요: 숫자에는 // 0, 문자열에는 // "empty" 또는 // "". 일부 최신 필드는 충분히 최근의 Claude Code 빌드가 필요해요. 실행 중인 빌드에서 시험해 보지 않은 채 필드가 없다고 단정하지 마세요.

복붙용 샘플 스크립트(필요한 것을 고르세요)

아래 프리셋은 bash + jq를 사용해요. Python이나 Node로 작성하면 JSON 파싱이 내장돼 있어 더 짧아져요.

1) 컨텍스트 바 - 진행 막대 + %:

#!/bin/bash
input=$(cat)
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
filled=$((pct / 10)); empty=$((10 - filled))
bar=$(printf '▓%.0s' $(seq 1 $filled))$(printf '░%.0s' $(seq 1 $empty))
printf "%s %s%%" "$bar" "$pct"

2) 색상 Git - 브랜치 + 스테이징(초록)/수정(노랑) 파일을 ANSI 색상 코드로 표시:

#!/bin/bash
input=$(cat)
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 ' ')
printf " %s \033[32m+%s\033[0m \033[33m~%s\033[0m" "$branch" "$staged" "$modified"

3) 비용 + 지속 시간:

#!/bin/bash
input=$(cat)
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
ms=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')
sec=$((ms / 1000)); min=$((sec / 60)); s=$((sec % 60))
printf "\$%.2f | %dm %ds" "$cost" "$min" "$s"

4) 여러 줄 + 색상 임계값 - 1번째 줄: 모델/디렉터리/브랜치, 2번째 줄: 색이 바뀌는 막대(초록 <70, 노랑 70-89, 빨강 90+) + 비용 + 사용량 제한:

#!/bin/bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name // "?"')
dir=$(echo "$input" | jq -r '.workspace.current_dir // "."' | xargs basename)
branch=$(git branch --show-current 2>/dev/null)
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
rl=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
if [ "$pct" -ge 90 ]; then c="\033[31m"; elif [ "$pct" -ge 70 ]; then c="\033[33m"; else c="\033[32m"; fi
printf "[%s] 📁 %s %s\n" "$model" "$dir" "$branch"
printf "${c}%s%% context\033[0m | \$%.2f" "$pct" "$cost"
[ -n "$rl" ] && printf " | 5h: %s%%" "$rl"

이 여러 줄 프리셋은 제가 실제로 매일 쓰는 거예요. 윗줄로 상황을 파악하고, 아랫줄이 색을 바꿔 컨텍스트가 차오르는 걸 경고해줘요 - 흐름 도중에 /compact당하지 않는 데 아주 효과적이에요.

Windows에서 설정하기(PowerShell + Git Bash)

세상에 나와 있는 가이드 대부분은 bash 전용이에요. (저처럼) Windows를 쓴다면, 잘 동작하는 두 가지 방법이 있어요.

옵션 A - Git Bash: 가장 간단해요. Git Bash와 jq가 설치돼 있으면 위의 .sh 스크립트가 그대로 실행돼요. 평소처럼 command를 .sh 파일로 가리키기만 하면 돼요.

옵션 B - PowerShell: stdin을 읽어 JSON을 파싱하는 .ps1 스크립트를 작성해요:

# C:/Users/you/.claude/statusline.ps1
$data = $input | Out-String | ConvertFrom-Json
$model = $data.model.display_name
$pct = [math]::Floor($data.context_window.used_percentage)
Write-Host "[$model] $pct% context" -NoNewline

그런 다음 settings.json에 선언해요:

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

⚠️ Windows 백슬래시 함정: command 필드의 경로는 항상 슬래시(/)로 쓰세요. Git Bash가 백슬래시 \를 "삼켜" 버려서 명령이 조용히 실패해요 - 스테이터스라인에 아무것도 안 뜨고 오류도 보고되지 않아요. ~ 문자는 그대로 잘 동작해요.

바로 이 지점에서 많은 Windows 사용자가 걸려 넘어져요. 스크립트는 맞는데 경로의 슬래시 방향이 틀린 거예요. \를 /로 바꾸면 실행돼요.

성능 팁: 스테이터스라인이 세션을 느리게 하지 않도록

스크립트는 아주 자주 실행돼요. 큰 저장소에서는 git status나 git diff가 매번 수백 밀리초씩 걸릴 수 있고, 그게 쌓이면 세션 전체가 살짝 굼떠져요. 스테이터스라인을 빠르게 유지하는 팁 몇 가지:

• Git 결과를 session_id를 키로 삼아 임시 파일에 캐시하세요 - 매번 git을 호출하는 대신 약 5초마다 갱신해요. 캐시 키로는 session_id를 사용하세요 - 절대로 $$/PID를 쓰지 마세요. 스크립트 실행마다 바뀌어 캐시가 쓸모없어져요.
• 출력을 짧게 유지하세요 - 한 줄, 몇 개 필드로. 긴 줄은 느리고 읽기도 어려워요.
• refreshInterval을 사용하세요 - 시계, 사용량 제한 같은 시간 기반 데이터는 힘들게 다시 계산하는 대신 이걸 쓰세요.
• COLUMNS/LINES를 읽으세요 - 너비를 가늠해 터미널이 좁을 때 잘라내세요.

경험칙: 스크립트가 약 300ms 이상 걸리면 지연이 느껴져요. 캐싱과 잘라내기가 가장 효과 큰 두 지렛대예요.

흔한 문제 & 해결 방법

진단하려면 claude --debug를 실행해 스크립트의 종료 코드와 stderr를 확인하세요. 또한 일부 에뮬레이터(예: Terminal.app)는 OSC 8 링크를 지원하지 않아서, 스테이터스라인에 하이퍼링크를 넣어도 클릭되지 않을 수 있어요 - 이건 터미널의 한계이지 스크립트 버그가 아니에요.

스크립트 편집이 싫다면? 비주얼 스테이터스라인 빌더를 쓰세요

상태 표시줄 하나 얻자고 누구나 bash나 PowerShell을 쓰고 싶어 하지는 않아요. 그렇다면 노코드 선택지 하나가 AgentKit 번들 — 현재 $149($198에서)이에요. 데스크톱 앱에 비주얼 스테이터스라인 빌더가 있어서, 손으로 코딩하는 대신 필드(모델, 컨텍스트, 비용, Git 등)를 드래그 앤 드롭할 수 있어요 - 라이선스, 스킬, MCP 통합을 한곳에서 관리하는 기능도 함께요. 터미널이 부담스러운 사람에게는 settings.json을 건드리지 않고 스테이터스라인을 만드는 방법이에요.

솔직히 말하면, /statusline과 위 스크립트는 완전히 무료이고 거의 모든 사람에게 충분해요 - 비주얼 빌더는 노코드로 하고 싶거나 스킬/에이전트 세트 전체를 한곳에서 관리하고 싶을 때 더 편리할 뿐이에요. 결정하기 전에 파고들고 싶다면 AgentKit이 무엇이고 그만한 가치가 있는지(리뷰)를 읽어 보세요.

자주 묻는 질문(FAQ)

스테이터스라인은 토큰을 소모하나요?

아니요. 스테이터스라인은 내 컴퓨터에서 로컬 스크립트를 실행하고 Claude API 호출을 하지 않으므로 토큰을 쓰지 않아요. 세션 비용에 영향을 주지 않고 원하는 만큼 정보를 표시할 수 있어요.

Windows에서 동작하나요?

네. .sh 스크립트는 Git Bash로 실행할 수 있고, .ps1을 작성해 powershell -NoProfile -File로 호출할 수도 있어요. 백슬래시 함정을 피하려면 경로를 슬래시(/)로 쓰기만 하면 돼요.

왜 스테이터스라인이 안 보이나요?

가장 흔한 원인은 스크립트에 chmod +x를 잊은 거예요. 그 밖에: 스크립트가 stdout 대신 stderr로 출력함, 워크스페이스 신뢰를 수락하지 않음, disableAllHooks가 켜져 있음, 또는 Windows에서 경로 슬래시 방향이 틀림 등이에요. 오류를 보려면 claude --debug를 실행하세요.

/statusline은 settings.json 편집과 어떻게 다른가요?

/statusline 명령을 쓰면 평범한 설명만으로 Claude Code가 스크립트를 생성하고 설정까지 해줘요 - 빠르고 초보자에게 아주 좋아요. settings.json을 직접 편집하면 내용과 서식을 완전히 제어할 수 있어요. 많은 사람이 /statusline으로 초안을 만든 뒤 파일을 손봐요.

컨텍스트 %를 표시하는 의미가 뭔가요?

대화를 미리 관리하기 위해서예요. 컨텍스트가 거의 찼을 때, 작업 도중에 Claude Code가 압축하도록 두는 대신 직접 /compact를 하거나 작업을 나눌 수 있어요 - Claude Code의 압축은 당신의 맥락 흐름을 끊어 놓기 쉽거든요.

코드 없이 되는 기성 설정이 있나요?

네. 가장 빠른 건 /statusline으로, Claude가 대신 작성해줘요. 완전한 드래그 앤 드롭 노코드 인터페이스를 원한다면, AgentKit 데스크톱 앱의 비주얼 스테이터스라인 빌더가 한 가지 선택지예요.

마무리 + 다음 단계

정교한 스크립트는 필요 없어요. 모델 + 컨텍스트 %를 보여주는 단순한 한 줄만으로도 이미 눈에 띄는 생산성 향상을 얻어요. 필요를 느낄 때 조금씩 레벨업하면 돼요. /statusline으로 시작한 뒤 파일을 열어 취향껏 조정하세요. 자주 쓰는 명령을 모으려면 Claude Code 치트 시트를, Claude Code가 프로젝트를 더 잘 이해하도록 하려면 CLAUDE.md 가이드를 읽어 보세요. 이제 막 시작했나요? Claude Code란 무엇인지로 돌아가세요.