claudekit / guides / ccstatusline-guide
[ Guide · Practical · 10분 ]

ccstatusline로 터미널 업그레이드하기

published · updated

ccstatusline로 Claude Code 터미널 상태바를 Powerline 스타일로 꾸미고, 모델, 토큰 사용량, Git 정보를 한 줄에 표시하는 방법을 정리합니다.

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)와 가져오기를 사용합니다.

함께 쓰면 좋은 도구

  • ccusage — 일 단위, 월 단위 토큰 사용량과 비용을 상세 분석. ccstatusline의 실시간 표시와 보완 관계.
  • 직접 스크립트를 만들고 싶다면 Claude Code의 /statusline 명령에 원하는 내용을 자연어로 설명하면 스크립트를 생성해 줍니다(공식 문서).
§ 8

자주 묻는 질문

자주 묻는 질문
§ 8.1
ccstatusline은 무엇을 해주나요?
Claude Code의 터미널 상태바를 Powerline 스타일로 꾸미고, 사용 중인 모델, 토큰 사용량, Git 브랜치 등 작업에 필요한 정보를 한 줄에 표시하는 독립 CLI 도구입니다.
§ 8.2
어떻게 적용하나요?
`npx -y ccstatusline@latest`(또는 `bunx -y ccstatusline@latest`)로 인터랙티브 TUI를 실행하고, 위젯과 테마를 고른 뒤 Claude Code 설정에 설치합니다. 기본 설치 옵션인 Pinned global install을 고르면 실행 중인 버전이 전역 설치되고, 이후에는 `ccstatusline` 명령으로 바로 TUI를 엽니다.
§ 8.3
Claude Code 설정 파일을 직접 수정해야 하나요?
아니요. ccstatusline TUI가 `~/.claude/settings.json`의 `statusLine` 필드를 자동으로 기록합니다. ccstatusline 자체 설정은 `~/.config/ccstatusline/settings.json`에 따로 저장됩니다.
§ 8.4
토큰 사용량 위젯은 어떤 정보를 쓰나요?
Block Usage, Weekly Usage 같은 사용량 위젯은 Anthropic API에서 사용량을 직접 조회하고, Block Timer는 대화 기록(transcript)의 타임스탬프로 5시간 블록 경과 시간을 계산합니다. 일 단위, 월 단위 비용 분석이 필요하면 ccusage 같은 별도 도구를 함께 쓰는 것을 권장합니다.
§ 8.5
테마와 색상은 어떻게 조정하나요?
ccstatusline은 내장된 Powerline 테마를 제공하며, TUI의 색상 설정에서 위젯별로 색을 개별 조정할 수 있습니다.