Fully Custom Claude Code Status Line: A JSON-Driven 3-Line Readout of Quota, Cost, and Health

개요

Claude Code의 사용자 정의 상태 줄은 JSON 데이터를 기반으로 현재 할당량, 비용 및 자동화 상태를 3줄로 요약하여 표시하며, API 호출 없이 직접 터미널에서 정보를 확인할 수 있도록 합니다.

주요 내용

* 사용자 정의 상태 줄 설정: settings.json 파일의 statusLine.command에 쉘 스크립트 경로를 지정하여 Claude Code가 매 턴 실행하는 명령의 표준 출력을 상태 줄로 표시합니다.
* JSON 기반 데이터: Claude Code는 모델 이름, 할당량 사용률, 세션 비용, 컨텍스트 창 사용률 등의 정보를 JSON 형식으로 표준 입력(stdin)에 전달합니다.
* 쉘 스크립트 구현: statusline.sh 스크립트는 표준 입력을 읽어 JSON 데이터를 파싱하고, 캐싱하여 재사용하며, 할당량 및 비용 정보를 사용자 친화적인 형식으로 구성합니다.
* 색상 코딩: 할당량 및 컨텍스트 사용률을 50%와 80% 임계값을 기준으로 녹색, 노란색, 빨간색으로 표시하여 현재 상태를 직관적으로 파악할 수 있습니다.
* 비동기 처리 및 캐싱: ccusage 및 automation-health.sh와 같이 시간이 오래 걸리는 작업은 2분 또는 5분 캐싱과 백그라운드 실행을 통해 상태 줄 표시가 지연되지 않도록 합니다.
* 건강 상태 표시: 자동화 작업의 성공/실패 여부를 나타내는 건강 상태 아이콘(🟢, 🟡, 🔴, ⚫)을 표시하고, 업데이트 중에는 점(·)으로 표시합니다.
* 프로젝트 건강 보고서: project-health-latest.md 파일에서 경고 수를 읽어와 프로젝트의 건강 상태를 시각화합니다.
* 구성 요소 분리: claude-limits-segment.sh와 같이 특정 정보(예: 할당량)만 반환하는 스크립트를 분리하여 다른 자동화 도구에서 재사용할 수 있도록 합니다.
* 주의사항: rate_limits 필드가 첫 API 응답 전에 존재하지 않는 경우, // empty를 사용하여 빈 문자열 대신 null로 처리해야 하며, macOS의 date -r와 Linux의 date -d 문법 차이를 고려해야 합니다.

시사점

이 구현은 API 호출 없이 Claude Code의 상태 줄을 통해 중요한 사용량 및 비용 정보를 실시간으로 파악할 수 있게 하여, 예상치 못한 할당량 초과나 자동화 작업 실패를 조기에 감지하고 대응하는 데 유용합니다.