Claude Code의 statusLine을 만들어 보기

Claude Code를 사용하다 보면,

• 현재 어떤 모델로 동작하고 있는지
• 컨텍스트(Context) 잔량
• /compact를 실행해야 하는 타이밍

을 확인하고 싶을 때가 있습니다.

매번 /context를 실행하면 확인할 수 있지만, 개발 중에 몇 번이고 확인하는 것은 조금 번거롭습니다.

그래서 Claude Code의 statusLine을 사용하여, 화면 하단에 현재 모델명과 컨텍스트 사용률을 상시 표시하도록 만들었습니다.

표시 예시

◆ Opus 4.6 │ ██░░░░░░ 42K/200K (21%)

컨텍스트 사용률이 80%를 초과하면 경고 아이콘도 표시합니다.

◆ Opus 4.6 │ ██████░░ 165K/200K (83%) ⚠

다음 내용을 ~/.local/bin/statusline.sh로 저장해 주세요.

#!/usr/bin/env bash
set -uo pipefail
# --- stdin의 JSON을 읽어옴 (이것이 본체) -----------------------------------
...

실행 권한을 부여합니다.

chmod +x ~/.local/bin/statusline.sh

~/.claude/settings.json에 다음과 같이 설정합니다.

{
"statusLine": {
"type": "command",
...

이렇게 하면 Claude Code 기동 시 statusLine이 표시됩니다.

여기서부터는 "왜 이렇게 되어 있는지"를 해설하겠습니다.

Claude Code의 statusLine은 화면 하단에 임의의 정보를 표시할 수 있는 메커니즘입니다.

공식 문서(Official Documentation)는 이곳입니다.

~/.claude/settings.json에 statusLine.command를 설정하면, Claude Code가 해당 명령어를 실행하고 표준 출력(Standard Output)으로 내보낸 문자열을 스테이터스 라인(Status Line)으로 표시해 줍니다.

Claude Code는 statusLine용 명령어를 실행할 때, 현재 세션 정보를 stdin의 JSON으로 전달합니다.

즉, 흐름은 다음과 같습니다.

Claude Code
↓ JSON을 stdin으로 전달
statusline.sh
...

그 JSON 안에 모델명이나 컨텍스트 사용률 등의 정보가 포함되어 있습니다.

{
"context_window": {
"used_percentage": 21.4,
...

따라서 statusLine 스크립트에서는 먼저 stdin을 읽어야 합니다.

input="$(cat)"

이것을 잊으면 모델명이나 컨텍스트 사용률을 가져올 수 없습니다.

Claude Code가 stdin으로 전달해 주는 JSON에는 context_window.used_percentage라는 값이 있습니다.

이것은 컨텍스트 윈도우(Context Window)의 사용률입니다.

이번 스크립트에서는 이 값을 "컨텍스트 사용률의 기준"으로 취급합니다.

{
"context_window": {
"used_percentage": 21.4,
...

표시하고 있는 토큰(Token) 수는 엄밀한 토큰 계산이 아니라, 다음 값으로부터 산출한 추정치입니다.

used tokens ≒ used_percentage × context_window_size

used_pct_raw="$(jq_get '.context_window.used_percentage' '0')"
ctx_size="$(jq_get '.context_window.context_window_size' '200000')"
tokens="$(awk -v p="$used_pct_raw" -v s="$ctx_size" 'BEGIN { printf "%d", (p/100)*s }')"

정확한 토큰 수를 표시하고 싶다기보다는,

"슬슬 컨텍스트가 차오르고 있구나"

라는 것을 빠르게 파악하는 것이 목적입니다.

그렇기 때문에 used_percentage를 기준으로 삼는 것이 심플하고 이해하기 쉽다고 생각했습니다.

chmod +x ~/.local/bin/statusline.sh

jq가 설치되어 있지 않다면 설치합니다.

macOS라면 Homebrew로 설치할 수 있습니다.

brew install jq

Ubuntu / Debian 계열이라면 다음과 같이 설치합니다.

sudo apt install jq

~/.claude/settings.json에 statusLine을 추가합니다.

{
"statusLine": {
"type": "command",
...

이렇게 하면 Claude Code를 실행했을 때 화면 하단에 statusLine이 표시됩니다.

Claude Code 상에서 테스트하기 전에 터미널에서 직접 확인할 수 있습니다.

echo '{"model":{"display_name":"Opus 4.6"},"context_window":{"used_percentage":25,"context_window_size":200000}}' \
| ~/.local/bin/statusline.sh

출력 예시입니다.

◆ Opus 4.6 │ ██░░░░░░ 50K/200K (25%)

80%를 초과했을 때도 확인할 수 있습니다.

echo '{"model":{"display_name":"Opus 4.6"},"context_window":{"used_percentage":83,"context_window_size":200000}}' \
| ~/.local/bin/statusline.sh

출력 예시입니다.

◆ Opus 4.6 │ ██████░░ 166K/200K (83%) ⚠

이 스크립트는 JSON 파싱(Parsing)에 jq를 사용합니다.

jq가 없는 경우, statusLine 상에 다음과 같은 메시지를 출력하고 종료합니다.

◆ statusline: jq를 찾을 수 없습니다 (brew install jq / apt install jq)

Claude Code 측을 망가뜨리지 않도록, 에러 종료가 아닌 exit 0으로 처리했습니다.

context_window.used_percentage 등의 필드는 Claude Code의 버전에 따라 이용 가능한 내용이 달라질 수 있습니다.

제대로 표시되지 않는다면 Claude Code를 업데이트한 후 확인하는 것이 좋습니다.

claude update

또한, 첫 응답 전 등 타이밍에 따라 값이 null이 될 가능성도 있기 때문에, 스크립트 측에서는 폴백(Fallback) 값을 준비해 두었습니다.

jq_get '.context_window.used_percentage' '0'

statusLine 명령어는 반복적으로 실행됩니다.

따라서 무거운 처리나 네트워크 액세스를 넣으면 체감 성능이 떨어질 수 있습니다.

이번 스크립트는 stdin의 JSON을 읽어 jq와 awk로 포맷팅(Formatting)만 하도록 만들었습니다.

statusLine에는 이 외에도 다양한 정보를 표시할 수 있습니다.

예를 들어 다음과 같은 항목을 추가해도 재미있을 것 같습니다.

• Git 브랜치
• 현재 디렉토리
• 세션 비용
• Rate Limit
• Vim 모드
• 사용 중인 모델의 전환 상태

단, statusLine은 항상 표시되므로 정보를 너무 많이 채워 넣으면 오히려 보기 불편해집니다.

개인적으로는 우선 컨텍스트 사용률만 표시하는 구성을 추천합니다.

Claude Code의 statusLine을 사용하면 작업 중에 보고 싶은 정보를 화면 하단에 항상 표시할 수 있습니다.

이번 스크립트에서는 다음과 같은 표시를 만들었습니다.

◆ Opus 4.6 │ ██░░░░░░ 42K/200K (21%)

포인트는 다음 세 가지입니다.

• Claude Code는 statusLine 명령어에 JSON을 stdin으로 전달한다.
• 컨텍스트 사용률은 context_window.used_percentage를 사용한다.
• statusLine은 항상 표시되므로 짧고 가볍게 만든다.

매번 /context를 입력하는 것이 번거로운 사람에게는 상당히 편리합니다.

제 경우에는 컨텍스트가 80%를 넘으면 "슬슬 정리할까" 하는 기준으로 삼고 있습니다.

꼭 자신만의 전용 statusline을 만들어 보세요!