상태 표시줄이란 무엇인가
문서에서는 이를 한 문장으로 설명합니다: "상태 표시줄은 사용자가 구성한 쉘 스크립트를 실행하는 Claude Code 하단의 사용자 정의 가능한 바입니다. stdin으로 JSON 세션 데이터를 수신하고 스크립트가 출력하는 내용을 표시합니다."
사람들이 이를 사용하는 이유는 다음과 같습니다:
- "작업하면서 컨텍스트 창 사용량을 모니터링"하기 위해.
- "세션 비용을 추적"하기 위해.
- "여러 세션에서 작업"할 때 세션을 구분하기 위해.
- git 브랜치와 상태를 계속 표시하기 위해.
구축하기 전에 알아두어야 할 두 가지 세부 사항이 있습니다. 첫째, 모델 사용 비용이 들지 않습니다: "상태 표시줄은 로컬에서 실행되며 API 토큰을 소비하지 않습니다." 둘째, 기본 푸터를 대체하는 것이 아니라 나란히 위치하지만, 문서에 따르면 사용자 정의 상태 표시줄을 사용하면 Claude Code가 일부 푸터 힌트 표시를 중단할 수 있습니다.
설정 방법
두 가지 방법이 있습니다.
Claude에게 작성을 맡기기. 문서에 따르면: "/statusline 명령은 표시하려는 내용에 대한 자연어 지침을 수락합니다. Claude Code는 ~/.claude/에 스크립트 파일을 생성하고 설정을 자동으로 업데이트합니다." 모델 이름이나 컨텍스트 바와 같이 원하는 내용을 설명하고 파일 수정을 승인하면 됩니다.
직접 작성하기. ~/.claude/settings.json의 사용자 설정 또는 프로젝트 설정에 statusLine 필드를 추가합니다. 타입을 command로 설정하고 명령이 스크립트나 인라인 쉘 명령을 가리키도록 합니다.
출력 형태를 결정하는 세 가지 선택적 필드가 있습니다:
- padding: 가로 간격을 추가합니다.
- refreshInterval: 아래에서 다룰 타이머에 따라 명령을 재실행합니다.
- hideVimModeIndicator: 스크립트가 vim 모드 텍스트를 표시할 때 기본 제공되는 표시기를 숨깁니다.
상태 표시줄을 제거하려면 /statusline을 실행하여 제거 또는 삭제를 요청하거나 설정에서 해당 필드를 삭제하면 됩니다.
스크립트가 수신하는 세션 필드
스크립트가 실행될 때마다 stdin으로 하나의 JSON 객체를 받습니다. 문서의 표는 길지만, 필드는 몇 가지 그룹으로 나뉩니다.
모델 및 노력(Effort). model.id 및 model.display_name, 그리고 effort.level 및 thinking.enabled.
현재 위치. workspace.current_dir, workspace.project_dir(Claude Code가 실행된 디렉토리), 추가된 디렉토리, origin 원격 저장소의 리포지토리 ID, 그리고 워크트리(worktree)에 있을 경우 관련 세부 정보.
세션 식별. "고유 세션 식별자"인 session_id, 그리고 설정한 이름이나 AI가 생성한 제목을 사용하는 session_name. 처리 중인 프롬프트에 대한 prompt_id와 "대화 트랜스크립트 파일 경로"인 transcript_path도 있습니다.
컨텍스트. 다음 섹션에서 다룰 context_window 객체.
비용 및 시간. 클라이언트 측에서 계산된 추정치로 "실제 청구액과 다를 수 있는" cost.total_cost_usd, 그리고 총 소요 시간과 추가/삭제된 라인 수.
제한 사항. 속도 제한(rate-limit) 창과 리셋 시점에 대한 필드, 그리고 캐시가 활성화되었는지 여부를 포함하는 프롬프트 캐시 객체.
풀 리퀘스트(PR). 현재 브랜치에 대한 열린 PR 번호, URL 및 리뷰 상태.
일부 필드는 해당 사항이 생기기 전까지는 나타나지 않습니다. 문서의 문제 해결 섹션에서는 다음과 같이 조언합니다: "첫 번째 API 응답이 완료되기 전에는 필드가 null일 수 있으므로, 스크립트에서 폴백(fallback)을 사용하여 null 값을 처리하십시오."
컨텍스트 창 사용량 표시 방법
컨텍스트 모니터링은 문서에 나열된 첫 번째 용도이며, 해당 페이지에는 포함된 내용이 정확히 설명되어 있습니다.
"가장 최근 API 응답의 실시간 컨텍스트 창"을 설명합니다. 여기에는 최대 창 크기, 결합된 입력 및 출력 합계, 카테고리별 분석, 그리고 미리 계산된 두 필드인 used_percentage와 remaining_percentage가 포함됩니다.
핵심 규칙은 무엇을 계산에 포함하느냐입니다. 문서에 따르면: "used_percentage 필드는 입력 토큰으로만 계산됩니다: input_tokens + cache_creation_input_tokens + cache_read_input_tokens. 여기에는 output_tokens가 포함되지 않습니다."
분석 데이터를 바탕으로 직접 수치를 계산하는 경우, 문서에서는 "used_percentage와 일치하도록 동일한 입력 전용 공식을 사용하라"고 권장합니다. 대부분의 스크립트에 대한 권장 사항은 더 간단합니다: "가장 간단하고 정확한 컨텍스트 상태를 위해 used_percentage를 사용하십시오."
주의해서 다뤄야 할 필드가 하나 있습니다: exceeds_200k_tokens. 문서에 따르면 이는 최신 응답의 결합된 카운트가 200k를 초과하는지 여부를 반영하며, "실제 컨텍스트 창 크기와 관계없이 고정된 임계값"입니다. 이것이 창이 거의 찼다는 경고는 아닙니다.
/context와 차이가 나는 이유
상태 표시줄과 /context는 측정하는 시점이 약간 다릅니다. 상태 표시줄은 마지막 API 응답을 사용합니다. /context는 그 이후에 추가된 메시지에 대한 추정치를 더합니다. 따라서 대용량 파일을 붙여넣거나 Claude가 여러 파일을 읽은 직후에는 다음 응답이 오기 전까지 /context가 상태 표시줄보다 더 높은 수치를 보여줄 수 있습니다.
압축(Compaction)은 데이터의 일부를 초기화합니다. 문서에 따르면 current_usage 객체는 "세션의 첫 번째 API 호출 전, 그리고 /compact 직후부터 다음 API 호출로 다시 채워지기 전까지 null입니다." 압축 직후에 컨텍스트 세그먼트가 비어 있거나 대시(-)로 표시되는 것은 정상적인 동작이며, 스크립트에 폴백을 설정해두면 가독성을 유지할 수 있습니다.
상태 표시줄 업데이트 시점
업데이트는 시간이 아니라 이벤트에 의해 구동됩니다. 문서에 따르면 스크립트는 세션이 시작되거나 재개될 때 한 번 실행되며, 다음과 같은 경우에 다시 실행됩니다:
- "새로운 어시스턴트 메시지가 도착했을 때".
- "
/compact가 완료되었을 때". - "권한 모드가 변경되었을 때".
- "Vim 모드가 전환되었을 때".
- 설정에서 명령을 변경했을 때.
- 설정한 경우, 새로고침 간격(refresh interval)이 경과했을 때.
- 마지막 데이터의 속도 제한 창이나 프롬프트 캐시 만료 시간이 리셋 또는 만료 시점에 도달했을 때.
업데이트는 일괄 처리됩니다: "Claude Code는 300ms 간격으로 업데이트를 디바운싱하므로, 급격한 변경 사항은 하나로 묶여 변경이 멈춘 후 스크립트가 한 번 실행됩니다." 또한 스크립트가 실행 중인 동안 새로운 업데이트가 트리거되면 Claude Code는 실행 중인 스크립트를 취소합니다.
백그라운드 에이전트 실행 중 업데이트가 멈추는 이유
이것이 서두의 예시에서 나타난 동작입니다. 업데이트는 메인 세션의 이벤트를 따르기 때문에, 메인 세션에서 긴 대기가 발생하면 다른 곳에서 작업이 진행 중이더라도 업데이트가 거의 또는 전혀 발생하지 않습니다.
문서에서는 이 사례를 직접 언급합니다: "메인 세션이 유휴 상태일 때(예: 코디네이터가 백그라운드 서브 에이전트를 기다리는 동안) 이벤트 기반 트리거가 조용해질 수 있습니다." 해결책은 refreshInterval을 설정하여 "고정된 타이머에 따라 명령을 재실행"하는 것입니다. 최소값은 1초입니다.
문서에서는 시계와 같이 세션 외부에서 변경되는 세그먼트나, "메인 세션이 유휴 상태인 동안 백그라운드 서브 에이전트가 git 상태를 변경할 때"를 위해서도 이 설정을 언급합니다. 멀티 에이전트 작업 중에 상태 표시줄에 git 상태를 표시한다면, 새로고침 간격을 설정해야 최신 상태를 유지할 수 있습니다.
새로고침 간격은 스크립트를 재실행할 뿐, 새로운 컨텍스트 데이터를 생성하지는 않습니다. 컨텍스트 필드는 여전히 메인 세션의 가장 최근 API 응답에서 가져옵니다.
상태 표시줄이 사라지는 원인
문제 해결 섹션에는 상태 표시줄이 비어 있게 되는 몇 가지 원인이 나열되어 있습니다:
- 폴더를 신뢰하지 않음. "워크스페이스 신뢰 대화 상자를 수락하기 전까지 상태 표시줄은 비어 있습니다." 상태 표시줄은 쉘 명령을 실행하므로 후크(hooks)와 동일한 신뢰 규칙을 따릅니다.
- 스크립트 실패. "0이 아닌 코드로 종료되거나 출력을 생성하지 않는 스크립트는 상태 표시줄을 비게 만듭니다."
- 후크 비활성화. 관리형 설정 외부에서
disableAllHooks가 true인 경우 관리형 상태 표시줄만 실행됩니다. - 조직의 후크 제한. 관리형 설정에서
allowManagedHooksOnly가 설정된 경우, "사용자 정의 상태 표시줄이 경고 없이 사라집니다."
무슨 일이 일어나고 있는지 확인하려면 claude --debug를 실행하는 것이 좋습니다. 이 명령은 세션의 첫 실행 시 스크립트의 stderr와 종료 코드를 기록합니다.
속도도 중요합니다. "느린 스크립트는 완료될 때까지 상태 표시줄 업데이트를 차단합니다." git status와 같은 명령의 경우, 문서에서는 결과를 캐싱할 것을 제안합니다.
Codex가 새로운 채팅에서 왜 상단부터 시작하는지를 포함하여 자체적으로 남은 컨텍스트 수치를 계산하는 방법은 Codex의 남은 컨텍스트 가이드에서 다루었습니다.
사람들이 처음에 겪는 시행착오
상태 표시줄을 /context와 비교함. 두 수치는 측정 시점이 다릅니다. /context는 다음 응답 전까지 더 높게 표시될 수 있습니다.
긴 백그라운드 작업 중 업데이트를 기대함. 메인 세션이 유휴 상태일 때는 이벤트 트리거가 멈춥니다. 새로고침 간격을 설정하세요.
exceeds_200k_tokens를 창이 꽉 찼다는 경고로 간주함. 이는 고정된 임계값일 뿐입니다.
컨텍스트 수치에 출력 토큰을 더함. used_percentage는 입력 토큰만 계산합니다.
신뢰되지 않은 폴더에서 빈 줄을 디버깅함. 먼저 신뢰 대화 상자를 수락하세요.
해결책: 상태 표시줄을 통해 컨텍스트 저장 시점 파악하기
1단계: used_percentage 표시
가장 간단하고 정확한 컨텍스트 상태를 위해 문서화된 필드입니다.
2단계: null 값에 대한 폴백 추가
첫 응답 전이나 /compact 후에는 필드가 비어 있을 수 있습니다.
3단계: 에이전트 작업을 위한 새로고침 간격 설정
메인 세션이 대기하는 동안에도 세그먼트를 최신 상태로 유지하세요.
4단계: 창이 차기 전에 결정 사항 저장
수치가 올라가면 나중에 다시 필요할 세션의 결정 사항과 사실들을 기록해 두세요.
MemoryLake에서 설정하기
상태 표시줄은 컨텍스트 창이 얼마나 찼는지만 알려줄 뿐, 아무것도 보관하지 않습니다. 세션이 압축되거나 종료되면 그 안에서 내린 결정은 요약본이나 트랜스크립트만큼만 유지됩니다. 결정한 내용, 실패한 접근 방식, 적용되는 제약 조건 등 세션을 가로질러 중요한 컨텍스트는 직접 작성한 노트로 보관하는 것이 좋습니다.
MemoryLake는 이러한 프로젝트 컨텍스트(과거 세션의 결정, 제약 조건, 교훈 등)를 위한 메모리 레이어입니다. 사용자가 직접 관리하는 한 곳에 보관되며 ChatGPT, Claude Code, Codex 등 연결된 어시스턴트에서 사용할 수 있습니다.
항목은 자신의 언어로 직접 작성합니다. Claude Code 세션, 트랜스크립트, 상태 표시줄 스크립트, 설정 파일 또는 공급업체의 저장소에서 데이터를 읽거나 쓰거나 삭제하지 않습니다. 상태 표시줄은 Anthropic이 설명한 방식 그대로 작동합니다.
1단계: API 키 생성
로그인 후 대시보드에서 키를 생성합니다. 다른 자격 증명과 마찬가지로 리포지토리 외부에 보관하세요.

2단계: 첫 번째 메모 업로드
해결책 4단계에서 작성한 내용, 즉 긴 세션에서 보관할 가치가 있는 결정과 사실부터 시작하세요. 항목당 하나의 주제를 다룹니다.

3단계: AI 및 에이전트 연결
Claude Code, Codex 및 사용하는 다른 어시스턴트를 연결합니다. 새로운 세션도 동일한 노트에서 시작할 수 있습니다.

실제 작업에서의 변화
첫 번째 차이점은 타이밍입니다. 상태 표시줄은 단순한 측정기가 아니라 컨텍스트를 저장하라는 신호가 됩니다.
두 번째는 더 매끄러운 압축입니다. 요약이 세부 사항을 대체하기 전에 필요한 내용이 이미 기록되어 있습니다.
세 번째는 도구 간의 일관성입니다. Claude Code에서 사용한 것과 동일한 노트를 다른 어시스턴트에서도 사용할 수 있습니다.
Claude Code 상태 표시줄 모범 사례
/statusline으로 시작하세요. 원하는 내용을 설명하고 Claude Code가 스크립트를 작성하게 하세요.
used_percentage를 사용하세요. 설계상 입력 토큰만 계산합니다.
null을 처리하세요. 첫 응답 전과 압축 후에는 값이 비어 있을 수 있음을 예상하세요.
긴 에이전트 작업을 위해 refreshInterval을 추가하세요. 이벤트 트리거가 멈출 수 있습니다.
스크립트를 빠르게 유지하세요. git status와 같이 느린 명령은 캐싱하세요.
세션 이름을 표시하세요. 여러 세션을 실행할 때 도움이 됩니다.
비어 있다면 신뢰 및 후크 설정을 확인하세요. 두 설정 모두 상태 표시줄을 숨길 수 있습니다.
결론
Claude Code 상태 표시줄은 사용자가 구성한 쉘 스크립트를 실행하고, stdin으로 JSON 세션 데이터를 전달하며, API 토큰을 사용하지 않고 스크립트의 출력 내용을 표시합니다. 데이터에는 모델, 워크스페이스, 세션 ID 및 이름, 트랜스크립트 경로, 비용 추정치, 속도 제한, 그리고 입력 토큰만 계산하는 used_percentage를 포함한 context_window 객체가 포함됩니다.
새로운 어시스턴트 메시지나 /compact와 같은 이벤트 발생 시 300ms 디바운싱과 함께 업데이트됩니다. 메인 세션이 백그라운드 서브 에이전트를 기다리는 동안 이러한 트리거가 멈출 수 있으므로, refreshInterval을 통해 최신 상태를 유지할 수 있습니다. 상태 표시줄은 마지막 API 응답을 보고하므로 /context가 더 높게 표시될 수 있습니다. 이를 창이 가득 차기 전에 중요한 내용을 저장하라는 신호로 활용하세요.