Claude Code 상태 바 커스터마이징: 스크립트와 아이디어
초기 설정에서 한 발 더 나아가 보세요. statusline 스크립트가 받는 JSON, 화면에 올릴 만한 필드 — 모델, 토큰, 비용, 컨텍스트, git — , 색과 레이아웃 아이디어, 그리고 바로 가져다 쓸 수 있는 커뮤니티 스크립트까지 소개합니다.
요약
- /statusline이 스크립트를 대신 작성해 줍니다. 사용 중인 OS를 밝히고, 전역 설정과 별도의 .sh/.ps1 파일을 요청한 뒤, 두 파일을 승인하세요. ~/.claude/settings.json의 statusLine 항목과 그 항목이 가리키는 스크립트입니다.
- 스크립트는 stdin에서 JSON 객체 하나를 읽습니다 — model.display_name, workspace.current_dir, context_window.used_percentage, cost.total_cost_usd, rate_limits — 그리고 보여 주고 싶은 것을 출력합니다.
- 필드는 번호 목록으로 요청하고, 컨텍스트 바는 임계값으로 색을 입히고(50% 미만 초록, 75% 초과 빨강), 토큰은 K 단위로 반올림하며, 한 줄이 붐비면 여러 줄로 나눕니다.
- 또는 커뮤니티 스크립트를 설치하세요. npx contextbricks 한 줄이면 모델, git 브랜치와 커밋, 벽돌식 토큰 미터, 주간 한도 경고가 모두 갖춰집니다. /compact와 /clear 시점을 스스로 결정할 수 있습니다.
Claude Code's Hidden Status Line: Tokens, Model and Project, Your Way
채널: 호두의 AI 분석실 (Waldo AI Lab)5:27
ContextBricks: My Custom Claude Code Status Line
커뮤니티 스크립트: Jeremy Dawes6:17
Status line — official documentation
공식 문서: code.claude.com/docs
이 페이지의 사실은 공식 status line 문서와 위의 두 녹화 영상으로 교차 확인했으며, 인용한 JSON 필드 이름은 공식 레퍼런스와 정확히 일치합니다. 스크린샷은 모두 해당 녹화에서 추출한 프레임입니다.
스크린샷은 호두의 AI 분석실과 Jeremy Dawes(ContextBricks)의 튜토리얼 영상에서 가져온 프레임으로, 출처를 밝혔으며 매 단계마다 원본 타임스탬프로 연결됩니다.
상태 바 커스터마이징, 단계별로
/statusline 프롬프트를 한 번에 올바르게
- 1
OS와 범위, 스크립트 파일까지 밝히는 /statusline 프롬프트 한 줄
/statusline을 실행하고 세 가지를 먼저 밝히세요. 사용 중인 시스템(Mac, Linux, Windows, WSL), 상태 라인을 전역으로 설정할 것, 그리고 스크립트는 별도의 .sh 파일로 — Windows에서는 .ps1 — 만들 것을 요청합니다. 말하지 않으면 설정 에이전트가 환경을 추측해 엉뚱한 셸을 노릴 수 있고, 프로젝트 단위 스크립트는 한 리포지토리에서만 나타납니다. 프롬프트는 네 줄이면 충분하니 메모에 저장해 두고 재활용하세요.
준비된 /statusline 프롬프트: OS, 전역, 별도 스크립트 파일 — 붙여 넣기만 하면 됩니다.영상 1:15 지점 보기 - 2
설정 에이전트가 만드는 두 파일을 승인한다
읽기·쓰기 권한을 승인하면 에이전트가 무엇을 건드렸는지 정확히 보고합니다. ~/.claude/settings.json에는 statusLine 구성이 들어가고, ~/.claude/statusline-command.sh 같은 스크립트가 상태 라인 내용을 생성합니다. 로직을 별도 파일에 두면 나중에 Claude는 스크립트만 수정하지 설정 파일은 건드리지 않습니다. Claude Code를 재시작하면 라인이 나타납니다.
생성·갱신된 파일: settings.json이 statusLine 항목을 담고, 스크립트가 내용을 만듭니다.영상 3:20 지점 보기 - 3
더 추가하기 전에 기본 라인 사양을 읽는다
기본 생성 라인에는 현재 디렉터리, [Claude Opus 4.5] 같은 모델 이름, 기본이 아닐 때의 output style, vim 모드, 리포지토리 안일 때의 git 브랜치, 컨텍스트 윈도우 사용률이 표시됩니다. 예: Claude-project [Claude Opus 4.5] (git:main) 12%. 구성은 전역이므로 이 머신의 모든 Claude Code 세션에 적용됩니다.
기본 표시 목록과 생성된 상태 라인의 렌더링 예시.영상 2:45 지점 보기
라인에 표시할 것을 정한다
- 4
원하는 필드를 번호를 붙여 요청한다
추가 항목을 순서 목록으로 요청하면 에이전트가 번호가 붙은 표시 순서로 답합니다. 이번 실행의 결과: 모델 이름, 20자 프로그레스 바, 20% 식의 백분율, 40000/200000 형식의 토큰, git:main, 마지막으로 프로젝트 디렉터리 — Claude 3.5 Sonnet [==== ] 20% 40000/200000 git:main Claude-project로 렌더링됩니다. 변경 사항은 스크립트에 반영되며, Claude Code를 재시작하면 확인할 수 있습니다.
표시 순서 1-6과 렌더링 예시 라인, 모두 스크립트에 기록됩니다.영상 3:45 지점 보기 - 5
각 요소에 의미 있는 색을 부여한다
요소별 색을 요청하면 스크립트에는 임계값이 포함된 ANSI 코드가 들어갑니다. 이번에 합의된 표: 모델 이름 시안, 프로그레스 바는 50% 미만 초록, 50-75% 노랑, 75% 초과 빨강, 백분율은 바를 따름, 토큰 마젠타, 브랜치 초록, 프로젝트 이름 파랑, 구분자 회색. 빨강은 컨텍스트 바에만 묶어 두세요. 경고색은 진짜 압박이 왔을 때만 빛나야 합니다.
요소별 색상표. 프로그레스 바에는 임계값이 붙습니다.영상 4:15 지점 보기 - 6
토큰을 K 단위로 반올림하고 /context로 대조한다
21373/200000 같은 원시 숫자는 한눈에 읽히지 않습니다. K 단위를 요청하면 라인이 21k/200k로 표시되고, 에이전트는 반올림되었음을 알려 줍니다. 검증도 간단합니다. 같은 세션에서 /context를 실행해 비교하면 총합이 일치합니다. 데모의 볼거리 하나: 반올림 때문에 22k 세션과 23K 세션이 같은 표시가 될 수 있습니다. 힐끔 읽는 라인에는 충분한 수준입니다.
21373/200000이 21k/200k로. /context에서도 같은 총합을 확인했습니다.영상 4:30 지점 보기 - 7
세션을 둘 띄워 각 라인이 자기 세션만 추적하는지 확인한다
터미널을 둘 열고 각각 Claude Code를 실행하세요. 상태 라인마다 자기 세션만 보고합니다. 왼쪽은 11%·22k/200k, 오른쪽은 9%·18k/200k이며, 각 창의 /context도 해당 라인과 일치합니다. 바로 이 때문에 브랜치와 프로젝트를 라인에 넣는 것입니다. 탭을 여러 개 띄워도 어느 세션이 무거운지 한눈에 보이니, 여기저기 /context를 칠 필요가 없습니다.
두 개의 Claude Code 세션, 상태 라인마다 자기 컨텍스트를 보고합니다.영상 5:15 지점 보기
스크립트를 가져와 매일 읽는다
- 8
직접 쓰기는 건너뛴다: npx로 커뮤니티 스크립트 설치
스크립트를 직접 쓸 필요는 없습니다. ContextBricks는 npx contextbricks 한 줄로 설치되어 ~/.claude/statusline.sh를 쓰고 settings.json을 백업을 먼저 저장한 뒤 갱신합니다. 기능 목록: 모델 이름, git repo:branch [commit] 메시지, 커밋되지 않은 변경·앞서감·뒤처짐 표시, 이번 세션에서 바뀐 줄 수, 벽돌 시각화로 보여 주는 실시간 컨텍스트 사용량, 토큰 내역. 제거는 ./uninstall.sh이며, 출력된 백업 경로로 이전 스크립트를 복원할 수 있습니다.
npx contextbricks: 스크립트 설치, settings.json 갱신, 기능 목록까지 한 번에.영상 0:20 지점 보기 - 9
에이전트가 작업하는 동안 미터를 읽는다
커스텀 라인이 빛을 발하는 때는 세션 한가운데입니다. 데모에서는 [Sonnet 4.5], +2381/-0줄에 이어 18%(36k/200k tokens) 컨텍스트 바와 sys:4k tools:16k mcp:2k mem:10k msg:4k 내역, 남은 163k가 표시됩니다. 제작자는 토큰 수를 세션 전사(transcript)를 파싱해 계산합니다. API 숫자가 아닌 추정치지만, compact와 clear 시점을 판단하기엔 충분히 정확하다고 말합니다.
기획 문서를 작성하는 동안 36k/200k tokens와 카테고리별 내역이 한눈에 들어옵니다.영상 5:00 지점 보기 - 10
신호를 보고 마무리한다: 커밋이 올라오고 주간 한도가 다가온다
git commit 이후 라인에는 브랜치와 커밋이 얹힙니다: contextbricks:master [ffe9523] Add comprehensive planning documentation. 오른쪽 끝에는 두 번째 신호 — Approaching weekly limit — 이 붙습니다. 컨텍스트 백분율, 커밋 마커, 한도 경고 세 가지가 모이면, 자동 압축이 작업 한가운데 끼어들게 두지 말고 스스로 /compact나 /clear를 실행할 타이밍을 판단할 수 있습니다.
브랜치와 커밋이 라인에 나타나고, 오른쪽엔 주간 한도 경고가 앉습니다.영상 6:02 지점 보기
스크립트가 읽을 수 있는 것 — 필드별로
라인의 모든 것은 스크립트가 stdin에서 받는 하나의 JSON 객체에서 나옵니다. 세션 시작 시 한 번, 그다음에는 매 업데이트마다 — 새 어시스턴트 메시지, 완료된 /compact, 권한 모드 변경 — 도착합니다. 공식 필드 중 한 줄의 값이 있는 것들입니다.
- 1모델과 effort — 라벨에는 model.display_name(Sonnet 4.5, Opus 4.5), 추론 단계를 함께 보여 주려면 effort.level을 더합니다.
- 2위치 — workspace.current_dir이 현재 디렉터리의 공식 권장 필드이고, workspace.project_dir는 시작 디렉터리, workspace.repo.owner/.name은 origin 리모트에서 파싱한 리포지토리입니다. 브랜치는 git branch --show-current와 짝지으면 됩니다.
- 3컨텍스트 — context_window.used_percentage와 remaining_percentage는 미리 계산되어 있고, context_window.current_usage는 입력·출력·캐시 생성·캐시 읽기를 나눠 보여 주며, context_window.context_window_size는 기본 200000(확장 시 1000000)입니다.
- 4돈과 시간 — cost.total_cost_usd는 세션 비용(/clear로 초기화), cost.total_duration_ms와 total_api_duration_ms는 실제 시간과 API 대기 시간을 구분해 주며, cost.total_lines_added와 total_lines_removed도 있습니다.
- 5한도 — rate_limits.five_hour와 rate_limits.seven_day는 Pro·Max 플랜에서 used_percentage와 resets_at을 노출합니다. 문서에는 prompt_cache 객체도 있어 hit_ratio와 expires_at으로 캐시 인지형 라인을 만들 수 있습니다.
공식 문서의 실무 포인트: echo나 print 한 번이 한 줄이므로, 다중 줄 레이아웃은 print를 더 붙이는 일입니다. ANSI 코드가 색을 담당하고, 터미널 폭은 COLUMNS와 LINES 환경 변수에서 읽습니다. 그리고 조건부로 사라지는 필드에는 .context_window.used_percentage // 0 같은 jq 폴백을 반드시 붙여 세션 시작 직후 몇 초에도 라인이 무너지지 않게 하세요.
라인이 말을 안 들을 때
깨진 상태 라인의 원인은 대부분 다섯 가지로 수렴합니다. 그리고 수정은 프롬프트 한 번이나 명령어 하나면 충분합니다.
- 1빈 줄이나 대시(--) — 첫 API 응답 전의 null 필드입니다. 공식 문서는 jq 폴백(// 0, // empty)을 권하고, workspace trust 확인을 수락하지 않으면 라인은 계속 비어 있습니다.
- 2스크립트가 실행되지 않음 — chmod +x로 실행 권한을 주고, stderr가 아니라 stdout에 출력하며, claude --debug로 스크립트 오류를 확인하세요.
- 3숫자가 이상함 — ContextBricks 제작자에 따르면 Claude가 토큰 계산을 연달아 몇 번이나 틀렸다고 합니다. 에이전트에게 원본 JSON을 디버그 파일로 덤프하게 하고 그 기준으로 스크립트를 다시 쓰게 한 뒤, /context와 비교하세요.
- 4Windows 셸 혼란 — Git Bash가 설치돼 있으면 Git Bash, 아니면 PowerShell을 씁니다. 경로는 슬래시로 쓰고 스크립트는 전용 .ps1 파일에 두세요.
- 5한 줄에 너무 많음 — 다중 줄을 요청하거나(경로·리포지토리 정보를 두 번째 줄로), 줄이는 방법도 있습니다. 토큰은 K 단위, 구분자 색은 하나, 앞으로도 안 볼 필드는 과감히 뺍니다.
완전히 빠지고 싶다면: /statusline delete(또는 /statusline clear)로 기능을 제거하고, 커뮤니티 설치 스크립트는 자체 제거기를 쓰세요. ContextBricks는 uninstall.sh를 함께 배포하며, 이전 스크립트로 복원할 백업 경로를 출력해 줍니다.