상태 표시줄 (Status Line)

기준일: 2026-07-14 난이도: 초급 공식 기준: Customize your status line, Commands

상태 표시줄은 Claude Code 하단에서 로컬 명령을 실행하고, stdin으로 받은 세션 JSON을 짧은 텍스트로 보여주는 기능입니다. 컨텍스트 사용량, 모델, 비용, Git 상태를 세션을 방해하지 않고 확인할 수 있습니다.

핵심 개념

항목	동작
입력	모델, 작업 디렉터리, 비용, 컨텍스트, 세션 ID 등의 JSON
출력	stdout의 텍스트, 여러 줄, ANSI 색상, OSC 8 링크
실행 위치	사용자 컴퓨터의 shell, API 토큰은 소비하지 않음
갱신	응답, `/compact`, 권한·vim 모드 변경 시 실행하고 300ms debounce
주기 갱신	`refreshInterval`로 1초 이상의 추가 실행 간격 설정
Subagent 행	`subagentStatusLine`으로 agent panel의 각 작업 행을 별도 구성

상태 표시줄 명령은 shell command이므로 workspace trust를 수락한 작업 공간에서만 실행됩니다. 프로젝트 설정에 넣을 때는 팀원이 실행할 명령이라는 점을 고려해야 합니다.

선택 기준

가장 빠른 설정은 /statusline에 원하는 정보를 자연어로 설명하는 방식입니다.
공유 설정은 빠르고 의존성이 적은 스크립트만 사용합니다.
시계나 background agent의 Git 상태처럼 idle 중에도 바뀌는 값은 refreshInterval을 사용합니다.
subagent별 상태가 필요할 때만 subagentStatusLine을 추가합니다.
비용이나 민감한 경로를 화면 공유에 노출하면 안 되는 환경에서는 표시 항목을 줄입니다.

실습

Claude Code 안에서 먼저 자동 구성을 요청합니다.

/statusline show model name, current directory, and context percentage

수동으로 구성하려면 ~/.claude/settings.json에 다음을 추가합니다.

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

~/.claude/statusline.sh 예시:

#!/bin/bash
input=$(cat)
model=$(printf '%s' "$input" | jq -r '.model.display_name // "-"')
dir=$(printf '%s' "$input" | jq -r '.workspace.current_dir // .cwd // "-"')
used=$(printf '%s' "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
printf '[%s] %s | %s%% context\n' "$model" "${dir##*/}" "$used"

chmod +x ~/.claude/statusline.sh
echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/tmp/demo"},"context_window":{"used_percentage":25}}' \
  | ~/.claude/statusline.sh

refreshInterval은 이벤트 기반 갱신에 주기 실행을 더합니다. 시간이 지나도 바뀌지 않는 값만 표시한다면 생략하는 편이 낫습니다.

Subagent 상태 행

Agent panel의 기본 작업 행을 바꾸려면 별도 명령을 설정합니다.

{
  "subagentStatusLine": {
    "type": "command",
    "command": "~/.claude/subagent-statusline.sh"
  }
}

이 명령은 tasks 배열을 포함한 JSON을 받고, 바꿀 작업마다 한 줄의 JSON을 출력합니다.

{"id":"task-id","content":"review · running"}

작업 ID를 출력하지 않으면 기본 행을 유지하고, 빈 content를 출력하면 해당 행을 숨깁니다. 플러그인이 기본 subagentStatusLine을 제공할 수도 있습니다.

도구에 입력할 프롬프트

내 Claude Code statusLine 설정과 스크립트를 읽기 전용으로 점검해줘.
workspace trust, 실행 권한, stdout 출력, jq 의존성, 평균 실행 시간,
refreshInterval 필요 여부와 화면 공유 시 민감 정보 노출을 확인해줘.
설정을 바꾸기 전 변경안을 먼저 보여줘.

문제 해결

증상	확인할 것
표시되지 않음	실행 권한, stdout, workspace trust, `disableAllHooks`
값이 비어 있음	첫 응답 전 `null`을 `// 0` 또는 `// "-"`로 처리
갱신이 느림	`git status` 같은 느린 명령 캐시, 스크립트 단독 실행 시간
링크가 클릭되지 않음	터미널의 OSC 8 지원, SSH/tmux escape 처리
오류 원인을 모름	`claude --debug`로 첫 status line 실행의 exit code와 stderr 확인
화면이 깨짐	여러 줄과 복잡한 ANSI/OSC 출력을 단순화

새 갱신이 들어오면 실행 중인 느린 스크립트가 취소될 수 있습니다. 빠른 단일 출력으로 시작한 뒤 필요한 항목만 추가합니다.

체크리스트

공식 입력 필드만 사용하고 null fallback을 넣었다.
mock JSON으로 스크립트를 단독 테스트했다.
스크립트 실행 권한과 workspace trust를 확인했다.
느린 명령을 제거하거나 캐시했다.
refreshInterval이 정말 필요한지 판단했다.
비용, 경로, 브랜치명이 화면 공유에 노출돼도 되는지 확인했다.

다음 단계

설정 가이드에서 설정 범위와 우선순위를 확인합니다.
모델 설정에서 모델 전환 기준을 정합니다.
에이전트 팀에서 병렬 작업 상태를 운영합니다.

상태 표시줄 (Status Line)

기준일: 2026-07-14 난이도: 초급 공식 기준: Customize your status line, Commands

핵심 개념

항목	동작
입력	모델, 작업 디렉터리, 비용, 컨텍스트, 세션 ID 등의 JSON
출력	stdout의 텍스트, 여러 줄, ANSI 색상, OSC 8 링크
실행 위치	사용자 컴퓨터의 shell, API 토큰은 소비하지 않음
갱신	응답, `/compact`, 권한·vim 모드 변경 시 실행하고 300ms debounce
주기 갱신	`refreshInterval`로 1초 이상의 추가 실행 간격 설정
Subagent 행	`subagentStatusLine`으로 agent panel의 각 작업 행을 별도 구성

선택 기준

가장 빠른 설정은 /statusline에 원하는 정보를 자연어로 설명하는 방식입니다.
공유 설정은 빠르고 의존성이 적은 스크립트만 사용합니다.
시계나 background agent의 Git 상태처럼 idle 중에도 바뀌는 값은 refreshInterval을 사용합니다.
subagent별 상태가 필요할 때만 subagentStatusLine을 추가합니다.
비용이나 민감한 경로를 화면 공유에 노출하면 안 되는 환경에서는 표시 항목을 줄입니다.

실습

Claude Code 안에서 먼저 자동 구성을 요청합니다.

/statusline show model name, current directory, and context percentage

수동으로 구성하려면 ~/.claude/settings.json에 다음을 추가합니다.

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

~/.claude/statusline.sh 예시:

#!/bin/bash
input=$(cat)
model=$(printf '%s' "$input" | jq -r '.model.display_name // "-"')
dir=$(printf '%s' "$input" | jq -r '.workspace.current_dir // .cwd // "-"')
used=$(printf '%s' "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
printf '[%s] %s | %s%% context\n' "$model" "${dir##*/}" "$used"

chmod +x ~/.claude/statusline.sh
echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/tmp/demo"},"context_window":{"used_percentage":25}}' \
  | ~/.claude/statusline.sh

refreshInterval은 이벤트 기반 갱신에 주기 실행을 더합니다. 시간이 지나도 바뀌지 않는 값만 표시한다면 생략하는 편이 낫습니다.

Subagent 상태 행

Agent panel의 기본 작업 행을 바꾸려면 별도 명령을 설정합니다.

{
  "subagentStatusLine": {
    "type": "command",
    "command": "~/.claude/subagent-statusline.sh"
  }
}

이 명령은 tasks 배열을 포함한 JSON을 받고, 바꿀 작업마다 한 줄의 JSON을 출력합니다.

{"id":"task-id","content":"review · running"}

작업 ID를 출력하지 않으면 기본 행을 유지하고, 빈 content를 출력하면 해당 행을 숨깁니다. 플러그인이 기본 subagentStatusLine을 제공할 수도 있습니다.

도구에 입력할 프롬프트

내 Claude Code statusLine 설정과 스크립트를 읽기 전용으로 점검해줘.
workspace trust, 실행 권한, stdout 출력, jq 의존성, 평균 실행 시간,
refreshInterval 필요 여부와 화면 공유 시 민감 정보 노출을 확인해줘.
설정을 바꾸기 전 변경안을 먼저 보여줘.

문제 해결

증상	확인할 것
표시되지 않음	실행 권한, stdout, workspace trust, `disableAllHooks`
값이 비어 있음	첫 응답 전 `null`을 `// 0` 또는 `// "-"`로 처리
갱신이 느림	`git status` 같은 느린 명령 캐시, 스크립트 단독 실행 시간
링크가 클릭되지 않음	터미널의 OSC 8 지원, SSH/tmux escape 처리
오류 원인을 모름	`claude --debug`로 첫 status line 실행의 exit code와 stderr 확인
화면이 깨짐	여러 줄과 복잡한 ANSI/OSC 출력을 단순화

새 갱신이 들어오면 실행 중인 느린 스크립트가 취소될 수 있습니다. 빠른 단일 출력으로 시작한 뒤 필요한 항목만 추가합니다.

체크리스트

공식 입력 필드만 사용하고 null fallback을 넣었다.
mock JSON으로 스크립트를 단독 테스트했다.
스크립트 실행 권한과 workspace trust를 확인했다.
느린 명령을 제거하거나 캐시했다.
refreshInterval이 정말 필요한지 판단했다.
비용, 경로, 브랜치명이 화면 공유에 노출돼도 되는지 확인했다.

다음 단계

설정 가이드에서 설정 범위와 우선순위를 확인합니다.
모델 설정에서 모델 전환 기준을 정합니다.
에이전트 팀에서 병렬 작업 상태를 운영합니다.

상태 표시줄 (Status Line)

핵심 개념

선택 기준

실습

Subagent 상태 행

도구에 입력할 프롬프트

문제 해결

체크리스트

다음 단계

관련 가이드

상태 표시줄 (Status Line)

핵심 개념

선택 기준

실습

Subagent 상태 행

도구에 입력할 프롬프트

문제 해결

체크리스트

다음 단계

관련 가이드