클로드 코드 상태 표시줄 설정 방법: /statusline으로 컨텍스트와 Git 상태 처음 보는 법

TL;DR

핵심 3줄 요약

이 글에서 다룰 내용

상태 표시줄은 무엇인가

Claude Code 상태 표시줄은 화면 하단의 사용자 설정 영역입니다. 설정한 셸 스크립트를 실행하고 JSON 세션 데이터를 표준 입력으로 전달한 뒤, 스크립트가 표준 출력으로 내보낸 내용을 표시합니다. 컨텍스트 창 사용률, 비용, Git 상태, 작업 디렉터리처럼 작업 중 계속 볼 정보를 한곳에 둘 수 있습니다.

이 기능은 여러 터미널 명령을 오가며 현재 저장소나 세션 상태를 확인하는 사람에게 맞습니다. 반대로 한 번만 확인하면 되는 정보나 느린 네트워크 요청은 표시줄보다 필요할 때 명령으로 확인하는 편이 낫습니다.

/statusline은 어디에서 시작하나

Claude Code 대화 입력창에서 /statusline 을 입력해 시작합니다. 명령 뒤에 원하는 표시 내용을 자연어로 쓰면 Claude Code가 ~/.claude/ 아래에 스크립트를 만들고 설정을 자동으로 갱신합니다. 설정 중 파일 편집 승인이 나오면 새 파일 경로와 실행 명령을 읽은 뒤 승인하세요.

첫 설정 순서

1. 작업할 프로젝트 폴더에서 Claude Code 대화를 엽니다.
2. 입력창에 /statusline 을 입력합니다.
3. 컨텍스트 사용률과 Git 상태를 한 줄로 보여 달라고 요청합니다.
4. 생성할 스크립트와 변경할 설정 파일을 검토합니다.
5. 신뢰한 작업공간에서만 변경을 승인하고, 다음 상호작용 뒤 표시 결과를 확인합니다.
6. 표시줄이 길면 프로젝트 폴더, Git 상태, 컨텍스트 사용률 순으로 항목을 줄입니다.

그대로 복사해 쓸 프롬프트

목표: 현재 Claude Code 세션의 컨텍스트 사용률과 Git 상태를 한 줄 상태 표시줄로 보여줘.
허용 입력: Claude Code가 표준 입력으로 제공하는 세션 JSON과 현재 작업 디렉터리의 Git 정보.
제외 입력: API 키, 토큰, 이메일, 파일 내용, 네트워크 요청.
출력 형식: 프로젝트 폴더 | Git 상태 | 컨텍스트 사용률 순서의 짧은 한 줄.
완료 기준: 상태 표시줄에 표시되고, Git 저장소가 아닌 폴더에서도 긴 오류 메시지를 출력하지 않음.
추정 금지: 확인할 수 없는 Git 상태나 민감한 값을 만들어 표시하지 말 것.
승인 지점: 스크립트 파일과 설정을 바꾸기 전에 변경 파일과 실행 명령을 보여주고 내 승인을 받을 것.

이 요청은 무엇을 읽고 무엇을 화면에 표시할지 미리 제한합니다. 상태 표시줄은 셸 명령을 실행하므로 입력 범위와 출력 범위를 좁힐수록 검토가 쉬워집니다.

수동 설정은 언제 필요한가

자동 생성 결과를 더 세밀하게 통제하려면 사용자 설정 파일 ~/.claude/settings.json 또는 프로젝트 설정에 statusLine 필드를 넣을 수 있습니다. 공식 문서의 기본 구조는 type 을 command 로 두고, command 에 스크립트 경로나 인라인 셸 명령을 지정하는 방식입니다.

자동 설정으로 한 번 만든 뒤 결과를 읽고 필요한 부분만 바꾸는 편이 처음부터 수동으로 작성하는 것보다 안전합니다. 시간이나 백그라운드 하위 에이전트의 Git 변경처럼 이벤트가 없어도 갱신할 정보에는 선택 사항인 refreshInterval 을 쓸 수 있으며, 공식 문서상 최소값은 1초입니다.

Git 상태를 어떻게 써야 하나

공식 문서는 Git 브랜치와 변경 상태를 표시하는 예시를 제공합니다. 다만 상태 표시줄은 요약용입니다. 브랜치 이름이나 변경 표시가 보인다고 해서 변경 내용, 테스트 결과, 커밋 대상이 검토된 것은 아닙니다.

변경 신호를 봤다면 다음 단계는 git diff 와 프로젝트의 테스트 명령으로 확인하는 것입니다. 상태 표시줄은 재확인을 빠르게 시작하게 해 주는 도구이지, 승인 절차를 없애는 도구가 아닙니다.

주의할 점

• 네트워크 요청이나 대용량 파일 탐색을 넣으면 표시줄 갱신이 느려질 수 있습니다.
• Git 저장소가 아닌 폴더에서도 짧고 안전하게 동작하도록 예외 처리를 요청하세요.
• 팀 프로젝트 설정을 바꾸기 전에는 개인 설정인지 프로젝트 설정인지 저장 위치를 구분하세요.
• 설정 방식과 제공 필드는 바뀔 수 있으므로 문제가 생기면 공식 문서의 현재 예시를 기준으로 다시 확인하세요.

자주 묻는 질문

출처

마무리

Claude Code 상태 표시줄의 시작점은 복잡하지 않습니다. 대화 입력창에서 /statusline 을 실행하고, 처음에는 컨텍스트 사용률과 Git 상태처럼 행동을 바꾸는 정보만 요청하면 됩니다. 생성되는 스크립트와 설정은 반드시 읽고 승인한 뒤, 상태 표시줄을 요약 신호로 활용하세요.