실시간 VPS 모니터링이 포함된 Claude Code용 커스텀 상태 바

Claude Code용 커스텀 상태 표시줄: 실시간 VPS 모니터링

여러 서버에서 Claude Code를 동시에 다루는 개발자들은 인프라 상태를 확인하기 위해 맥락을 전환하느라 시간을 낭비하곤 합니다. 해결책은 바로 에디터 내에서 주요 세션 지표와 VPS 모니터링을 실시간으로 보여주는 커스텀 상태 표시줄입니다. 맥락 전환 없이 바로 확인 가능하죠.

시스템 아키텍처

모니터링 시스템은 서버를 주기적으로 폴링하는 백그라운드 데몬과 데이터를 표시하는 클라이언트 스크립트 두 부분으로 구성됩니다. vps-poller.sh 데몬은 30초마다 서버에 SSH 쿼리를 보내 다음 네 가지 핵심 지표를 수집합니다:

• RAM 사용량
• CPU 부하
• 디스크 공간 사용량
• 시스템 가동 시간

데이터는 /tmp/에 JSON 파일로 캐싱되어 statusline.sh 클라이언트 스크립트가 추가 네트워크 호출 없이 즉시 최신 정보를 가져올 수 있습니다. 이로 인해 Claude Code 인터페이스가 항상 가볍게 유지됩니다.

주요 아키텍처 장점:

• 캐싱 덕분에 네트워크 오버헤드 최소화
• 표시 지연 완전 제로
• 모듈러 설계: 데몬 독립 실행 가능
• 여러 서버 동시 처리

활성 서버 자동 포커스

여러 VPS 인스턴스를 다룰 때 가장 큰 불편은 현재 작업 중인 서버를 파악하는 일입니다. 이 시스템은 Claude Code 로그를 자동 분석해 이를 해결합니다.

스크립트는 최근 20KB 세션 대화록을 스캔하며, 활성 서버를 찾기 위해 두 가지 전략을 사용합니다:

• SSH 명령어(ssh, scp, sftp) 감지 후 IP 주소를 사전 설정된 서버 목록과 매칭
• Model Context Protocol(MCP)만 사용할 경우 서버 이름으로 후순위 검색

실제 동작 예시:

# SSH로 'main' 서버 작업 중
▶ main●(R:42% D:55%) new● sec●

# MCP로 'sec' 서버로 전환
main● new● ▶ sec●(R:61% D:70%)

# 'new' 서버 고부하 (항상 강조 표시)
▶ main●(R:42% D:55%) new◉(R:92%) sec●

상태 표시기:

• ● — 정상
• ◉ — 고부하 (RAM > 85% 또는 디스크 > 90%)
• ✗ — 서버 연결 불가
• ↻ — 최근 재부팅
• ▶ — 현재 활성 서버

Claude API 연동 및 비용 추적

상태 표시줄은 Claude API와 연동해 실시간 사용 한도와 세션 비용 추정치를 보여줍니다. 계정 유형을 자동 감지합니다:

• Claude Max 구독자: 이론적 세션 비용 표시
• API 사용자: 실제 지출액

표시되는 Claude API 지표:

• 활성 모델 — 현재 모델 (예: Opus 4.6)
• 컨텍스트 충전도 — 색상 구분 진행 바 (초록 → 노랑 → 빨강)
• 남은 쿼터 — 5시간(H) 및 주간(W) 한도 사용 비율
• 세션 비용 — 예상 API 비용

API 데이터는 부하를 줄이기 위해 2분간 캐싱되며, 시스템 자격 증명 저장소에서 OAuth 토큰을 가져옵니다.

설치 및 설정

설치는 Claude Code를 통해 간편하게 진행되며, 빠른 배포를 위해 최적화되었습니다.

Claude Code를 통한 빠른 설치:

Clone https://github.com/CreatmanCEO/claude-statusline and run install.sh --ru

고급 사용자용 수동 설치:

git clone https://github.com/CreatmanCEO/claude-statusline.git ~/claude-statusline
bash ~/claude-statusline/install.sh --ru

VPS 모니터링 설정:

• ~/.claude/statusline.conf에 서버 추가
• SHOW_VPS=remote 설정
• VPS_SERVERS에 서버 목록 입력
• 데몬 시작: ~/claude-statusline/vps-poller.sh start

플랫폼별 주의사항:

• Linux/macOS: 모든 기능 지원
• Windows: Claude Code를 통한 설치만 (PowerShell 생략)
• JSON 처리 위해 bash와 jq 사전 설치 필요

주요 기능

• 즉시 VPS 모니터링 — 도구 전환 없이 서버 상태 확인

• 자동 포커스 — Claude Code 로그에서 활성 서버 자동 감지

• Claude API 연동 — 실시간 한도 및 세션 비용

• 경량 — 순수 bash + jq, Node.js 등 무거운 런타임 불필요

• 크로스플랫폼 — Linux, macOS, Windows(제한 있음)

호환성 수정 사항

개발 및 테스트 과정에서 주요 이슈를 해결했습니다:

Windows 권한 문제:

• PowerShell에서 chmod 실패
• 해결: Claude Code 전용 설치 지침

OAuth 토큰 저장:

• Windows: .credentials.json
• Unix: .credentials
• 해결: 스크립트에서 둘 다 확인

중첩 JSON 따옴표:

• echo로 JSON 손상
• 해결: 적절한 이스케이프 적용 printf로 변경

Windows bash 경로:

• command -v bash에서 공백 포함 경로 반환
• 해결: 경로 확인 없이 직접 bash 호출

모든 수정은 출시 당일 완료—오픈소스 속도의 힘입니다.

고급 기능 및 커스터마이징

다양한 표시 모드로 워크플로에 맞게 상태 표시줄을 조정하세요.

커스터마이징 가능한 세그먼트:

• Git 정보: 현재 브랜치 및 변경 상태
• 코드 통계: 이번 세션 추가/제거 라인 수
• 세션 타이머: 작업 시간
• 시스템 도구: MCP 및 기타 프로토콜 지원

성능 최적화:

• 초소형 풋프린트: 데몬 CPU <1%
• 스마트 캐싱: 변경 시에만 업데이트
• 지연 로딩: 미사용 모듈 생략

커뮤니티 피드백으로 프로젝트가 진화 중입니다. 앞으로: 더 많은 모니터링 프로토콜, UI 개선, 개발 도구 연동 예정.

— Editorial Team