ONEDEV

claude-hud

AI Coding ToolsskillJavaScript

★ 27,999주당 +141조회 5

무엇인가

claude-hud는 Claude Code 세션의 관측성 계층을 담당하는 플러그인이다. 모델·프로젝트 경로·git 브랜치, 컨텍스트 사용률, 요율 한도, 도구 호출, 서브에이전트 상태, 할 일 진행률을 입력창 아래 상태줄에 상시 표시하도록 규율한다. 대화 기록을 읽어 세션 상태를 추측하는 대신 Claude Code가 이미 계산한 값을 받아 렌더링하는 데 초점을 둔다.

어떻게 동작하나

동작 경로는 Claude Code의 네이티브 statusline API다. Claude Code가 stdin으로 넘기는 JSON과 트랜스크립트 JSONL을 읽어 도구·에이전트·할 일 활동을 파싱하고 stdout으로 상태줄 문자열을 출력한다. 별도 창이나 tmux가 필요 없다. 렌더링은 새 어시스턴트 메시지, /compact, 권한 변경, vim 모드 전환 같은 상호작용 뒤에 300ms 디바운스로 다시 실행된다. 설정은 ~/.claude/plugins/claude-hud/config.json에 두고 /claude-hud:configure가 레이아웃·언어·표시 토글을 안내한다. Full/Essential/Minimal 프리셋을 고른 뒤 요소별로 켜고 끌 수 있다.

무엇과 다른가

tmux 패널이나 별도 모니터 창을 띄우는 도구와 달리 터미널 종류를 가리지 않고 Claude Code 프로세스 안에서 끝난다. settings.json에 statusLine 명령을 직접 작성하는 방식과 비교하면 토큰 수를 추정하지 않고 Claude Code가 보고한 컨텍스트 윈도 크기를 그대로 쓰며 1M 컨텍스트 세션에도 맞춰 스케일한다. CLAUDE.md·AGENTS.md 같은 규칙 파일이 에이전트의 행동을 제약하는 것과 달리, 이 플러그인은 에이전트의 판단에 개입하지 않고 사람이 읽는 상태 표시만 만든다.

어떻게 쓰나

Claude Code 세션 안에서 /plugin marketplace add jarrodwatts/claude-hud로 마켓플레이스를 등록하고 /plugin install claude-hud로 설치한 뒤 /reload-plugins를 실행한다. 세션 밖에서는 claude plugin marketplace add jarrodwatts/claude-hud와 claude plugin install claude-hud@claude-hud로 같은 단계를 수행한다. 마지막으로 /claude-hud:setup을 실행해 상태줄을 구성하면 다음 메시지부터 HUD가 나타난다. CLAUDE_CONFIG_DIR로 여러 설정 디렉터리를 쓰고 plugins/를 심볼릭 링크로 공유하는 경우, 디렉터리별 값은 $CLAUDE_CONFIG_DIR/claude-hud.json에 두면 공유 설정 위에 덧씌워진다.

전제와 한계

Claude Code 전용이며 다른 에이전트에는 붙지 않는다. Windows에서는 Node.js LTS가 지원 런타임이라 없으면 /claude-hud:setup이 런타임을 찾지 못하고, 구버전 Claude Code에서 /tmp가 별도 파일시스템일 때 EXDEV 오류가 발생했다. 색상 바 문자는 보이는 그래프 문자 하나만 허용하고 제어 문자·제로폭 문자·구분자는 거부하며, 이모지나 CJK 같은 넓은 문자는 터미널에 따라 정렬을 어긋나게 할 수 있다. display.showMemoryUsage는 expanded 레이아웃에서만 렌더링되고, 중국어 라벨은 명시적으로 선택해야 켜진다.

유사 도구