Claude Code 상태를 한눈에 보여주는 claude-hud를 소개 합니다.

 

클로드 코드를 사용하면서 제일 궁금했던 게 바로 현재 내 토큰이 얼마나 남았는지가 궁금합니다.

그래서 저는 항상 클로드 사이트의 사용량 페이지를 항시 띄워두고 자주 새로고침을 하며 확인을 했어요.

 

클로드 사이트에서 확인을 하는 것도 점점 귀찮아지면서 상단 바에 표시할 수 있는 코덱스 바 같은 위젯도 알아보며 많은 걸 사용해 봤어요.

하지만 그것도 역시 계속 클릭해서 확인해야 했고 단순 현재 세션의 사용량만을 계산하여 실제 남은 토큰 양과 다르게 나오는 경우가 많았습니다. (위젯 중에는 개인적으로 코덱스바가 정확하고 좋았어요!)

그리고 컨텍스트 사용량이 표시되기는 하지만 이미 많이 차버린 경우에 표시해주기 때문에 미리 관리하기가 힘들었어요.

컨텍스트 사용량 표시가 없다가 큰 작업 들어가기 초반에 갑자기 떠버리면 왠지 토큰 낭비하는 기분도 들고요.

 

그러다 알게 된 클로드의 /statusline 명령어.

클로드 하단에 각종 상태를 표시할 수 있는 기능인데 그냥 해보려니 어렵고 복잡하고...

그래서 statusline 기능을 위주로 찾아보다가 알게 된 claude-hud!!

https://github.com/jarrodwatts/claude-hud

GitHub - jarrodwatts/claude-hud: A Claude Code plugin that shows what's happening - context usage, active tools, running agents,

 

claude-hud란?

Claude Code 입력창 아래에 실시간 상태를 표시해주는 플러그인 입니다. 표시해 주는 정보가 상당히 많습니다.

• 모델/프로젝트 경로/git 브랜치 : 현재 어떤 모델 사용하는지 표시해주고, 특히나 좋았던 프로젝트 경로 표시! 창을 여러개 띄우다 보면 어느 창이 어떤 프로젝트 였는지 가끔 헷갈릴 때가 있었는데 이걸 표시해주니 편했어요.
• 컨텍스트 사용량 : 컨텍스트 사용량을 확인할 수 있어 어느 정도 사용하게 되면 미리 정리할 수 있어요.
• 사용량 한도 : 구독 플랜의 현재 사용량과 reset되는 남은 시간을 표시해줘요.
• Tool : 클로드가 지금 읽고 수정하고 검색하는 파일을 표시해줘요.
• Todo 진행률 : Task가 여러개 일 때 현재 몇 번째 진행 중인지 표시해줘요.

설치하고 기본으로 설정하는 경우 아래와 같이 보여주고 여기에 옵션을 추가해주면 더욱 많은 정보가 표시 됩니다.

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)

 

마음에 든 점

제일 마음에 드는건 별도의 다른 창을 띄우지 않아도 된다는 거에요.

이전에 코덱스바 사용했을 때는 상단 위젝으로 있기 때문에 자세히 보고 싶을때는 눌러봐야 하고 별도 프로그램이다 보니 가끔 먹통이 되기도 했습니다.

claude-hud는 Claude Code에서 원래 제공하는 statusline API를 그대로 사용하기 때문에 별도 창도 띄울 필요없고 입력창 밑에 계속 표시가 됩니다. 그리고 표시되는 정보도 추정치가 아닌 실제 네이티브 데이터라 거의 정확한거 같아요. 완전 실시간은 아니지만 그래도 약 0.3 ~ 0.5초 정도마다 갱신되서 사용하는데 지장은 없는거 같아요.

 

설치도 간단

명령어 몇개만 치면 끝이기 때문에 설치도 너무 간단해요.

 

1) 마켓플레이스 추가

/plugin marketplace add jarrodwatts/claude-hud

 

2) 플러그인 설치 후 리로드

/plugin install claude-hud
/reload-plugins

 

3) 상태줄 설정

/claude-hud:setup

 

setup 명령을 치면 어떤 내용을 표시할 건지 선택하는게 나오는데 저는 전부 체크하고 설치했어요.

Mac에서 설치 했었는데 오류가 나거나 하진 않은거 같습니다.

setup까지 했는데 표시가 안된다면 Claude Code를 재시작 해주세요.

아래 이미지는 실제 제가 사용하는 화면 이에요. 컬러풀하게 한 눈에 보기 좋게 나오죠?

claude-hud 화면

 

HUD 화면 구성

설치하고 나서 보면 처음에는 이게 뭔가 싶어요. 하나씩 설명 드릴께요.

1번째 줄 - 기본 정보

[Opus] │ my-project git:(main*)

• [Opus] : 현재 사용중인 모델을 표시해 줍니다.
• my-project : 현재 프로젝트 경로를 표시해 줍니다.
• git:(main*) : git 브랜치, 끝에 *이 붙으면 커밋 안한 변경사항이 있다는 뜻이에요.

git 기호는 옵션을 켜면 더 자세히 표시됩니다.

• main ↑2 ↓1 : 리모트보다 2개 앞서고(push 안함) 1개 뒤처짐
• main* !3 +1 ?2 : 파일 통계  ! 수정, + 추가/스테이징, x 삭제, ? untracked (0인 건 생략)

2번째 줄 - 컨텍스트 & 사용량

Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██░░░░░░░░ 25% (1d 16h / 7d)

• Context 막대 : 컨텍스트가 얼마나 찼는지 초록 > 노랑 > 빨강으로 색을 바꿔주면서 표시해줘요. 저는 노랑일 때 정리해요.ㅎㅎ
• Usage 막대 : 5시간 Limit, 주간 Limit를 표시해 줍니다. 남은 시간도 같이 표시해줘서 편해요.

그외 옵션 줄들

◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2        ← 툴 활동
◐ explore [haiku]: Finding auth code (2m 15s)    ← 에이전트 상태
▸ Fix authentication bug (2/5)                   ← todo 진행률

• ◐ = 지금 진행 중, ✓ = 완료 (×3은 3번 호출했다는 뜻)
• 에이전트 줄은 어떤 서브에이전트가 어떤 모델로 뭘 하는지 + 경과 시간을 보여준다
• todo 줄의 (2/5)는 5개 중 2개 완료

이 3줄은 할일이 있을 때만 표시되었다가 사라집니다.

 

알아두면 편한 명령어

명령어	용도
/claude-hud:setup	상태줄 초기 설정
/claude-hud:configure	프리셋, 언어, 표시 항목 변경
/reload-plugins	플러그인 다시 불러오기

 

/claude-hud:configure는 탭메뉴를 따라가면서 켜고 끄는 방식이라 config 파일을 안 건드려도 왠만한건 다 할수 있어요. 저장 전에는 미리보기로 어떻게 보일지 확인할 수 있는것도 편해요.

컨텍스트 표시 방식도 취향대로 바꿀 수가 있습니다.

45%만 볼지, 45k/200k 토큰으로 볼지, 남은 양으로 볼지(remaining), 둘 다 볼지(both)

 

아쉬운 점

• 한국어가 안되요. 하지만 간단한 영어들이라 큰 불편은 아니에요.
• 사용량 한도는 구독 계정 전용이에요. 추가 사용량으로 사용하는 API 사용량은 확인 할 수 없어요.
• 클로드 코드 사용중일 때만 갱신되요. 작업이 완료되거나 미사용 중일 때는 자동으로 갱신이 안되고 모델이 응답할 때 갱신이 되어요.
• 자리 차지를 많이 해요. 단순히 패널을 1~2개만 사용할때는 괜찮지만 상하 분할로 4개 사용하면 항상 입력창 하단에 고정되어 있어서 자리 차지를 많이 하게 됩니다.ㅠ

 

결론

설치 쉽고, 따로 안열어도 되고, 실시간으로 보여주기 때문에 설치해두면 편한거 같아요.

특히 컨텍스트 관리가 중요한 긴 작업을 자주 돌리시는 분이나 토큰 사용량을 자주 확인해보시는 분들은 필수로 쓰시는게 좋을거 같아요.

만약 사용하다 맘에 안들면 지워버리면 그만. 그리고 무료라는 점이 너무 좋네요.

개인적으로는 클로드 코드를 많이 사용하신다면 무조건 사용하는게 좋다는 생각 입니다.ㅎㅎ