Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 23. 22:32

Claude Code를 위한 맞춤형 상태 표시줄 구축

요약

Claude Code 사용 시 토큰 비용, 컨텍스트 잔량, 현재 프로젝트 및 브랜치 정보를 실시간으로 확인할 수 있는 맞춤형 상태 표시줄 구축 방법을 소개합니다. 상태 표시줄 API를 활용하여 작업 효율을 높이고 비용을 관리하는 팁을 제공합니다.

핵심 포인트

  • 실시간 비용 모니터링을 통한 효율적인 토큰 사용 관리
  • 컨텍스트 잔량 확인으로 적절한 세션 전환 시점 파악
  • 프로젝트 및 브랜치 정보를 통한 컨텍스트 스위칭 비용 감소
  • 단순한 셸 스크립트와 JSON 파이프를 이용한 상태 표시줄 구현

저는 하루 대부분을 Claude Code에서 보냅니다. 이곳은 저의 페어 프로그래머, 코드 리뷰어, 그리고 고무 오리 역할을 모두 수행합니다. 며칠 동안 사용해 보니, 제가 얼마나 많은 토큰을 소모했는지, 세션 비용이 얼마인지, 또는 컨텍스트 창을 채우는 데 얼마나 가까워졌는지 전혀 알지 못한다는 것을 깨달았습니다.

가끔씩 /cost를 실행하며 '예상보다 비싸네'라고 생각하고 다시 작업에 몰두했습니다.

하지만 그 상태가 지속된 것은 하루 정도였습니다.

저는 대시보드를 좋아합니다. 리소스를 소비하거나 돈을 쓰는 상황이라면, 그것이 실시간으로 표시되기를 원합니다. 제가 기억해서 실행해야 하는 또 다른 명령은 원하지 않습니다. 터미널 하단을 힐끗 보고 무슨 일이 일어나고 있는지 즉시 알고 싶습니다.

그래서 저는 맞춤형 상태 표시줄을 만들었습니다.

이유

제가 확인하고 싶었던 것은 세 가지였습니다.

비용 (Cost)

Claude Opus는 무료가 아니며, 긴 세션은 예상외로 비쌀 수 있습니다. 누적 총액이 항상 보이는 것은 제가 작업하는 방식을 변화시킵니다. 이는 한 달에 한 번 은행 계좌를 확인하는 것과 휴대폰 홈 화면에서 잔액을 보는 것의 차이입니다.

제가 다음과 같은 것을 볼 때:

session:$1.47

저는 제가 아직 '계속 진행할 만한' 영역에 있는지, 아니면 현재 작업을 마무리하고 새로 시작해야 할 시간인지 즉시 알 수 있습니다.

컨텍스트 (Context)

Claude Code는 컨텍스트 한계에 가까워지면 대화를 자동으로 압축하지만, 저는 그 결정을 스스로 내리고 싶습니다.

긴 리팩토링 과정에서 다음과 같이 보는 것이:

ctx:81% left

점차

ctx:32% left

으로 줄어드는 것을 보면, 제가 동력을 잃기 전에 지금까지 작업한 내용을 커밋하고 새 세션을 여는 것이 좋을 때라는 것을 알려줍니다.

참고: 상태 표시줄(status line)에 보고되는 컨텍스트 백분율(context percentage)은 Claude Code가 제공하는 가공되지 않은(raw) 값입니다. 제 경험상, 상태 표시줄에 약 28% 남음이라고 표시되어 있을 때 Claude는 컨텍스트 창(context window)이 낮아지고 있다는 경고를 보내기 시작합니다. 경고 자체에는 약 **14%**가 남았다고 표시됩니다. 제 추측으로는 Claude가 의도적으로 보수적으로 동작하여, 압축(compaction) 및 응답 생성(generating responses)을 위해 컨텍스트 창의 일부를 예약해 두기 때문에 실제 한계에 도달하기 훨씬 전에 사용자에게 알림을 주는 것 같습니다. 이러한 동작을 확인해 주는 공식 문서(official documentation)를 찾지는 못했지만, 충분히 일관적이었기에 저는 경고를 기다리기보다 상태 표시줄 값을 기준으로 계획을 세웁니다.

방향 설정 (Orientation)

저는 끊임없이 저장소(repositories)와 브랜치(branches) 사이를 오갑니다.

한눈에 다음 사항들을 알고 싶습니다:

  • 어떤 프로젝트에 있는가?
  • 어떤 브랜치에 있는가?
  • 어떤 모델(model)을 사용 중인가?
  • 이 세션이 실행된 지 얼마나 되었는가?

모든 셸 프롬프트(shell prompt)가 현재 git 브랜치를 보여주는 것과 같은 이유입니다. 컨텍스트 스위칭(context switching)을 줄이는 것은 비용 없는 생산성 향상입니다.

작동 방식 (How It Works)

상태 표시줄 API(status line API)는 실망스러울 정도로 단순합니다.

Claude Code가 셸 스크립트(shell script)를 가리키도록 설정하기만 하면 됩니다. 몇 초마다 Claude Code는 스크립트의 표준 입력(stdin)으로 JSON 문서를 파이프(pipe)로 전달하며, 스크립트가 출력하는 모든 내용이 상태 표시줄이 됩니다.

그게 전부입니다.

SDK도 없습니다.

프레임워크(framework)도 없습니다.

API도 없습니다.

그저 표준 입력(stdin)과 표준 출력(stdout)뿐입니다.

더 좋은 점은, 비용이 전혀 들지 않는다는 것입니다. 모든 것이 로컬(locally)에서 실행됩니다. Claude Code는 로컬 IPC를 통해 스크립트 세션 정보를 보내고, 사용자의 스크립트가 이를 포맷팅(formats)하면 그 결과가 터미널(terminal)에 렌더링(rendered)됩니다. 원한다면 근무 시간 내내 매초마다 새로고침해도 토큰(token)을 단 하나도 소비하지 않습니다.

제가 관심을 갖는 JSON은 다음과 같습니다 (약간 축소됨):

{
  "cwd": "/Users/nsdrone/gitrepos/my-project",
  "model": {
...

제 스크립트는 단 한 번의 jq 호출로 JSON을 파싱(parses)하고, 모든 것을 포맷팅하여 다음과 같이 출력합니다:

~/gitrepos/my-project (main) »    Opus | 5m | in:89.4k out:12.3k cache:64.2k | ctx:81% left | session:$1.47

이것이 제가 신경 쓰는 전부이며, 그 외에는 아무것도 필요하지 않습니다.

Step 1: 스크립트 생성

~/.claude/statusline.sh 파일을 생성합니다:

#!/bin/bash
# Claude Code 상태 표시줄 — 터미널 하단에 세션 정보를 렌더링합니다.
# Claude Code는 매 refreshInterval 초마다 세션 JSON을 stdin으로 파이프합니다;
...

Step 2: 실행 권한 부여

chmod +x ~/.claude/statusline.sh

Step 3: 연결하기

~/.claude/settings.json에 다음 내용을 추가합니다:

{
  "statusLine": {
    "type": "command",
...

새로고침 간격(refresh interval)은 초 단위로 측정됩니다. 저는 모든 것이 실시간으로 업데이트되는 것을 좋아하기 때문에 1을 사용합니다. 만약 이것이 과하다고 느껴진다면 5로 높이세요.

Step 4: 테스트하기

스크립트를 검증하기 위해 Claude Code를 실행할 필요는 없습니다.

echo '{"cwd":"/Users/you/project","git":{"branch":"main"},"model":{"display_name":"Opus"},"context_window":{"current_usage":{"input_tokens":45000,"output_tokens":8000,"cache_read_input_tokens":32000},"remaining_percentage":78},"cost":{"total_cost_usd":0.83,"total_duration_ms":420000}}' | ~/.claude/statusline.sh

예상 출력:

~/project (main) »    Opus | 7m | in:45.0k out:8.0k cache:32.0k | ctx:78% left | session:$0.83

Step 5: Claude Code 재시작

새 세션을 시작하면 상태 표시줄이 터미널 하단에서 대기하고 있을 것입니다.

나만의 스타일로 만들기

가장 좋은 점은 이것이 단순한 셸 스크립트(shell script)라는 것입니다.

몇 가지 아이디어:

  • 컨텍스트(context)가 낮아지면 ANSI 색상 추가.
  • +256/-43 라인 변경 사항 표시.
  • 다중 행(multi-line) 상태 표시줄 구축.
  • git dirty 상태 추가.
  • 진행률 표시줄(progress bar) 추가.
  • 그 외 bash에서 할 수 있는 무엇이든.

이 모든 것을 직접 작성하고 싶지 않다면, Claude Code에는 이미 단축 명령어가 있습니다:

/statusline show me model, branch, token counts, context percentage, and cost

이 명령어를 사용하면 Claude Code가 여러분을 위해 상태 표시줄을 생성하고 연결해 줄 것입니다.

마치며

이것은 제가 Claude Code에서 가장 먼저 커스텀한 기능이었으며, 제가 Claude Code를 사용하는 방식을 완전히 바꾸어 놓았습니다.

상태 표시줄 (status lines), 훅 (hooks), 그리고 다른 확장 지점 (extension points)들이 그저 구조화된 JSON을 받는 셸 스크립트 (shell scripts)일 뿐이라는 것을 깨닫는 순간, 시스템 전체가 이해되기 시작합니다. 당신은 더 이상 "기능"에 대해 생각하지 않고, 자동화 (automation)에 대해 생각하기 시작할 것입니다.

그리고 바로 그 지점에서 재미가 시작됩니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0