최근 터미널 기반 AI 코딩 도구인 Claude Code를 사용하면서 가장 유용하다고 느낀 기능 중 하나는 바로 하단의 상태 표시줄(Status Line) 커스터마이징입니다. 단순히 도구의 상태를 보여주는 것을 넘어, 현재 작업 중인 프로젝트의 Git 브랜치, 실시간 API 사용 비용, 컨텍스트 윈도우 점유율 등을 한눈에 파악할 수 있게 해주거든요.
오늘은 셸 스크립트와 JSON 데이터를 활용해 Claude Code의 상태 표시줄을 전문가처럼 꾸미는 방법을 정리해 보겠습니다.
🛠️ 상태 표시줄 설정하기
상태 표시줄은 /statusline 명령어를 통해 자동으로 생성하거나, 설정 파일을 직접 수정하여 구성할 수 있습니다.
1. 명령어 사용 (가장 쉬운 방법)
자연어로 원하는 내용을 입력하면 Claude Code가 알아서 스크립트를 생성해줍니다.
/statusline 모델 이름과 컨텍스트 사용량을 프로그레스 바로 보여줘
2. 수동 설정 (settings.json)
더 정밀한 제어를 원한다면 ~/.claude/settings.json 파일에 직접 스크립트 경로를 지정할 수 있습니다.
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh",
"padding": 2
}
}💡 단계별 구축 가이드: 컨텍스트 모니터링 바 만들기
Claude Code는 매 상호작용마다 세션 데이터를 JSON 형태로 스크립트에 전달합니다. 이를 활용해 모델명과 컨텍스트 사용량을 출력하는 Bash 스크립트를 짜봅시다.
Step 1: 스크립트 작성
jq 라이브러리를 사용해 JSON을 파싱하면 편리합니다.
#!/bin/bash
# Claude Code로부터 입력받은 JSON 데이터 저장
input=$(cat)
# jq를 이용해 필요한 필드 추출
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
# 터미널에 출력할 텍스트 형식 지정
echo "[$MODEL] 📊 사용량: ${PCT}%"
Step 2: 실행 권한 부여
작성한 스크립트 파일(statusline.sh)에 실행 권한을 줍니다.
chmod +x ~/.claude/statusline.sh
🚀 고급 활용 예시
단순 텍스트를 넘어 더 직관적인 정보를 표시하고 싶다면 아래 패턴들을 참고해 보세요.
🎨 색상이 포함된 Git 상태 표시
ANSI 이스케이프 코드를 사용하면 스테이징된 파일은 초록색으로, 수정된 파일은 노란색으로 강조할 수 있습니다.
💰 실시간 비용 및 시간 추적
세션이 길어질수록 비용이 걱정된다면 cost.total_cost_usd 필드를 활용하세요. 현재까지 지불한 달러($) 금액과 세션 유지 시간을 실시간으로 띄울 수 있습니다.
🔗 클릭 가능한 링크 삽입
OSC 8 이스케이프 시퀀스를 지원하는 터미널(iTerm2, WezTerm 등)을 사용 중이라면, 현재 레포지토리의 GitHub 주소를 클릭 가능한 링크로 만들 수도 있습니다.
📊 사용 가능한 데이터 필드 (JSON)
스크립트에서 활용할 수 있는 주요 필드 목록입니다:
| 필드명 | 설명 |
|---|---|
model.display_name | 현재 사용 중인 모델명 (예: Claude 3.5 Sonnet) |
workspace.current_dir | 현재 작업 디렉토리 경로 |
cost.total_cost_usd | 세션 시작 후 누적된 API 비용 |
context_window.used_percentage | 컨텍스트 윈도우 사용률 (%) |
vim.mode | Vim 모드 활성화 시 현재 모드 (NORMAL/INSERT) |
⚠️ 주의사항 및 팁
- 성능 최적화: 상태 표시줄 스크립트는 매 메시지마다 실행됩니다.
git status처럼 무거운 작업은 임시 파일에 결과를 캐싱(Cache)하여 5~10초 간격으로 업데이트하는 것이 좋습니다. - 길이 조절: 터미널 너비는 한정되어 있습니다. 너무 많은 정보를 넣으면 텍스트가 잘릴 수 있으니 핵심 정보 위주로 구성하세요.
- 테스트 방법: 아래 명령어로 스크립트가 잘 작동하는지 미리 확인할 수 있습니다.
echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":25}}' | ./statusline.sh
맺음말
상태 표시줄 커스터마이징은 단순한 '꾸미기'가 아닙니다. 작업 흐름을 방해받지 않고 중요한 메트릭을 실시간으로 확인하는 생산성 환경 구축의 핵심입니다. 여러분만의 멋진 상태 표시줄을 만들어 보세요!
혹시 특정 언어(Python, Node.js)로 구현된 예제 코드가 더 필요하신가요? 도움이 필요하시면 말씀해 주세요!