[Claude Code 설정] statusline, 화면 맨 아래에 폴더 브랜치 모델 사용량 띄우기
지금 어느 폴더와 브랜치에서 어떤 모델로 일하는지, 컨텍스트와 5시간 한도를 얼마나 썼는지를 화면 맨 아래 두 줄에 계속 보여 주는 Claude Code 설정입니다. 설정 방법과 제가 쓰는 스크립트를 정리했습니다.
작업하다가 문득 "내가 지금 어떤 브랜치에 있었지?", "컨텍스트가 얼마나 찼지?" 하고 궁금해질 때가 있습니다. 그때마다 명령어를 치거나 화면을 위로 올려 확인하기가 번거로웠습니다. 이 글에서는 이런 정보를 화면 맨 아래에 계속 띄워 두는 Claude Code의 상태줄(statusline) 설정과, 제가 실제로 쓰는 스크립트를 다룹니다.
1. 어떤 설정인가
상태줄은 Claude Code 화면 아래쪽에 고정되는 줄입니다. 공식 문서에 따르면 사용자가 지정한 셸 명령을 실행하고, 그 명령이 출력한 내용을 그대로 보여 줍니다. 명령은 세션 정보를 JSON으로 표준입력에서 받습니다. 모델 이름, 작업 폴더, 컨텍스트 사용률, 사용량 한도 같은 값이 들어 있어서, 원하는 것만 골라 출력하면 됩니다.
제 상태줄은 두 줄입니다. 첫 줄에는 작업 폴더, git 브랜치, 모델 이름, 사용자 이름이 아이콘과 함께 나옵니다. 둘째 줄에는 Context(컨텍스트 사용률)와 5h Usage(5시간 한도 사용률)가 막대와 퍼센트로 나오고, 한도는 리셋까지 남은 시간도 붙습니다. 사용률은 50% 미만이면 초록, 80% 미만이면 노랑, 그 이상이면 빨강으로 바뀝니다.
2. 출처
| 항목 | 내용 |
|---|---|
| AI 도구 | Claude Code |
| 종류 | 설정 (Claude Code에 내장된 기능, 플러그인이 아닙니다) |
| 만든 곳 | Anthropic (기능), 설정 가이드는 아래 참고 자료 |
| 공식 문서 | https://code.claude.com/docs/en/statusline |
| 참고한 가이드 | 노션 문서 "클로드코드 상태바 세팅 가이드" (작성자 표기: UPAX, 인스타그램 @hongik.man), https://possible-timpani-b05.notion.site/3abf67ccdbf881c2b5e9f4bf449c950c |
| 설치 경로 | 별도 설치 없음, /statusline 명령 |
| 확인한 버전 | 확인하지 못했습니다. 2026년 10월 7일 기준 공식 문서를 읽고 제 설정에서 동작을 확인했습니다. |
| 라이선스 | 해당 없음 |
이 글은 위 가이드를 참고했지만 내용을 옮기지 않고, 공식 문서와 제 환경에서 확인한 것을 다시 정리한 것입니다. 가이드에는 유료 강의와 전자책 안내가 섞여 있으니, 필요한 부분만 보시면 됩니다.
3. 언제 쓰면 좋은가
- 작업 폴더와 브랜치를 자주 헷갈릴 때
- 컨텍스트가 얼마나 찼는지 보고 대화를 정리할 타이밍을 잡고 싶을 때
- 5시간 한도를 얼마나 썼는지 신경 쓰이는 구독 사용자일 때
상태줄은 내 컴퓨터에서 도는 스크립트라서 토큰을 쓰지 않습니다.
4. 사용법
Claude Code 입력창(터미널이 아니라 Claude Code 안)에 원하는 항목을 말로 적습니다. 제가 쓴 문장은 아래와 같습니다.
/statusline 현재 폴더명, git 브랜치, 모델명, 컨텍스트 % 프로그레스바, 5시간 사용량 한도를 한 줄로 보여줘. Python으로 만들어줘
끝에 "Python으로 만들어줘"를 붙인 이유가 있습니다. 공식 문서의 예시는 JSON을 읽을 때 jq라는 프로그램을 쓰는데, 컴퓨터에 따라 설치되어 있지 않을 수 있습니다. 그러면 bash 스크립트는 값을 못 읽어 상태줄이 비어 보일 수 있으므로(참고한 가이드도 같은 이유로 권합니다), 처음부터 Python으로 만들게 했습니다.
그러면 Claude Code가 ~/.claude/ 아래에 스크립트를 만들고 설정 파일을 알아서 고칩니다. 파일을 만들어도 되냐고 물으면 승인하면 됩니다. 설정이 끝난 뒤 아무 말이나 한 번 입력하면 상태줄이 나타납니다.
고치고 싶을 때도 말로 하면 됩니다. "git 브랜치는 빼 줘", "색을 더 밝게 바꿔 줘" 같은 식입니다. 한 줄로 만든 상태줄을 두 줄로 나누고 싶다면 이런 식으로 요청하면 됩니다.
/statusline 첫 줄에는 폴더, 브랜치, 모델, 사용자명을 아이콘과 함께 보여주고, 둘째 줄에는 Context 사용량과 5h Usage 사용량을 막대로 보여줘. 5h Usage에는 리셋까지 남은 시간도 붙여줘
``` 지우고 싶으면 `/statusline delete`를 입력합니다. 설정 파일의 `statusLine` 항목을 직접 지워도 됩니다. 설정은 사용자 폴더의 파일로 저장되기 때문에 껐다 켜도 유지되지만, 다른 컴퓨터에는 따로 한 번 더 해야 합니다.
## 5. 적용 예시
제 `~/.claude/settings.json`에는 아래 항목이 들어 있습니다.
```json
"statusLine": {
"type": "command",
"command": "python3 ~/.claude/statusline.py"
}
스크립트는 표준입력의 JSON에서 필요한 값만 꺼내 두 줄로 출력합니다. 아래는 제 스크립트의 핵심입니다. 제 환경에서는 Orca라는 터미널 도구에 입력을 넘기는 코드가 추가로 들어 있고, 항목 앞에 이모지 아이콘도 붙어 있지만, 글에서는 둘 다 뺐습니다.
import getpass, json, os, subprocess, sys, time
d = json.loads(sys.stdin.read() or "{}")
cwd = (d.get("workspace") or {}).get("current_dir") or os.getcwd()
model = (d.get("model") or {}).get("display_name", "?")
ctx = (d.get("context_window") or {}).get("used_percentage") or 0
five_hour = (d.get("rate_limits") or {}).get("five_hour") or {}
five, resets_at = five_hour.get("used_percentage"), five_hour.get("resets_at")
def color(p):
return "\033[32m" if p < 50 else "\033[33m" if p < 80 else "\033[31m"
def bar(p, n=10):
f = max(0, min(n, round(p / 100 * n)))
return f"{color(p)}{'█' * f}{'░' * (n - f)} {p:.0f}%\033[0m"
def git(*args):
return subprocess.run(["git", "-C", cwd, *args], capture_output=True, text=True, timeout=1).stdout.strip()
def resets_in(ts):
m = int((float(ts or 0) - time.time()) // 60)
if m <= 0:
return ""
return f" (resets in {m // 60}h {m % 60}m)" if m >= 60 else f" (resets in {m}m)"
branch = git("branch", "--show-current")
user = git("config", "user.name") or getpass.getuser()
first = [os.path.basename(cwd)] + ([branch] if branch else []) + [model, user]
second = [f"Context {bar(ctx)}", f"5h Usage {bar(five) + resets_in(resets_at) if five is not None else '-'}"]
print(" ".join(first))
print(" ".join(second))몇 가지를 덧붙입니다. 사용자 이름은 상태줄이 받는 JSON에 없어서, git config user.name에서 읽고 없으면 시스템 계정 이름을 씁니다. 리셋까지 남은 시간은 공식 문서의 rate_limits.five_hour.resets_at(유닉스 초)에서 계산합니다. rate_limits는 문서에 따르면 Pro나 Max 구독자에게만, 그리고 세션에서 첫 응답을 받은 뒤에야 들어옵니다. 그래서 값이 없을 때는 -로 표시하고, 리셋 시간이 없거나 이미 지났으면 괄호를 뺍니다. 줄을 나누고 싶을 때는 print를 한 번 더 호출하면 됩니다.
실제로 화면에 뜬 모습이 아래입니다. 이 캡처는 git 저장소가 아닌 홈 폴더에서 막 켠 세션이라 브랜치 항목이 없고, 5h Usage는 첫 응답을 받기 전이라 -로 나옵니다. 저장소 안에서는 폴더 이름 뒤에 브랜치가 붙고, 사용자 이름은 그 폴더에 적용된 git 설정을 따릅니다.

6. 써 본 소감
한 번 만들어 두면 따로 신경 쓸 일이 없고, 컨텍스트 막대의 색이 바뀌는 것으로 대화를 정리할 때를 가늠할 수 있습니다. 항목을 말로 바꿀 수 있어서 부담 없이 고쳐 가며 쓸 수 있습니다. Claude Code를 자주 쓴다면 가장 먼저 해 볼 만한 설정이라고 느꼈습니다.
Comments (0)