ccstatusline
무엇인가
ccstatusline은 Claude Code CLI의 statusLine 슬롯에 등록되어 터미널 하단 한 줄을 대체하는 포매터다. Claude Code가 렌더마다 넘기는 세션 JSON을 입력으로 받아, 활성화된 위젯을 순서대로 평가해 하나의 문자열로 출력한다. 터미널 상태줄 렌더링 계층에 속하며 코드 생성이나 에이전트 실행 자체에는 관여하지 않는다.
어떻게 동작하나
위젯은 각자 독립적으로 값을 계산한다. Git Branch·Git Root Dir·Current Working Dir은 저장소 상태를, Block Timer·Block Reset Timer·Weekly Reset Timer는 진행 막대를, Cache Timer는 프롬프트 캐시 TTL과 HOT 상태를, Claude Status는 서비스 심각도와 48시간 인시던트 이력을, Git CI Status는 현재 브랜치 PR의 검사 결과를 담당한다. 토큰·세션 길이·속도·컴팩션 지표는 트랜스크립트 JSONL을 단일 스캔으로 스트리밍해 계산하고, 활성 블록이 없을 때의 결과는 잠시 캐시한다. Git PR·CI 값은 버전이 붙은 디스크 캐시에서 먼저 렌더링하고 백그라운드에서 갱신한다. 설정은 TUI 편집기에서 다루며 JSON으로 내보내고 다시 가져올 수 있다.
무엇과 다른가
Claude Code 기본 상태줄은 표시 항목이 고정되어 있다. ccstatusline은 이를 위젯 파이프라인으로 바꿔 항목별 표시 여부, 숫자 포맷, 패딩, dim 스타일을 개별로 지정한다. 직접 작성한 셸 스크립트와 달리 powerline 구분자와 flex 모드, 한쪽 패딩, 위젯별 폭 제한을 지원하고, 숨겨진 위젯을 건너뛰어 구분자 색을 실제로 보이는 앞 위젯에서 상속한다.
어떻게 쓰나
설치 후 Claude Code의 settings.json statusLine 항목이 이 명령을 가리키게 하고, TUI 편집기에서 줄과 위젯을 배치한다. 편집기에서 x 키를 누르면 해당 위젯과 그 줄의 나머지가 자연 폭을 유지하고 앞쪽 powerline 열만 자동 정렬된다. 설정은 JSON으로 내보내 검증·미리보기한 뒤 전체를 교체하거나 일부 필드만 병합할 수 있고, 병합 시 로컬 설치 메타데이터는 보존되며 결과는 저장 전까지 적용되지 않는다.
전제와 한계
Claude Code CLI가 전제이며 statusLine 훅을 지원하는 버전이 필요하다. 사용량 위젯은 Claude 사용량 API 응답에 의존하므로 limits[] 또는 weekly_scoped 항목이 없는 응답에서는 값을 채우지 못한다. settings.json이 유효하지 않으면 파일을 건드리지 않고 기본값을 메모리에서 렌더링하며 상태줄에 경고를 표시한다. 컨텍스트 윈도 크기를 Claude Code와 모델 이름이 알려주지 않을 때는 CCSTATUSLINE_CONTEXT_SIZE_FALLBACK 환경 변수로 대체값을 지정한다. Windows를 지원하지만 영구 Git 캐시 쓰기가 실패하면 임시 파일을 정리하고 고정된 대체 이름을 재사용해 파일 잠금 누수를 막는다.