Claude Code 상태줄(statusline) 설정 가이드: /statusline 한 방으로 완성(2026)
터미널 하단을 실시간 대시보드로 바꿔 보세요 — 모델, 컨텍스트 윈도우 게이지, git 브랜치, 폴더, 비용을 한눈에. 내장 /statusline 명령어부터 색까지 다듬어진 결과물까지 그림으로 보는 12단계, 그리고 상태줄이 안 보일 때의 해결책까지 담았습니다.
핵심 요약
- /statusline은 Claude Code에 내장된 슬래시 명령어입니다. 한 번 실행하고 원하는 상태줄을 한 문장으로 말하면, statusline-setup 에이전트가 스크립트를 작성하고 ~/.claude/settings.json에 statusLine 블록까지 연결해 줍니다.
- Windows에서는 에이전트가 세 가지 길을 제시합니다: PowerShell 프로필 변환, WSL이나 Git Bash 설정 지정, 또는 사용자·디렉터리·모델·컨텍스트 사용량을 보여주는 기본값 새로 만들기.
- 스크립트는 표준 입력(stdin)으로 JSON 문서 하나를 읽습니다 — model.display_name, workspace.current_dir, context_window.used_percentage, cost.total_cost_usd 등. echo하는 것이 곧 상태줄이 되고, ANSI 색상과 여러 줄도 자유롭게 쓸 수 있습니다.
- 전부 로컬에서 돌고 토큰도 들지 않습니다. 갱신은 기본적으로 세션 이벤트를 따르고(refreshInterval로 N초 간격 설정 가능), 필요 없어지면 /statusline clear 한 번에 지웁니다.
How to Set Up a Custom Status Line in Claude Code CLI to Track API Costs and Context Usage (2026)
채널:ProgrammingKnowledge23:32
Claude Code最該裝的不是Skill，是這個腳本｜彩色進度條、費用、git 分支一眼看完
채널:YAHA學堂8:44
Your Claude Code Terminal Should Look Like This (Status Line Setup)
채널:Leon van Zyl9:02
How to Add a Custom Status Line in Claude Code on Windows 11 (Project-Level Setup)
채널:Devtamin7:27
Status line — Claude Code documentation
공식 문서:code.claude.com
1–4단계는 Windows PowerShell, 5–12단계는 macOS에서 녹화했습니다. 스틸 컷은 깨끗한 화면 녹화에서만 가져왔습니다 — 크리에이터 얼굴 캠이나 구워진 오버레이가 있는 프레임은 하나도 쓰지 않았습니다.
운영체제를 먼저 밝히기, 스크립트를 전역·별도 파일로 두기, jq 필요, 디버그 파일 요령 — 이 팁들은 위의 추가 영상 두 편에서 왔습니다. 심화 섹션의 필드 이름과 갱신 동작은 공식 statusline 문서를 따릅니다.
/statusline 워크스루 — 그림으로 보는 12단계
/statusline 실행하고 Claude에게 연결 맡기기
- 1
터미널에서 Claude Code 시작하기
PowerShell, 터미널, 어떤 셸에서든 claude를 입력해 실행합니다. 새 세션에는 환영 박스와 빈 프롬프트만 있을 뿐 — 입력창 아래 줄, 즉 상태줄이 자리할 공간은 ~/.claude/settings.json에 statusLine 블록이 추가되기 전까지 존재하지 않습니다.
Windows PowerShell의 Claude Code v2.1.83 새 세션 — 환영 박스, 빈 프롬프트, 상태줄은 아직 없음.0:22부터 시청 - 2
/statusline 명령어 입력하기
슬래시 명령어 메뉴에 담백하게 적혀 있습니다: Claude Code의 상태줄 UI 설정. Enter만 누르면 됩니다. 이 내장 명령어는 자연어를 이해하므로 스크립트를 직접 쓸 필요가 없습니다 — 물론 생성된 결과를 나중에 고쳐 써도 됩니다.
자동완성은 /statusline을 "Claude Code 상태줄 UI를 설정하는 명령어"로 소개합니다.0:32부터 시청 - 3
셋업 에이전트의 질문에 답하기
전용 statusline-setup 에이전트가 이어받습니다. Windows에서는 표준 셸 설정을 찾지 못했다고 알리고 세 가지 길을 제시합니다: PS1 프로필을 붙여넣어 변환시키기, WSL이나 Git Bash 설정 지정하기, 또는 사용자·디렉터리·모델·컨텍스트 사용량을 보여주는 기본값으로 시작하기. 세 길 모두 같은 settings.json 블록으로 끝납니다.
Windows의 세 가지 선택지: PS1 변환, 커스텀 설정 지정, 또는 무난한 기본값으로 시작.1:20부터 시청 - 4
작성된 설정과 스크립트 확인하기
에이전트가 끝나면 상태줄 미리보기를 출력합니다 — 사용자명, 디렉터리, git 브랜치, 모델, 컨텍스트 퍼센트 — 그리고 모든 파일의 위치를 정확히 알려줍니다: 설정은 ~/.claude/settings.json, 스크립트는 ~/.claude/statusline-command.sh. macOS와 Linux에서는 같은 흐름으로 새로 만드는 대신 기존 .zshrc나 .bashrc 프롬프트를 변환할 수도 있습니다.
hardik | ~/Dev/project | main | Claude Opus 4.6 | ctx:42% 미리보기와 두 파일 경로로 셋업 완료.3:06부터 시청
원하는 상태줄을 자연어 한 문장으로 설명하기
- 5
원하는 상태줄을 정확히 요청하기
/statusline은 언제든 다시 실행할 수 있고, 상태줄을 한 문장으로 요청합니다: 모델 이름과 컨텍스트 퍼센트를 진행 바로 보여줘, 같은 식으로. 다른 언어로 요청해도 됩니다 — 이 명령어는 본질적으로 에이전트에게 주는 프롬프트일 뿐입니다. 새 요청은 같은 스크립트를 다시 쓸 뿐, 중복으로 쌓이지 않습니다.
자연어 한 문장 — 모델 이름과 컨텍스트 퍼센트 진행 바 — 그것이 인터페이스의 전부입니다.1:07부터 시청 - 6
statusline-setup 도구가 일하는 모습 보기
Claude Code는 내장 statusline-setup 도구를 호출해 현재 ~/.claude/settings.json과 상태줄 스크립트를 읽은 뒤 다시 씁니다. Claude 자체 호버 카드가 기능을 요약합니다: 컨텍스트 윈도우 사용량, 비용, git 상태를 모니터링하는 커스텀 상태 바 구성.
실행 중인 statusline-setup 도구 — 설정과 스크립트를 읽는 중, 호버에는 기능 설명.1:12부터 시청 - 7
새 상태줄과 만나기
완료되면 에이전트가 디자인을 되짚습니다 — 굵은 시안색 모델 이름, 49%까지 초록, 50%에서 노랑, 80%에서 빨강으로 바뀌는 20자 폭 컨텍스트 바 — 그리고 상태줄은 이미 터미널 하단에서 살아 움직입니다. 재시작도 필요 없고, 같은 세션에서 바로 조정을 요청할 수 있습니다.
에이전트의 요약 아래, 컨텍스트 2%를 표시하는 실시간 Opus 4.6 (1M context) 바.1:27부터 시청
생성된 스크립트 읽어보기
- 8
JSON 문서 하나가 stdin으로 도착한다
생성된 스크립트를 열어 보세요 — macOS와 Linux는 ~/.claude/statusline.sh, Windows는 .ps1 / statusline-command.sh 변형. 갱신이 있을 때마다 Claude Code가 세션의 JSON 스냅샷을 스크립트의 표준 입력으로 흘려보냅니다. 생성된 Bash는 jq로 파싱합니다: .model.display_name, .workspace.current_dir, .cost.total_cost_usd, .cost.total_duration_ms, .context_window.used_percentage.
파싱 부분: stdin에서 다섯 번의 jq 읽기, 90%와 70% 컨텍스트 임계값으로 BAR_COLOR 선택.5:46부터 시청 - 9
echo하는 것이 곧 상태줄이 된다
스크립트 끝부분은 순수한 표현 로직입니다: printf로 비용 포매팅, 밀리초를 분과 초로 변환, 상태줄 한 줄마다 echo 하나 — 첫 줄은 모델+폴더+git 브랜치, 둘째 줄은 바·퍼센트·비용·타이머. ANSI 색상 이스케이프도 환영이고, echo를 하나 더하면 줄도 하나 늘어납니다.
echo 두 줄이 상태줄 두 줄로: 모델+디렉터리+브랜치, 그리고 바·퍼센트·비용·타이머.6:13부터 시청 - 10
같은 방식으로 git 정보 추가하기
git 데이터는 서브프로세스 한 번이면 됩니다: git rev-parse --git-dir로 저장소인지 판별, git branch --show-current로 브랜치 이름 획득, git diff --cached --numstat와 --numstat로 스테이징·수정 파일 수 집계. 생성 예제는 스테이징 수를 초록, 수정 수를 노랑으로 칠합니다 — 여러 Claude Code 세션을 브랜치별로 띄워 놓고 작업할 때 싼 안전장치가 되어 줍니다.
스테이징 수와 수정 수로 조립한 GIT_STATUS, ANSI 코드로 초록·노랑 착색.5:01부터 시청
설정 블록은 내 것: 지우기, 다시 쓰기, 여러 줄로
- 11
모든 것은 settings.json 블록 하나에 매달려 있다
~/.claude/settings.json을 들여다보면 기능 전체가 statusLine 객체 하나입니다: type은 "command", command는 실행할 스크립트를 가리킵니다 — 이 구성에서는 bash ~/.claude/statusline-command.sh. /statusline clear를 실행하면 에이전트가 블록을 지우고, 새 상태줄을 설명하면 다시 씁니다. 저장소별 상태줄이 필요하면 프로젝트의 .claude/settings.json에 둬도 됩니다.
/statusline clear의 diff: statusLine 블록이 settings.json에서 빠지고, 언제든 다시 쓸 준비 완료.1:41부터 시청 - 12
심화: 멀티라인으로 비용·경과 시간·저장소 링크까지
줄은 공짜로 쌓입니다. 공식 문서의 멀티라인 예제는 1행에 OSC 8 이스케이프 시퀀스로 클릭 가능한 저장소 링크를, 2행에 컨텍스트 바, printf '$%.2f'로 포맷한 세션 비용, 경과한 분과 초를 실어 날릅니다. 임계값, 레이트 리밋 퍼센트, vim 모드 — 원하는 조합을 요청하고 마음에 들 때까지 다듬으면 됩니다.
주석 달린 예제: 1행은 OSC 8 저장소 링크, 2행은 바·비용·경과 시간.7:31부터 시청
statusline 스크립트가 받는 stdin JSON
Claude Code는 스크립트를 호출할 때 세션의 JSON 스냅샷을 표준 입력으로 넘깁니다. 공식 문서 기준으로 알아둘 만한 필드들입니다 — 어떤 것이든 /statusline 한 문장에 언급하면 에이전트가 연결해 줍니다:
- 1세션 기본 — session_id, transcript_path, cwd, version. 첫 프롬프트를 보낸 뒤에는 session_name과 prompt_id도 붙습니다.
- 2model.id와 model.display_name — 상태줄이 흔히 맨 앞에 두는 현재 Claude 모델.
- 3workspace.current_dir, workspace.project_dir, workspace.added_dirs. 폴더가 호스티드 저장소에 속하면 workspace.git_worktree와 repo.owner / repo.name도.
- 4context_window.used_percentage와 remaining_percentage — used는 입력, 캐시 생성, 캐시 읽기 토큰을 세지만 출력 토큰은 세지 않습니다.
- 5context_window.current_usage는 그 내역으로 input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens로 나뉩니다. 첫 API 호출 전과 /compact 직후에는 null입니다.
- 6cost.total_cost_usd, cost.total_duration_ms, cost.total_api_duration_ms, cost.total_lines_added, cost.total_lines_removed — 비용과 페이스를 보여주는 상태줄용.
- 7Pro/Max 플랜에는 rate_limits.five_hour와 rate_limits.seven_day(used_percentage, resets_at 포함). 게이트웨이 구성이라면 spend_limit 쌍이 나타납니다 — 각 윈도우는 따로 없을 수 있으니 방어 코드를 넣으세요.
- 8그 외 — exceeds_200k_tokens, fast_mode, effort.level, thinking.enabled, output_style.name, vim.mode, agent.name, pr.number / pr.url / pr.review_state, 그리고 worktree.* 계열.
필드 이름은 공식 statusline 문서를 따르며, 그 문서에는 Bash·Python·Node.js용 완성 스크립트, Windows PowerShell 버전, 느린 머신용 git 캐시 레시피도 실려 있습니다.
문제 해결: 상태줄이 안 보이거나, 틀리거나, 늦을 때
상태줄 고장은 거의 다섯 가지 원인으로 모입니다. 전부 같은 세션에서 고칠 수 있습니다 — 재설치는 필요 없습니다.
- 1아예 안 보임 — 먼저 ~/.claude/settings.json의 JSON이 깨졌는지 확인하세요. 녹화 중에도 명령 경로에 오타 하나가 있어 상태줄이 침묵하다가, 고치고 세션을 재시작해서야 나타난 Windows 셋업이 있었습니다. 권한 프롬프트가 열려 있는 동안에도 상태줄은 숨고, 워크스페이스를 신뢰하기 전에는 스크립트가 실행되지 않습니다.
- 2오류 없이 빈 상태줄 — 스크립트가 0이 아닌 상태로 끝났거나 아무것도 출력하지 않은 것입니다. 손으로 직접 실행해 보세요. 예: echo '{"model":{"display_name":"Opus"}}' | bash ~/.claude/statusline.sh. 출력을 읽어 보고, claude --debug는 스크립트 stderr도 기록합니다.
- 3한 프로젝트에서만 동작 — 블록이 홈 디렉터리가 아니라 프로젝트의 .claude/settings.json에 떨어졌습니다. ~/.claude/settings.json으로 옮기면 모든 프로젝트에서 상태줄이 보입니다.
- 4숫자가 이상함 — 스크립트가 잘못된 프로퍼티를 읽고 있을 확률이 높습니다. Claude에게 원본 stdin JSON을 디버그 파일로 덤프하게 하고, 그 파일을 읽고 필드를 고치세요. 녹화된 macOS 세션이 정확히 이 방법으로 퍼센트를 스스로 고쳤습니다.
- 5macOS나 Linux에서 스크립트는 있는데 아무것도 그려지지 않음 — jq가 없습니다. 설치하고(brew install jq, sudo apt install jq 또는 Windows 등가물), 그다음 Claude에게 상태줄 업데이트를 시켜 스크립트를 다시 생성하게 하세요.
상태줄 갱신 주기(그리고 비용)
스크립트는 세션 시작 때 한 번 돌고, 이후에는 무언가 일어날 때마다 다시 돕니다: 새 어시스턴트 메시지, /compact 완료, 권한 모드나 vim 모드 변경, 명령 자체의 수정, 레이트 리밋 윈도우 리셋, 따뜻한 프롬프트 캐시 만료. 갱신은 300밀리초로 디바운스되고, 실행 중인 실행은 더 새것이 도착하면 취소됩니다.
갱신이 이벤트 주도이므로, 가만히 있을 때 — 가령 긴 서브에이전트 실행을 기다리는 동안 — 상태줄은 조용해집니다. statusLine 블록에 refreshInterval을 추가하면 시간 기반 데이터를 위해 N초마다 스크립트를 다시 실행합니다. 이 모든 것은 API를 건드리지 않습니다: 스크립트는 로컬에서 돌고 토큰을 소모하지 않으며, echo 줄이 하나 늘면 표시도 한 줄 늘어납니다.
만져볼 수 있는 다이얼이 두 개 더 있습니다: hideVimModeIndicator는 스크립트가 vim 모드를 직접 그릴 때 내장 -- INSERT -- 표시를 숨기고, 별개의 subagentStatusLine 설정은 서브에이전트에게 에이전트 패널 전용 커스텀 줄을 줍니다.