- 작업 중 컨텍스트 윈도우 사용량을 모니터링하려는 경우
- 세션 비용을 추적해야 하는 경우
- 여러 세션에서 작업하고 이들을 구분해야 하는 경우
- git 브랜치 및 상태를 항상 표시하려는 경우

상태 표시줄 설정
/statusline 명령을 사용하여 Claude Code가 스크립트를 생성하도록 하거나, 수동으로 스크립트를 만들고 설정에 추가합니다.
/statusline 명령 사용
/statusline 명령은 표시하려는 내용을 설명하는 자연어 지시사항을 허용합니다. Claude Code는 ~/.claude/ 디렉토리에 스크립트 파일을 생성하고 설정을 자동으로 업데이트합니다:
상태 표시줄 수동 구성
사용자 설정(~/.claude/settings.json, 여기서 ~는 홈 디렉토리) 또는 프로젝트 설정에 statusLine 필드를 추가합니다. type을 "command"로 설정하고 command를 스크립트 경로 또는 인라인 셸 명령으로 지정합니다. 스크립트 생성에 대한 전체 설명은 상태 표시줄 단계별 구축을 참조하세요.
command 필드는 셸에서 실행되므로 스크립트 파일 대신 인라인 명령을 사용할 수도 있습니다. 이 예제는 jq를 사용하여 JSON 입력을 구문 분석하고 모델 이름과 컨텍스트 백분율을 표시합니다:
padding 필드는 상태 표시줄 콘텐츠에 추가 수평 간격(문자 단위)을 추가합니다. 기본값은 0입니다. 이 패딩은 인터페이스의 기본 제공 간격에 추가되므로 터미널 가장자리로부터의 절대 거리가 아닌 상대 들여쓰기를 제어합니다.
상태 표시줄 비활성화
/statusline을 실행하고 상태 표시줄을 제거하거나 지우도록 요청합니다(예: /statusline delete, /statusline clear, /statusline remove it). settings.json에서 statusLine 필드를 수동으로 삭제할 수도 있습니다.
상태 표시줄 단계별 구축
이 설명서는 현재 모델, 작업 디렉토리 및 컨텍스트 윈도우 사용량 백분율을 표시하는 상태 표시줄을 수동으로 만들어 내부 동작을 보여줍니다./statusline을 원하는 내용 설명과 함께 실행하면 이 모든 것이 자동으로 구성됩니다.
JSON을 읽고 출력을 인쇄하는 스크립트 만들기
Claude Code는 stdin을 통해 JSON 데이터를 스크립트로 보냅니다. 이 스크립트는
jq(설치해야 할 수 있는 명령줄 JSON 파서)를 사용하여 모델 이름, 디렉토리 및 컨텍스트 백분율을 추출한 다음 형식이 지정된 줄을 인쇄합니다.이를 ~/.claude/statusline.sh에 저장합니다(여기서 ~는 홈 디렉토리이며, macOS에서는 /Users/username, Linux에서는 /home/username):상태 표시줄 작동 방식
Claude Code는 스크립트를 실행하고 stdin을 통해 JSON 세션 데이터를 파이프합니다. 스크립트는 JSON을 읽고 필요한 것을 추출한 다음 stdout에 텍스트를 인쇄합니다. Claude Code는 스크립트가 인쇄하는 모든 것을 표시합니다. 업데이트 시기 스크립트는 새로운 어시스턴트 메시지 후, 권한 모드가 변경될 때 또는 vim 모드가 전환될 때 실행됩니다. 업데이트는 300ms에서 디바운스되므로 빠른 변경이 함께 일괄 처리되고 스크립트는 상황이 안정화되면 한 번 실행됩니다. 스크립트가 여전히 실행 중인 동안 새 업데이트가 트리거되면 진행 중인 실행이 취소됩니다. 스크립트를 편집하면 Claude Code와의 다음 상호 작용이 업데이트를 트리거할 때까지 변경 사항이 나타나지 않습니다. 스크립트가 출력할 수 있는 것- 여러 줄: 각
echo또는print문은 별도의 행으로 표시됩니다. 다중 줄 예제를 참조하세요. - 색상: 녹색의 경우
\033[32m과 같은 ANSI 이스케이프 코드를 사용합니다(터미널이 지원해야 함). git 상태 예제를 참조하세요. - 링크: OSC 8 이스케이프 시퀀스를 사용하여 텍스트를 클릭 가능하게 만듭니다(macOS에서는 Cmd+클릭, Windows/Linux에서는 Ctrl+클릭). iTerm2, Kitty 또는 WezTerm과 같이 하이퍼링크를 지원하는 터미널이 필요합니다. 클릭 가능한 링크 예제를 참조하세요.
상태 표시줄은 로컬에서 실행되며 API 토큰을 소비하지 않습니다. 자동 완성 제안, 도움말 메뉴 및 권한 프롬프트를 포함한 특정 UI 상호 작용 중에 일시적으로 숨겨집니다.
사용 가능한 데이터
Claude Code는 stdin을 통해 스크립트에 다음 JSON 필드를 보냅니다:| 필드 | 설명 |
|---|---|
model.id, model.display_name | 현재 모델 식별자 및 표시 이름 |
cwd, workspace.current_dir | 현재 작업 디렉토리. 두 필드 모두 동일한 값을 포함합니다. workspace.current_dir은 workspace.project_dir과의 일관성을 위해 선호됩니다. |
workspace.project_dir | Claude Code가 시작된 디렉토리로, 세션 중에 작업 디렉토리가 변경되면 cwd와 다를 수 있습니다 |
cost.total_cost_usd | USD 단위의 총 세션 비용 |
cost.total_duration_ms | 세션 시작 이후의 총 벽시계 시간(밀리초) |
cost.total_api_duration_ms | API 응답 대기에 소비된 총 시간(밀리초) |
cost.total_lines_added, cost.total_lines_removed | 변경된 코드 줄 |
context_window.total_input_tokens, context_window.total_output_tokens | 세션 전체의 누적 토큰 수 |
context_window.context_window_size | 토큰 단위의 최대 컨텍스트 윈도우 크기. 기본값은 200,000이거나 확장된 컨텍스트가 있는 모델의 경우 1,000,000입니다. |
context_window.used_percentage | 사용된 컨텍스트 윈도우의 사전 계산된 백분율 |
context_window.remaining_percentage | 남은 컨텍스트 윈도우의 사전 계산된 백분율 |
context_window.current_usage | 마지막 API 호출의 토큰 수(컨텍스트 윈도우 필드에 설명됨) |
exceeds_200k_tokens | 가장 최근 API 응답의 총 토큰 수(입력, 캐시 및 출력 토큰 결합)가 200k를 초과하는지 여부. 이는 실제 컨텍스트 윈도우 크기와 관계없이 고정된 임계값입니다. |
session_id | 고유 세션 식별자 |
transcript_path | 대화 기록 파일의 경로 |
version | Claude Code 버전 |
output_style.name | 현재 출력 스타일의 이름 |
vim.mode | vim 모드가 활성화되어 있을 때 현재 vim 모드(NORMAL 또는 INSERT) |
agent.name | --agent 플래그 또는 에이전트 설정이 구성되어 있을 때 에이전트 이름 |
worktree.name | 활성 worktree의 이름. --worktree 세션 중에만 표시됩니다 |
worktree.path | worktree 디렉토리의 절대 경로 |
worktree.branch | worktree의 Git 브랜치 이름(예: "worktree-my-feature"). 훅 기반 worktree의 경우 없음 |
worktree.original_cwd | worktree에 들어가기 전에 Claude가 있던 디렉토리 |
worktree.original_branch | worktree에 들어가기 전에 체크아웃된 Git 브랜치. 훅 기반 worktree의 경우 없음 |
전체 JSON 스키마
전체 JSON 스키마
상태 표시줄 명령은 stdin을 통해 이 JSON 구조를 수신합니다:없을 수 있는 필드 (JSON에 없음):
vim: vim 모드가 활성화되어 있을 때만 나타남agent:--agent플래그 또는 에이전트 설정이 구성되어 있을 때만 나타남worktree:--worktree세션 중에만 나타남. 존재할 때branch및original_branch도 훅 기반 worktree의 경우 없을 수 있습니다
null일 수 있는 필드:context_window.current_usage: 세션의 첫 번째 API 호출 전에nullcontext_window.used_percentage,context_window.remaining_percentage: 세션 초기에null일 수 있음
컨텍스트 윈도우 필드
context_window 객체는 컨텍스트 사용량을 추적하는 두 가지 방법을 제공합니다:
- 누적 합계 (
total_input_tokens,total_output_tokens): 전체 세션 전체의 모든 토큰의 합계로, 총 소비량을 추적하는 데 유용합니다 - 현재 사용량 (
current_usage): 가장 최근 API 호출의 토큰 수로, 실제 컨텍스트 상태를 반영하므로 정확한 컨텍스트 백분율에 사용합니다
current_usage 객체에는 다음이 포함됩니다:
input_tokens: 현재 컨텍스트의 입력 토큰output_tokens: 생성된 출력 토큰cache_creation_input_tokens: 캐시에 기록된 토큰cache_read_input_tokens: 캐시에서 읽은 토큰
used_percentage 필드는 입력 토큰만으로 계산됩니다: input_tokens + cache_creation_input_tokens + cache_read_input_tokens. output_tokens는 포함하지 않습니다.
current_usage에서 컨텍스트 백분율을 수동으로 계산하는 경우 동일한 입력 전용 공식을 사용하여 used_percentage와 일치시킵니다.
current_usage 객체는 세션의 첫 번째 API 호출 전에 null입니다.
예제
이 예제는 일반적인 상태 표시줄 패턴을 보여줍니다. 예제를 사용하려면:- 스크립트를
~/.claude/statusline.sh(또는.py/.js)와 같은 파일에 저장합니다 - 실행 가능하게 만듭니다:
chmod +x ~/.claude/statusline.sh - 설정에 경로를 추가합니다
jq를 사용하여 JSON을 구문 분석합니다. Python 및 Node.js는 기본 제공 JSON 구문 분석을 가집니다.
컨텍스트 윈도우 사용량
현재 모델과 컨텍스트 윈도우 사용량을 시각적 진행률 표시줄과 함께 표시합니다. 각 스크립트는 stdin에서 JSON을 읽고,used_percentage 필드를 추출하고, 채워진 블록(▓)이 사용량을 나타내는 10자 막대를 구축합니다:

색상이 있는 git 상태
색상으로 구분된 스테이징 및 수정된 파일 표시기가 있는 git 브랜치를 표시합니다. 이 스크립트는 터미널 색상에 ANSI 이스케이프 코드를 사용합니다:\033[32m은 녹색, \033[33m은 노란색, \033[0m은 기본값으로 재설정합니다.

비용 및 기간 추적
세션의 API 비용 및 경과 시간을 추적합니다.cost.total_cost_usd 필드는 현재 세션의 모든 API 호출 비용을 누적합니다. cost.total_duration_ms 필드는 세션 시작 이후의 총 경과 시간을 측정하는 반면, cost.total_api_duration_ms는 API 응답 대기에 소비된 시간만 추적합니다.
각 스크립트는 비용을 통화로 형식화하고 밀리초를 분과 초로 변환합니다:

여러 줄 표시
스크립트는 여러 줄을 출력하여 더 풍부한 디스플레이를 만들 수 있습니다. 각echo 문은 상태 영역에서 별도의 행을 생성합니다.

print 또는 echo 문은 별도의 행을 만듭니다:
클릭 가능한 링크
이 예제는 GitHub 저장소에 대한 클릭 가능한 링크를 만듭니다. git 원격 URL을 읽고,sed를 사용하여 SSH 형식을 HTTPS로 변환하고, 저장소 이름을 OSC 8 이스케이프 코드로 래핑합니다. Cmd(macOS) 또는 Ctrl(Windows/Linux)을 누르고 클릭하여 브라우저에서 링크를 엽니다.

printf '%b'를 사용하여 다양한 셸에서 백슬래시 이스케이프를 더 안정적으로 해석합니다:
비용이 많이 드는 작업 캐싱
상태 표시줄 스크립트는 활성 세션 중에 자주 실행됩니다.git status 또는 git diff와 같은 명령은 특히 큰 저장소에서 느릴 수 있습니다. 이 예제는 git 정보를 임시 파일에 캐싱하고 5초마다만 새로 고칩니다.
/tmp/statusline-git-cache와 같은 안정적인 고정 파일 이름을 캐시 파일에 사용합니다. 각 상태 표시줄 호출은 새 프로세스로 실행되므로 $$, os.getpid() 또는 process.pid와 같은 프로세스 기반 식별자는 매번 다른 값을 생성하고 캐시는 재사용되지 않습니다.
각 스크립트는 git 명령을 실행하기 전에 캐시 파일이 누락되었거나 5초보다 오래되었는지 확인합니다:
Windows 구성
Windows에서 Claude Code는 Git Bash를 통해 상태 표시줄 명령을 실행합니다. 해당 셸에서 PowerShell을 호출할 수 있습니다:팁
- 모의 입력으로 테스트:
echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":25}}' | ./statusline.sh - 출력을 짧게 유지: 상태 표시줄의 너비가 제한되어 있으므로 긴 출력이 잘리거나 어색하게 줄 바꿈될 수 있습니다
- 느린 작업 캐싱: 스크립트는 활성 세션 중에 자주 실행되므로
git status와 같은 명령이 지연을 유발할 수 있습니다. 이를 처리하는 방법은 캐싱 예제를 참조하세요.
문제 해결
상태 표시줄이 나타나지 않음- 스크립트가 실행 가능한지 확인합니다:
chmod +x ~/.claude/statusline.sh - 스크립트가 stderr가 아닌 stdout으로 출력하는지 확인합니다
- 스크립트를 수동으로 실행하여 출력을 생성하는지 확인합니다
- 설정에서
disableAllHooks가true로 설정되어 있으면 상태 표시줄도 비활성화됩니다. 이 설정을 제거하거나false로 설정하여 다시 활성화합니다. claude --debug를 실행하여 세션의 첫 번째 상태 표시줄 호출에서 종료 코드 및 stderr를 기록합니다- Claude에 설정 파일을 읽고
statusLine명령을 직접 실행하도록 요청하여 오류를 표시합니다
-- 또는 빈 값을 표시함
- 필드는 첫 번째 API 응답이 완료되기 전에
null일 수 있습니다 - jq의
// 0과 같은 폴백으로 스크립트에서 null 값을 처리합니다 - 여러 메시지 후에도 값이 비어 있으면 Claude Code를 다시 시작합니다
- 누적 합계 대신 정확한 컨텍스트 상태를 위해
used_percentage를 사용합니다 total_input_tokens및total_output_tokens는 세션 전체에 누적되며 컨텍스트 윈도우 크기를 초과할 수 있습니다- 각각이 계산되는 시기로 인해 컨텍스트 백분율이
/context출력과 다를 수 있습니다
- 터미널이 OSC 8 하이퍼링크를 지원하는지 확인합니다(iTerm2, Kitty, WezTerm)
- Terminal.app은 클릭 가능한 링크를 지원하지 않습니다
- SSH 및 tmux 세션은 구성에 따라 OSC 시퀀스를 제거할 수 있습니다
\e]8;;과 같은 리터럴 텍스트로 이스케이프 시퀀스가 나타나면echo -e대신printf '%b'를 사용하여 더 안정적인 이스케이프 처리를 합니다
- 복잡한 이스케이프 시퀀스(ANSI 색상, OSC 8 링크)는 다른 UI 업데이트와 겹치면 가끔 손상된 출력을 유발할 수 있습니다
- 손상된 텍스트가 보이면 스크립트를 일반 텍스트 출력으로 단순화해 봅니다
- 이스케이프 코드가 있는 다중 줄 상태 표시줄은 일반 텍스트 단일 줄보다 렌더링 문제가 더 발생하기 쉽습니다
- 0이 아닌 코드로 종료되거나 출력을 생성하지 않는 스크립트는 상태 표시줄을 공백으로 만듭니다
- 느린 스크립트는 완료될 때까지 상태 표시줄이 업데이트되지 않도록 차단합니다. 오래된 출력을 피하려면 스크립트를 빠르게 유지합니다.
- 느린 스크립트가 실행 중인 동안 새 업데이트가 트리거되면 진행 중인 스크립트가 취소됩니다
- 구성하기 전에 모의 입력으로 스크립트를 독립적으로 테스트합니다
- MCP 서버 오류, 자동 업데이트 및 토큰 경고와 같은 시스템 알림은 상태 표시줄과 동일한 행의 오른쪽에 표시됩니다
- 자세한 모드를 활성화하면 이 영역에 토큰 카운터가 추가됩니다
- 좁은 터미널에서 이러한 알림이 상태 표시줄 출력을 자를 수 있습니다