sirmalloc이 만든 커뮤니티 오픈소스 프로젝트(
sirmalloc/ccstatusline). 이 가이드는 v2.2.32 기준입니다.
왜 상태바를 바꾸는가
Claude Code의 기본 상태바는 필수 정보만 표시합니다. 장시간 작업에서는 토큰 사용량, 현재 모델, Git 브랜치 같은 정보를 한눈에 파악할 수 있어야 컨텍스트 전환 비용이 줄어듭니다.
ccstatusline은 이런 위젯을 인터랙티브하게 구성할 수 있는 독립 CLI 도구입니다.
설치 및 첫 설정
npx -y ccstatusline@latest
# 또는 Bun 사용 시
bunx -y ccstatusline@latest
실행하면 인터랙티브 TUI가 열립니다. 화살표 키로 항목을 이동하고 Enter로 선택, ESC로 빠져나옵니다.
TUI에서 Claude Code 설정에 설치하면 ccstatusline이 ~/.claude/settings.json의 statusLine 필드를 자동으로 기록합니다. Claude Code는 설정 파일 변경을 자동으로 다시 읽고 상태바 명령을 바로 실행하므로, 세션을 다시 시작하지 않아도 새 상태바가 나타납니다.
설치 방식은 두 가지입니다.
- Pinned global install (기본값) — 지금 실행 중인 버전을 npm 또는 Bun으로 전역 설치하고,
statusLine에"command": "ccstatusline"을 기록합니다. 버전이 고정되고, 상태바를 그릴 때마다 패키지 버전을 확인하는 과정이 없어 실행이 빠릅니다. 이후에는ccstatusline만 입력하면 TUI가 열립니다. - 자동 업데이트 방식 —
statusLine에npx -y ccstatusline@latest를 기록해 항상 최신 버전을 따라갑니다.
위젯 선택
상태바에 표시할 위젯을 선택할 수 있습니다. 위젯 선택 화면은 이름 일부만 입력해도 검색됩니다.
- Model — 현재 사용 중인 Claude 모델 (Opus 5.5, Sonnet 5.5 등)
- 사용량 — Block Usage(5시간 블록 사용률), Weekly Usage(주간 사용률), 모델별 주간 사용량(Sonnet, Opus, Fable), Block Timer(현재 5시간 블록 경과 시간)
- Git Branch — 현재 작업 중인 브랜치 이름. Git PR, Git CI Status 등 Git 위젯이 여럿 있습니다
- Session Clock — 현재 세션 경과 시간
- Memory Usage — 시스템 메모리 상태
- Context %, Context Length — 현재 컨텍스트 윈도우 점유율과 길이
- Claude Status, Cache Timer — Claude 서비스 장애 상태, 프롬프트 캐시 만료까지 남은 시간
작업 성격에 맞는 위젯만 켜는 것을 권장합니다. 너무 많이 켜면 상태바가 좁은 터미널에서 잘릴 수 있습니다.
테마와 색상
내장된 Powerline 스타일 테마를 화살표 키로 미리보기하며 선택합니다. 각 위젯의 색상은 TUI 색상 설정에서 개별 조정할 수 있어, 사용 중인 터미널 테마와 조화시킬 수 있습니다.
갱신 주기
Claude Code는 새 응답이 도착하거나 /compact가 끝나는 등 이벤트가 있을 때 상태바를 다시 그립니다. 시계나 사용량처럼 시간에 따라 바뀌는 위젯을 쓰면, TUI의 Configure Status Line 메뉴에서 refreshInterval을 1-60초로 지정해 일정 간격으로도 갱신할 수 있습니다(Claude Code 2.1.97 이상).
설정 변경 시점
언제든 TUI를 다시 실행하면(ccstatusline 또는 npx -y ccstatusline@latest) 기존 설정을 불러와 수정할 수 있습니다. 설정은 ~/.config/ccstatusline/settings.json에 저장되므로 파일을 직접 편집할 필요는 없습니다. 설정을 백업하거나 옮길 때는 TUI의 JSON 내보내기(Export Config)와 가져오기를 사용합니다.