Claude Code를 위한 오픈소스 상태 표시줄 도구 'Spark' 공개

실용적 조언

npx spark-hud 명령어를 통해 별도 설치 없이 기능을 즉시 테스트해볼 수 있다.
자주 사용하는 환경 변수나 프로젝트 상태를 쉘 스크립트로 작성해 커스텀 위젯으로 등록하면 작업 효율이 향상된다.

섹션별 상세

01

Claude Code 사용 시 현재 브랜치나 토큰 사용량 등 세션 상태를 실시간으로 확인하기 어렵다는 불편함이 있었다. Spark는 Claude Code의 훅(Hook) 시스템을 활용하여 모든 응답 상단에 상태 표시줄을 출력하며, 첫 프롬프트 이후에는 변경된 상태값만 업데이트하여 정보를 제공한다. 17개의 내장 위젯이 포함되어 있으며 npx 명령어로 즉시 실행 가능한 구조를 갖췄다. 이를 통해 개발자는 별도의 조작 없이도 모델의 상태와 리소스 소모량을 상시 모니터링할 수 있다.

bash

npx spark-hud

Spark HUD를 즉시 실행하기 위한 npx 명령어

Claude Code 터미널 상단에 표시된 Spark HUD의 모습 — Screenshot브랜치명, 토큰 수, 모델명, 세션 시간 등이 한 줄의 상태바 형태로 출력되는 것을 확인할 수 있다. 이는 사용자가 작업 중 실시간으로 리소스와 환경 정보를 파악할 수 있게 돕는다.

02

모델이 현재 작업 중인 환경의 메타데이터를 인지하지 못해 발생하는 맥락 단절 문제를 해결하고자 했다. 위젯은 시각적 정보를 제공하는 디스플레이 모드와 모델에게 세션 정보를 조용히 전달하는 컨텍스트 모드로 구분되어 작동한다. 컨텍스트 모드 위젯은 모델의 프롬프트에 세션 메타데이터를 자동으로 주입하여 상황 인지 능력을 보강한다. 사용자는 모델에게 수동으로 정보를 입력할 필요 없이 더 정확한 응답을 유도할 수 있다.

03

특정 개발 환경에 맞춘 커스텀 상태 정보가 필요한 경우에도 유연하게 대응할 수 있는 구조가 필요했다. 위젯은 한 줄의 텍스트를 출력하는 간단한 쉘 스크립트 형태로 설계되었으며, 3초 이내에 실행 가능한 모든 로직을 HUD에 통합할 수 있다. 순수 Bash와 Python 3로 구현되어 추가적인 라이브러리 설치 없이도 다양한 환경에서 재현 가능하다. 개발자는 자신만의 스크립트를 작성하여 프로젝트 특화된 대시보드를 Claude Code 내에 구축할 수 있다.

다양한 위젯 정보가 출력된 실제 사용 예시 — Screenshot알림(Alerts)과 세부 세션 데이터가 포함된 HUD의 확장된 형태를 보여준다. 위젯 시스템이 어떻게 다양한 정보를 구조화하여 표시하는지 시각적으로 증명한다.

용어 해설

훅 시스템(Hook System): — 프로그램의 특정 실행 지점에서 사용자 정의 스크립트나 코드가 실행되도록 가로채는 메커니즘이다. Claude Code의 응답 생성 전후에 Spark 스크립트를 실행하여 상태 정보를 삽입하는 데 활용된다.
헤드업 디스플레이(HUD): — 사용자의 시선이 머무는 화면 상단에 중요한 정보를 실시간으로 띄워주는 인터페이스 요소이다. 이 도구에서는 브랜치, 토큰, 모델 정보 등을 터미널 상단에 고정하여 보여주는 역할을 한다.
컨텍스트 윈도우(Context Window): — AI 모델이 한 번에 처리할 수 있는 텍스트 데이터의 범위를 의미한다. Spark는 컨텍스트 모드 위젯을 통해 이 범위 내에 세션 메타데이터를 주입하여 모델의 상황 인지 능력을 높인다.

언급된 도구

Spark추천링크

Claude Code용 실시간 상태 표시줄 및 컨텍스트 주입 도구

언급된 리소스

GitHubSpark GitHub Repository