Cmd. /statusline

Claude Code 하단 상태줄(status line)을 자연어 지시로 구성하거나 자동 설정하는 명령

핵심 요약

/statusline은 화면 하단 상태줄을 구성하는 명령으로, 자연어 지시를 주면 스크립트를 생성하고 settings.json의 statusLine을 자동 갱신합니다.
인수 없이 실행하면 사용자의 셸 프롬프트를 기반으로 상태줄을 자동 구성합니다.
상태줄은 로컬에서 돌아가 API 토큰을 쓰지 않으며, stdin으로 받은 JSON 세션 데이터를 스크립트가 stdout으로 내보내 표시합니다.
모델 이름·컨텍스트 사용률·비용(cost.total_cost_usd)·git 상태·rate limit 등을 표시할 수 있습니다.
Settings 창을 여는 /status와 다른 명령이며, 느린 git status는 캐싱하고 출력은 짧게 유지하세요.

명령어 원본 선언

/statusline [원하는 표시 내용 설명]

공식 설명 요약

/statusline은 Claude Code의 상태줄(status line) 을 구성하는 명령입니다. 상태줄은 화면 하단에 놓이는 커스터마이즈 가능한 막대입니다. 사용자가 지정한 셸 스크립트를 실행해 컨텍스트 사용량, 비용, git 상태 같은 정보를 항상 띄워 둡니다.

공식 설명(원문): "Configure Claude Code's status line. Describe what you want, or run without arguments to auto-configure from your shell prompt."

동작 방식은 두 가지입니다.

자연어 지시 전달: /statusline 뒤에 원하는 표시 내용을 자연어로 설명하면, Claude Code가 ~/.claude/에 스크립트 파일을 만들고 settings.json의 statusLine 필드를 자동으로 업데이트합니다.
인수 없이 실행: 인수 없이 /statusline만 실행하면 사용자의 셸 프롬프트(shell prompt)를 보고 상태줄을 자동 구성합니다.

상태줄은 로컬에서 돌아가며 API 토큰을 쓰지 않습니다. Claude Code가 표준 입력(stdin)으로 JSON 세션 데이터를 스크립트에 넘기면, 스크립트가 표준 출력(stdout)으로 내보낸 텍스트가 그대로 표시됩니다.

최소 지원 버전

공식 명령어 레퍼런스 및 전용 문서(/en/statusline)에 별도의 최소 버전 표기는 없습니다. 다만 개별 기능에는 도입 버전이 명시되어 있습니다.
- context_window.total_input_tokens / total_output_tokens: v2.1.132부터 컨텍스트 창에 남아 있는 토큰 수를 반환(이전에는 세션 누적 합계).
- COLUMNS / LINES 환경변수로 터미널 크기 읽기: v2.1.153부터 지원.

사용법

# 자연어로 원하는 표시 내용 설명 → 스크립트 자동 생성 + settings.json 자동 갱신
/statusline show model name and context percentage with a progress bar

# 인수 없이 실행 → 셸 프롬프트 기반 자동 구성
/statusline

# 제거/초기화 요청
/statusline delete
/statusline clear
/statusline remove it

settings.json 수동 구성

/statusline이 자동 생성하는 설정은 다음 형태입니다. ~/.claude/settings.json(사용자 설정) 또는 프로젝트 설정에 직접 작성할 수도 있습니다.

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

type: "command"으로 설정.
command: 스크립트 경로 또는 인라인 셸 명령. 셸에서 실행되므로 jq 등을 이용한 인라인 명령도 사용 가능.
padding(선택): 상태줄 내용에 추가할 수평 여백(문자 단위). 기본값 0.
refreshInterval(선택): N초마다 명령을 다시 실행(이벤트 기반 갱신에 더해). 최소값 1. 시계 등 시간 기반 데이터나 idle 상태에서 git이 바뀌는 경우 유용.
hideVimModeIndicator(선택): 스크립트가 직접 vim.mode를 렌더링할 때 내장 -- INSERT -- 표시를 숨김.

갱신 시점

스크립트는 새 어시스턴트 메시지 이후, /compact 완료 후, 권한 모드 변경 시, vim 모드 토글 시 실행됩니다. 갱신은 300ms 디바운스되며, 실행 중 새 갱신이 트리거되면 진행 중인 실행은 취소됩니다.

좋은 사용 예

모델 이름과 컨텍스트 사용률을 진행 막대로 표시
git 브랜치/스테이징 상태를 색상으로 구분 표시
세션 비용(cost.total_cost_usd)과 소요 시간 추적
Claude.ai 구독자의 rate limit 사용량 표시(아래 활용 사례 참고)

비슷한 명령어 추천

명령어	차이점	언제 선택
`/statusline`	하단 상태줄 스크립트 구성/자동 생성	상시 표시 정보를 커스터마이즈
`/status`	Settings(Status 탭) 열기 — 버전·모델·계정·연결 확인	즉시 상태 정보 조회
`/context`	현재 컨텍스트 창 사용 내역 시각화	컨텍스트 점유 분석
`/config`	전역 설정 조정	일반 설정 관리

활용 사례

운영 가시성 표준화: 팀 공통 상태줄 스크립트를 배포해 모델·디렉터리·git 상태를 일관되게 노출.
rate limit 모니터링: rate_limits.five_hour / rate_limits.seven_day 객체로 5시간/주간 윈도우의 used_percentage(0~100)와 resets_at(Unix epoch 초)을 상태줄에 표시. 이 객체는 Claude.ai 구독자(Pro/Max)에 한해 세션의 첫 API 응답 이후 나타나며, 각 윈도우는 독립적으로 부재할 수 있습니다. jq -r '.rate_limits.five_hour.used_percentage // empty'처럼 부재를 안전하게 처리하세요.
다중 행 상태줄: 각 echo/print가 한 행으로 나오므로 git 정보와 컨텍스트 막대를 여러 줄로 나눠 구성할 수 있습니다.
서브에이전트 상태줄: subagentStatusLine 설정으로 에이전트 패널의 각 서브에이전트 행 본문을 커스터마이즈.

주요 stdin JSON 필드

필드	설명
`model.id`, `model.display_name`	현재 모델 식별자 및 표시 이름
`workspace.current_dir`, `cwd`	현재 작업 디렉터리(동일 값, `current_dir` 권장)
`workspace.project_dir`	Claude Code 실행 디렉터리
`cost.total_cost_usd`	클라이언트 측 추정 세션 비용(USD)
`cost.total_duration_ms`	세션 시작 이후 경과 시간(ms)
`context_window.used_percentage`	사전 계산된 컨텍스트 창 사용률
`context_window.context_window_size`	최대 컨텍스트 창 크기(기본 200000, 확장 시 1000000)
`rate_limits.five_hour.used_percentage`	5시간 rate limit 소비율(0~100)
`rate_limits.*.resets_at`	rate limit 윈도우가 리셋되는 Unix epoch 초
`effort.level`	현재 추론 강도(`low`/`medium`/`high`/`xhigh`/`max`/`ultra`)
`session_id`, `session_name`	세션 식별자 및 사용자 지정 이름
`vim.mode`	현재 vim 모드(vim 모드 활성 시)
`pr.number`, `pr.url`, `pr.review_state`	현재 브랜치의 열린 PR 정보

주의사항

상태줄은 /status와 다릅니다. /status는 Settings 창(Status 탭)을 열어 버전·모델·계정·연결 정보를 조회하는 명령이고, /statusline은 하단 상태줄을 직접 구성하는 명령입니다.
출력은 짧게 유지하세요. 상태바 폭이 제한적이라 긴 출력은 잘리거나 어색하게 줄바꿈됩니다.
스크립트는 활성 세션에서 자주 실행되므로 git status 같은 느린 명령은 캐싱(예: /tmp/statusline-git-cache-<session_id>)을 권장합니다.
스크립트는 반드시 stdout으로 출력해야 하며(stderr 아님), 실행 권한이 필요합니다(chmod +x ~/.claude/statusline.sh).
Claude Code가 스크립트 출력을 캡처하므로 tput cols 등으로 터미널 폭을 읽을 수 없습니다. v2.1.153부터는 COLUMNS/LINES 환경변수를 사용하세요.
제거하려면 /statusline에 삭제를 요청하거나 settings.json의 statusLine 필드를 수동으로 지웁니다.

출처

Commands reference: https://code.claude.com/docs/en/commands
Customize your status line: https://code.claude.com/docs/en/statusline

핵심 요약

/statusline은 화면 하단 상태줄을 구성하는 명령으로, 자연어 지시를 주면 스크립트를 생성하고 settings.json의 statusLine을 자동 갱신합니다.
인수 없이 실행하면 사용자의 셸 프롬프트를 기반으로 상태줄을 자동 구성합니다.
상태줄은 로컬에서 돌아가 API 토큰을 쓰지 않으며, stdin으로 받은 JSON 세션 데이터를 스크립트가 stdout으로 내보내 표시합니다.
모델 이름·컨텍스트 사용률·비용(cost.total_cost_usd)·git 상태·rate limit 등을 표시할 수 있습니다.
Settings 창을 여는 /status와 다른 명령이며, 느린 git status는 캐싱하고 출력은 짧게 유지하세요.

명령어 원본 선언

/statusline [원하는 표시 내용 설명]

공식 설명 요약

공식 설명(원문): "Configure Claude Code's status line. Describe what you want, or run without arguments to auto-configure from your shell prompt."

동작 방식은 두 가지입니다.

자연어 지시 전달: /statusline 뒤에 원하는 표시 내용을 자연어로 설명하면, Claude Code가 ~/.claude/에 스크립트 파일을 만들고 settings.json의 statusLine 필드를 자동으로 업데이트합니다.
인수 없이 실행: 인수 없이 /statusline만 실행하면 사용자의 셸 프롬프트(shell prompt)를 보고 상태줄을 자동 구성합니다.

최소 지원 버전

공식 명령어 레퍼런스 및 전용 문서(/en/statusline)에 별도의 최소 버전 표기는 없습니다. 다만 개별 기능에는 도입 버전이 명시되어 있습니다.
- context_window.total_input_tokens / total_output_tokens: v2.1.132부터 컨텍스트 창에 남아 있는 토큰 수를 반환(이전에는 세션 누적 합계).
- COLUMNS / LINES 환경변수로 터미널 크기 읽기: v2.1.153부터 지원.

사용법

# 자연어로 원하는 표시 내용 설명 → 스크립트 자동 생성 + settings.json 자동 갱신
/statusline show model name and context percentage with a progress bar

# 인수 없이 실행 → 셸 프롬프트 기반 자동 구성
/statusline

# 제거/초기화 요청
/statusline delete
/statusline clear
/statusline remove it

settings.json 수동 구성

/statusline이 자동 생성하는 설정은 다음 형태입니다. ~/.claude/settings.json(사용자 설정) 또는 프로젝트 설정에 직접 작성할 수도 있습니다.

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

type: "command"으로 설정.
command: 스크립트 경로 또는 인라인 셸 명령. 셸에서 실행되므로 jq 등을 이용한 인라인 명령도 사용 가능.
padding(선택): 상태줄 내용에 추가할 수평 여백(문자 단위). 기본값 0.
refreshInterval(선택): N초마다 명령을 다시 실행(이벤트 기반 갱신에 더해). 최소값 1. 시계 등 시간 기반 데이터나 idle 상태에서 git이 바뀌는 경우 유용.
hideVimModeIndicator(선택): 스크립트가 직접 vim.mode를 렌더링할 때 내장 -- INSERT -- 표시를 숨김.

갱신 시점

좋은 사용 예

모델 이름과 컨텍스트 사용률을 진행 막대로 표시
git 브랜치/스테이징 상태를 색상으로 구분 표시
세션 비용(cost.total_cost_usd)과 소요 시간 추적
Claude.ai 구독자의 rate limit 사용량 표시(아래 활용 사례 참고)

비슷한 명령어 추천

명령어	차이점	언제 선택
`/statusline`	하단 상태줄 스크립트 구성/자동 생성	상시 표시 정보를 커스터마이즈
`/status`	Settings(Status 탭) 열기 — 버전·모델·계정·연결 확인	즉시 상태 정보 조회
`/context`	현재 컨텍스트 창 사용 내역 시각화	컨텍스트 점유 분석
`/config`	전역 설정 조정	일반 설정 관리

활용 사례

운영 가시성 표준화: 팀 공통 상태줄 스크립트를 배포해 모델·디렉터리·git 상태를 일관되게 노출.
rate limit 모니터링: rate_limits.five_hour / rate_limits.seven_day 객체로 5시간/주간 윈도우의 used_percentage(0~100)와 resets_at(Unix epoch 초)을 상태줄에 표시. 이 객체는 Claude.ai 구독자(Pro/Max)에 한해 세션의 첫 API 응답 이후 나타나며, 각 윈도우는 독립적으로 부재할 수 있습니다. jq -r '.rate_limits.five_hour.used_percentage // empty'처럼 부재를 안전하게 처리하세요.
다중 행 상태줄: 각 echo/print가 한 행으로 나오므로 git 정보와 컨텍스트 막대를 여러 줄로 나눠 구성할 수 있습니다.
서브에이전트 상태줄: subagentStatusLine 설정으로 에이전트 패널의 각 서브에이전트 행 본문을 커스터마이즈.

주요 stdin JSON 필드

필드	설명
`model.id`, `model.display_name`	현재 모델 식별자 및 표시 이름
`workspace.current_dir`, `cwd`	현재 작업 디렉터리(동일 값, `current_dir` 권장)
`workspace.project_dir`	Claude Code 실행 디렉터리
`cost.total_cost_usd`	클라이언트 측 추정 세션 비용(USD)
`cost.total_duration_ms`	세션 시작 이후 경과 시간(ms)
`context_window.used_percentage`	사전 계산된 컨텍스트 창 사용률
`context_window.context_window_size`	최대 컨텍스트 창 크기(기본 200000, 확장 시 1000000)
`rate_limits.five_hour.used_percentage`	5시간 rate limit 소비율(0~100)
`rate_limits.*.resets_at`	rate limit 윈도우가 리셋되는 Unix epoch 초
`effort.level`	현재 추론 강도(`low`/`medium`/`high`/`xhigh`/`max`/`ultra`)
`session_id`, `session_name`	세션 식별자 및 사용자 지정 이름
`vim.mode`	현재 vim 모드(vim 모드 활성 시)
`pr.number`, `pr.url`, `pr.review_state`	현재 브랜치의 열린 PR 정보

주의사항

상태줄은 /status와 다릅니다. /status는 Settings 창(Status 탭)을 열어 버전·모델·계정·연결 정보를 조회하는 명령이고, /statusline은 하단 상태줄을 직접 구성하는 명령입니다.
출력은 짧게 유지하세요. 상태바 폭이 제한적이라 긴 출력은 잘리거나 어색하게 줄바꿈됩니다.
스크립트는 활성 세션에서 자주 실행되므로 git status 같은 느린 명령은 캐싱(예: /tmp/statusline-git-cache-<session_id>)을 권장합니다.
스크립트는 반드시 stdout으로 출력해야 하며(stderr 아님), 실행 권한이 필요합니다(chmod +x ~/.claude/statusline.sh).
Claude Code가 스크립트 출력을 캡처하므로 tput cols 등으로 터미널 폭을 읽을 수 없습니다. v2.1.153부터는 COLUMNS/LINES 환경변수를 사용하세요.
제거하려면 /statusline에 삭제를 요청하거나 settings.json의 statusLine 필드를 수동으로 지웁니다.

출처

Commands reference: https://code.claude.com/docs/en/commands
Customize your status line: https://code.claude.com/docs/en/statusline

명령어 원본 선언

공식 설명 요약

최소 지원 버전

사용법

settings.json 수동 구성

갱신 시점

좋은 사용 예

비슷한 명령어 추천

활용 사례

주요 stdin JSON 필드

주의사항

출처

목차

Cmd. /statusline

명령어 원본 선언

공식 설명 요약

최소 지원 버전

사용법

settings.json 수동 구성

갱신 시점

좋은 사용 예

비슷한 명령어 추천

활용 사례

주요 stdin JSON 필드

주의사항

출처

목차