본문으로 건너뛰기
블로그로
블로그튜토리얼

Claude Code statusline 설정: 클로드 코드 상태 줄에 모델·컨텍스트·사용량 띄우기

클로드 코드(Claude Code) 상태 줄은 입력창 아래에 모델, 대화가 찬 정도, 5시간·7일 사용량을 늘 띄워 줍니다. /statusline에 말로 시키는 가장 쉬운 방법, settings.json 구조, 표시 예시 3가지, 안 보일 때와 끄는 법을 실제 화면으로 정리했습니다.

공식 출처 3건 · 본문 하단 확인 섹션과 동일

Claude Code statusline 설정: 클로드 코드 상태 줄에 모델·컨텍스트·사용량 띄우기 표지 이미지

클로드 코드(Claude Code) 상태 줄(statusline)은 입력창 아래에 늘 떠 있는 한 줄입니다. 가장 쉬운 설정 방법은 입력창에 /statusline을 치고 보고 싶은 것을 말로 적는 거예요. 예를 들어 /statusline 모델 이름이랑 컨텍스트 사용량 %를 보여 줘라고 하면 클로드 코드가 스크립트를 만들고 설정 파일까지 고칩니다.

클로드 코드를 쓰다 보면 "지금 어떤 모델이지?", "대화가 얼마나 찼지?", "이번 주 한도는 얼마나 남았지?"를 자주 확인하게 됩니다. 매번 /usage나 /context를 치지 않고 화면 아래에서 바로 보는 방법이 상태 줄이에요. 이 글은 말로 시켜서 설정하는 법을 먼저 보여 드리고, 직접 고치고 싶은 분을 위해 설정 파일 구조와 표시할 수 있는 정보를 정리했습니다. 내용은 2026년 11월 22일에 Claude Code 공식 문서로 확인했어요.

상태 줄이 바꾸는 화면

설정하기 전과 후를 같은 폴더, 같은 질문으로 찍었습니다.

상태 줄을 설정하기 전의 클로드 코드 화면. 입력창 아래에는 auto mode on 안내만 보인다 설정 전입니다. 입력창 아래에는 권한 모드 안내만 있어요(2026년 11월 22일, 강의용 데모 계정 화면).

상태 줄을 설정한 뒤의 클로드 코드 화면. 입력창 아래에 [Fable 5.2], 컨텍스트 막대와 4% context, 7d: 12%가 표시된다 설정 후입니다. 모델 이름, 대화가 찬 정도(컨텍스트 %), 7일 한도 사용률이 한 줄로 보여요.

위 화면의 숫자는 데모 계정의 실제 값이라 예시로만 보시면 됩니다. 5시간 한도(5h)도 보이게 짰는데 화면에는 7일 한도만 나왔어요. 이 데모 계정은 Ultra 플랜이고, 클로드 사용량 확인 글에 정리한 대로 인증된 Ultra 계정에는 5시간 한도가 없습니다. 값이 없는 칸은 스크립트가 빼고 보여 주도록 만들었어요.

상태 줄은 기본 안내 줄을 없애지 않고 그 위에 한 줄을 더 씁니다. 대신 ? for shortcuts 같은 일부 안내 문구는 상태 줄을 켜면 더 이상 나오지 않아요. 상태 줄은 내 컴퓨터에서 도는 스크립트라 API 토큰을 쓰지 않습니다. 도움말 메뉴나 권한 확인 창이 떠 있는 동안에는 잠깐 숨어요.

가장 쉬운 방법: /statusline에 말로 시키기

클로드 코드 입력창에 /statusline 다음에 원하는 내용을 한국어로 적으면 됩니다. 명령어 문서에 따르면 아무것도 적지 않고 /statusline만 치면 지금 쓰는 터미널 프롬프트 모양을 보고 알아서 설정해요.

예를 들어서 이렇게 시킬 수 있습니다.

/statusline 모델 이름, 컨텍스트 사용량 %를 막대로, 5시간·7일 사용량 %를 보여 줘
/statusline 지금 폴더 이름과 git 브랜치, 이번 세션 예상 비용을 보여 줘

클로드 코드는 ~/.claude/ 폴더에 스크립트 파일을 만들고 설정 파일(~/.claude/settings.json)에 연결합니다. 중간에 파일을 고쳐도 되는지 묻는 창이 뜨면 승인하세요. 파일이 저장되면 클로드 코드가 설정을 바로 다시 불러와 스크립트를 돌리고, 입력창 아래에 상태 줄이 나타납니다.

/statusline도 클로드에게 일을 시키는 것이라 이 대화 한 번만큼은 사용량이 들어요. 한번 만들어진 뒤에 상태 줄이 화면을 새로 그릴 때는 토큰을 쓰지 않습니다.

상태 줄에 띄울 수 있는 정보

클로드 코드는 상태 줄 스크립트를 부를 때마다 지금 세션 정보를 JSON으로 넘겨줍니다. 상태 줄 문서의 필드 가운데 처음 쓰는 분이 자주 찾을 만한 것만 골랐어요.

  • 지금 모델: model.display_name
  • 대화가 찬 정도(%): context_window.used_percentage
  • 5시간 한도(%): rate_limits.five_hour.used_percentage
  • 7일 한도(%): rate_limits.seven_day.used_percentage
  • 한도가 풀리는 시각(초 단위 Unix 시간): rate_limits.*.resets_at
  • 이번 세션 예상 비용: cost.total_cost_usd
  • 지금 폴더(전체 경로): workspace.current_dir
  • effort 단계(지원하는 모델에서만): effort.level

몇 가지는 조건이 붙습니다.

  • 한도(rate_limits): claude.ai Pro·Max·Ultra 구독자에게 오고, 세션에서 첫 응답이 온 뒤부터 들어옵니다. 5시간·7일 칸이 따로따로 빠질 수 있고, 리셋 시각이 지나면 그 칸은 빠져요. 공식 문서에는 이 값을 받는 경우로 구독자와, 사용 한도를 정해 둔 Claude apps 게이트웨이를 거치는 경우만 적혀 있습니다.

컨텍스트와 비용 값도 알아 둘 점이 있어요.

  • 컨텍스트 %: 입력 토큰만으로 계산한 값이고, 세션 초반에는 비어 있을 수 있습니다. /context는 마지막 응답 뒤에 추가된 메시지까지 어림해서 더하기 때문에, 다음 답이 오기 전까지는 /context 쪽 숫자가 더 높게 나올 수 있어요.
  • 비용: 정가 기준 추정치라 실제 청구액과 다를 수 있고, /clear로 새 세션을 시작하면 0으로 돌아갑니다. 구독자에게는 청구액이 아니라 "이 세션이 얼마짜리 작업이었나"를 보는 참고값이에요.

컨텍스트가 무엇인지, 차면 어떻게 되는지는 AI 코딩 대화가 길어져 엉뚱한 답을 할 때에 정리해 두었습니다. 상태 줄에서 컨텍스트 %가 높아지면 그 글의 순서대로 정리하고 새 대화로 넘어가면 돼요.

설정 파일은 이렇게 생겼어요

/statusline이 하는 일을 직접 하려면 두 가지가 필요합니다. 출력할 내용을 만드는 스크립트 하나와, 그 스크립트를 가리키는 설정 한 줄이에요.

설정은 ~/.claude/settings.json(내 모든 프로젝트) 또는 프로젝트 폴더의 설정 파일에 statusLine 항목으로 넣습니다.

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

type은 항상 "command"이고, command에는 스크립트 경로나 한 줄짜리 명령을 적습니다. 선택 항목도 세 가지 있어요.

  • padding: 상태 줄 앞쪽 여백(글자 수). 기본값 0.
  • refreshInterval: 몇 초마다 다시 그릴지. 시계처럼 시간이 흐르면 바뀌는 값을 띄울 때만 씁니다. 최솟값 1.
  • hideVimModeIndicator: vim 모드 표시를 스크립트가 직접 그릴 때 기본 표시를 숨김.

상태 줄은 새 답이 올 때, /compact가 끝날 때, 권한 모드를 바꿀 때 같은 순간마다 스크립트를 다시 돌립니다. 그래서 refreshInterval을 넣지 않아도 대화하는 동안에는 숫자가 계속 바뀌어요.

자주 쓰는 표시 예시 3가지

아래 스크립트는 macOS·Linux용 Bash이고, JSON을 읽는 도구 jq가 필요합니다. jq가 없으면 클로드 코드에 "jq 설치해 줘"라고 하거나, /statusline으로 만들 때 "jq 없이 만들어 줘"라고 덧붙이면 돼요. 스크립트를 ~/.claude/statusline.sh로 저장한 뒤 터미널에서 chmod +x ~/.claude/statusline.sh를 실행해 실행 권한을 주고, 위의 설정을 넣습니다. 파일 만들기가 낯설면 클로드 코드에 아래 스크립트를 붙여 넣고 "이 내용을 ~/.claude/statusline.sh로 저장하고 실행 권한도 줘"라고 시켜도 됩니다.

1. 모델과 컨텍스트 %

공식 문서의 가장 기본 예시입니다. 스크립트 파일 없이 설정 한 줄로도 됩니다.

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

화면에는 [Opus] 25% context처럼 나와요. // 0은 값이 아직 없을 때 0을 대신 쓰라는 뜻입니다.

2. 모델, 컨텍스트 막대, 5시간·7일 한도

이 글의 설정 후 화면에 쓴 스크립트입니다. 공식 문서의 컨텍스트 막대 예시와 한도 예시를 합쳤어요.

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
FILLED=$((PCT / 10)); EMPTY=$((10 - FILLED)); BAR=""
[ "$FILLED" -gt 0 ] && printf -v F "%${FILLED}s" && BAR="${F// /▓}"
[ "$EMPTY" -gt 0 ] && printf -v P "%${EMPTY}s" && BAR="${BAR}${P// /░}"
FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
WEEK=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
LIMITS=""
[ -n "$FIVE_H" ] && LIMITS="5h: $(printf '%.0f' "$FIVE_H")%"
[ -n "$WEEK" ] && LIMITS="${LIMITS:+$LIMITS }7d: $(printf '%.0f' "$WEEK")%"
echo "[$MODEL] $BAR $PCT% context${LIMITS:+ | $LIMITS}"

한도 값이 없을 때는 // empty로 빈칸을 받아서 그 부분을 통째로 뺍니다. 한도 값을 받지 못하는 환경에서도 이 스크립트는 그대로 돌고, 그때는 모델과 컨텍스트만 보여요.

3. 폴더 이름과 예상 비용

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
echo "[$MODEL] ${DIR##*/} | \$$(printf '%.2f' "$COST")"

${DIR##*/}는 전체 경로에서 마지막 폴더 이름만 남깁니다. 여러 프로젝트를 창 여러 개로 열어 둘 때 어느 창이 어느 폴더인지 구분하기 좋아요.

여러 줄로 나누고 싶으면 echo를 두 번 쓰면 되고, 색은 ANSI 색 코드(\033[32m가 초록)로 넣습니다. 공식 문서에 git 상태·여러 줄·클릭되는 링크 예시가 Bash·Python·Node.js로 다 있으니, 그 예시 주소를 /statusline에 붙여 주고 "이거 참고해서 만들어 줘"라고 시켜도 됩니다.

Windows에서 쓸 때

상태 줄 문서에 따르면 Windows에서는 Git Bash가 있으면 Git Bash로, 없으면 PowerShell로 상태 줄 명령을 돌립니다. 경로는 C:/Users/이름/.claude/statusline.ps1처럼 슬래시(/)로 적어야 해요. 역슬래시(\)로 적으면 Git Bash가 그 글자를 지워 버려서 아무 오류 없이 상태 줄이 비어 있습니다. PowerShell 스크립트는 "command": "powershell -NoProfile -File C:/Users/이름/.claude/statusline.ps1"처럼 부릅니다.

상태 줄이 안 보일 때 확인할 것

공식 문서의 문제 해결 항목을 처음 쓰는 분이 자주 만날 순서로 정리했어요.

  1. 폴더 신뢰를 안 했다: 클로드 코드를 처음 연 폴더에서 "이 폴더를 신뢰하나요?" 창을 승인하기 전까지 상태 줄은 비어 있습니다. 상태 줄도 명령을 실행하기 때문이에요. 클로드 코드를 다시 열고 승인하세요.
  2. 실행 권한이 없다: chmod +x ~/.claude/statusline.sh를 실행합니다.
  3. 스크립트가 오류로 끝난다: 스크립트가 오류로 끝나거나 아무것도 출력하지 않으면 상태 줄이 비어요. 아래처럼 가짜 데이터를 넣어 직접 돌려 보면 어디서 막히는지 보입니다.
echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ~/.claude/statusline.sh
  1. 값이 --나 빈칸으로 나온다: 첫 답이 오기 전에는 값이 비어 있을 수 있습니다. 메시지를 몇 번 보낸 뒤에도 비어 있으면 클로드 코드를 다시 시작하세요.
  2. 회사에서 막았다: 회사 관리 설정에 allowManagedHooksOnly가 켜져 있으면 내가 만든 상태 줄은 아무 안내 없이 사라집니다. 내 설정에 disableAllHooks: true가 있어도 꺼져요. 회사 계정이면 관리자에게 물어보세요.
  3. 화면이 좁다: 터미널 폭이 좁으면 같은 줄 오른쪽에 뜨는 알림 때문에 상태 줄이 잘릴 수 있습니다. 내용을 짧게 줄이세요.

그래도 모르겠으면 클로드 코드에게 "settings.json을 읽고 statusLine 명령을 직접 실행해서 왜 안 나오는지 찾아 줘"라고 하면 됩니다. 공식 문서도 이 방법을 권해요. claude --debug로 시작하면 스크립트의 오류 출력이 기록에 남습니다.

상태 줄 끄는 법

/statusline에 지우라고 말하면 됩니다. /statusline delete, /statusline clear, /statusline 상태 줄 지워 줘 모두 됩니다. 직접 하려면 ~/.claude/settings.json에서 statusLine 항목을 통째로 지우세요. 스크립트 파일은 남아 있어도 상관없어요.

남이 만든 상태 줄 도구

공식 문서 끝에 테마와 기능을 미리 넣어 둔 커뮤니티 프로젝트로 ccstatusline과 starship-claude가 소개돼 있습니다. 이 글에서는 두 도구를 설치해 보지 않았어요. 내가 보고 싶은 것이 모델·컨텍스트·한도 정도라면 /statusline에 말로 시키는 쪽이 더 간단합니다.

함께 보면 좋은 글

출처와 확인 (2026-11-22)

공식 문서

  • Customize your status line (설정 방법, /statusline, 넘겨받는 필드, 예시, Windows, 문제 해결, 끄는 법, 커뮤니티 프로젝트)
  • Commands (/statusline을 인자 없이 쓰면 터미널 프롬프트 모양으로 설정)
  • Claude Code settings (사용자 설정과 프로젝트 설정 위치)

화면 두 장은 2026년 11월 22일 Claude Code v2.1.330, 강의용 데모 계정(Ultra 플랜)으로 찍었습니다. 데모 폴더의 프로젝트 설정에만 상태 줄을 넣었어요.