HUD

HUD 스킬

상태 표시줄을 위해 OMC HUD(헤드업 디스플레이)를 구성합니다.

참고: 이 가이드의 모든 ~/.claude/... 경로는 CLAUDE_CONFIG_DIR 환경 변수가 설정된 경우 해당 변수를 존중합니다.

빠른 명령어

명령어	설명
/oh-my-claudecode:hud	현재 HUD 상태 표시(필요시 자동 설정)
/oh-my-claudecode:hud setup	HUD 상태 표시줄 설치/복구
/oh-my-claudecode:hud minimal	미니멀 디스플레이로 전환
/oh-my-claudecode:hud focused	포커스드 디스플레이로 전환(기본값)
/oh-my-claudecode:hud full	풀 디스플레이로 전환
/oh-my-claudecode:hud status	상세 HUD 상태 표시

자동 설정

/oh-my-claudecode:hud 또는 /oh-my-claudecode:hud setup을 실행하면 시스템이 자동으로:

1. ~/.claude/hud/omc-hud.mjs가 존재하는지 확인
2. ~/.claude/settings.json에 statusLine이 구성되어 있는지 확인
3. 누락된 경우 HUD 래퍼 스크립트 생성 및 설정 구성
4. 상태를 보고하고 변경 사항이 있으면 Claude Code 재시작을 요청

중요: 인수가 setup이거나 ~/.claude/hud/omc-hud.mjs에 HUD 스크립트가 없으면, 아래 지침을 사용하여 직접 HUD 파일을 반드시 생성해야 합니다.

설정 지침(이 명령어 실행)

1단계: 설정이 필요한지 확인:

node -e "const p=require('path'),f=require('fs'),d=process.env.CLAUDE_CONFIG_DIR||p.join(require('os').homedir(),'.claude');console.log(f.existsSync(p.join(d,'hud','omc-hud.mjs'))?'EXISTS':'MISSING')"

2단계: 플러그인이 설치되었는지 확인:

node -e "const p=require('path'),f=require('fs'),d=process.env.CLAUDE_CONFIG_DIR||p.join(require('os').homedir(),'.claude'),b=p.join(d,'plugins','cache','omc','oh-my-claudecode');try{const v=f.readdirSync(b).filter(x=>/^\d/.test(x)).sort((a,c)=>a.localeCompare(c,void 0,{numeric:true}));if(v.length===0){console.log('Plugin not installed - run: /plugin install oh-my-claudecode');process.exit()}const l=v[v.length-1],h=p.join(b,l,'dist','hud','index.js');console.log('Version:',l);console.log(f.existsSync(h)?'READY':'NOT_FOUND - try reinstalling: /plugin install oh-my-claudecode')}catch{console.log('Plugin not installed - run: /plugin install oh-my-claudecode')}"

3단계: omc-hud.mjs가 MISSING이거나 인수가 setup이면, 정식 템플릿에서 HUD 래퍼와 그 의존성을 설치합니다:

HUD_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hud"
mkdir -p "$HUD_DIR/lib"
cp "${CLAUDE_PLUGIN_ROOT}/scripts/lib/hud-wrapper-template.txt" "$HUD_DIR/omc-hud.mjs"
cp "${CLAUDE_PLUGIN_ROOT}/scripts/lib/config-dir.mjs" "$HUD_DIR/lib/config-dir.mjs"

중요: 항상 scripts/lib/hud-wrapper-template.txt의 정식 템플릿에서 복사하세요. 래퍼 내용을 인라인으로 작성하지 마십시오. 템플릿은 단일 진실 공급원이며 드리프트 테스트(src/__tests__/hud-wrapper-template-sync.test.ts, src/__tests__/paths-consistency.test.ts)로 보호됩니다.

4단계: 실행 가능하게 설정(Unix 전용, Windows는 건너뜁니다):

node -e "if(process.platform==='win32'){console.log('Skipped (Windows)')}else{require('fs').chmodSync(require('path').join(process.env.CLAUDE_CONFIG_DIR||require('path').join(require('os').homedir(),'.claude'),'hud','omc-hud.mjs'),0o755);console.log('Done')}"

5단계: HUD를 사용하도록 settings.json 업데이트:

${CLAUDE_CONFIG_DIR:-~/.claude}/settings.json을 읽은 다음 statusLine 필드를 업데이트/추가합니다.

중요: 명령어에 ~를 사용하지 마십시오. Unix에서는 $HOME을 사용하여 경로를 여러 머신에서 이식 가능하게 유지하십시오. Windows에서는 셸 명령어가 ~를 확장하지 않으므로 절대 경로를 사용하십시오.

Windows를 사용 중인 경우 먼저 올바른 경로를 확인하십시오:

node -e "const p=require('path').join(require('os').homedir(),'.claude','hud','omc-hud.mjs').split(require('path').sep).join('/');console.log(JSON.stringify(p))"

중요: 명령어 경로는 모든 플랫폼에서 반드시 슬래시(/)를 사용해야 합니다. Claude Code는 bash를 통해 statusLine 명령어를 실행하며, 백슬래시를 이스케이프 문자로 해석하여 경로가 손상됩니다.

그런 다음 statusLine 필드를 설정합니다. Unix에서는 이식 가능하게 유지되어 다음과 같이 보여야 합니다:

{
  "statusLine": {
    "type": "command",
    "command": "node ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hud/omc-hud.mjs"
  }
}

Windows에서는 경로가 백슬래시 대신 슬래시를 사용합니다:

{
  "statusLine": {
    "type": "command",
    "command": "node C:/Users/username/.claude/hud/omc-hud.mjs"
  }
}

편집 도구를 사용하여 다른 설정을 유지하면서 이 필드를 추가/업데이트하십시오.

6단계: 이전 HUD 스크립트 정리(있는 경우):

node -e "const p=require('path'),f=require('fs'),d=process.env.CLAUDE_CONFIG_DIR||p.join(require('os').homedir(),'.claude'),t=p.join(d,'hud','omc-hud.js');try{if(f.existsSync(t)){f.unlinkSync(t);console.log('Removed legacy omc-hud.js')}else{console.log('No legacy script found')}}catch{}"

7단계: 변경 사항을 적용하려면 Claude Code를 재시작하도록 사용자에게 알립니다.

디스플레이 프리셋

미니멀(Minimal)

필수 요소만 표시합니다:

[OMC] ralph | todos:2/5

포커스드(Focused, 기본값)

모든 관련 요소를 표시합니다:

[OMC] branch:main | ralph:3/10 | US-002 | skill:planner | ctx:67% | agents:2 | bg:3/5 | todos:2/5

풀(Full)

멀티라인 에이전트 세부 정보를 포함한 모든 것을 표시합니다:

[OMC] repo:oh-my-claudecode branch:main | ralph:3/10 | US-002 (2/5) | ctx:[████░░]67% | agents:3 | bg:3/5 | todos:2/5
├─ O architect    2m   analyzing architecture patterns...
├─ e explore     45s   searching for test files
└─ s executor     1m   implementing validation logic

멀티라인 에이전트 표시

에이전트가 실행 중일 때 HUD는 별도 줄에 상세 정보를 표시합니다:

• 트리 문자(├─, └─)는 시각적 계층 구조를 표시
• 에이전트 코드(O, e, s)는 모델 계층 색상으로 에이전트 유형을 나타냄
• 지속 시간은 각 에이전트가 실행된 시간을 표시
• 설명은 각 에이전트가 수행 중인 작업을 표시(최대 45자)

표시 요소

요소	설명
[OMC]	모드 식별자
repo:name	Git 저장소 이름(청록색)
branch:name	Git 브랜치 이름(청록색)
ralph:3/10	Ralph 루프 반복/최대값
US-002	현재 PRD 스토리 ID
skill:name	마지막으로 활성화된 스킬(청록색)
ctx:67%	컨텍스트 창 사용량
agents:2	실행 중인 하위 에이전트 수
bg:3/5	백그라운드 작업 슬롯
todos:2/5	할 일 완료 상태

색상 코딩

• 초록색: 정상/양호
• 노란색: 경고(컨텍스트 >70%, ralph >7)
• 빨간색: 심각(컨텍스트 >85%, ralph 최대값)

구성 위치

HUD 구성은 ~/.claude/settings.json의 omcHud 키 아래에 저장됩니다(또는 CLAUDE_CONFIG_DIR이 설정된 경우 사용자 정의 구성 디렉토리).

레거시 구성 위치(더 이상 사용되지 않음): ~/.claude/.omc/hud-config.json

수동 구성

구성 파일을 수동으로 편집할 수 있습니다. 각 옵션은 개별적으로 설정할 수 있으며, 설정되지 않은 값은 기본값을 사용합니다.

{
  "preset": "focused",
  "elements": {
    "omcLabel": true,
    "updateNotification": true,
    "ralph": true,
    "autopilot": true,
    "prdStory": true,
    "activeSkills": true,
    "lastSkill": true,
    "contextBar": true,
    "agents": true,
    "agentsFormat": "multiline",
    "backgroundTasks": true,
    "todos": true,
    "thinking": true,
    "thinkingFormat": "text",
    "permissionStatus": false,
    "apiKeySource": false,
    "profile": true,
    "promptTime": true,
    "sessionHealth": true,
    "useBars": true,
    "showCallCounts": true,
    "callCountsFormat": "auto",
    "safeMode": true,
    "maxOutputLines": 4
  },
  "thresholds": {
    "contextWarning": 70,
    "contextCompactSuggestion": 80,
    "contextCritical": 85,
    "ralphWarning": 7
  },
  "staleTaskThresholdMinutes": 30,
  "contextLimitWarning": {
    "threshold": 80,
    "autoCompact": false
  }
}

callCountsFormat

호출 횟수 배지 아이콘 스타일을 제어합니다:

• "auto" (기본값): macOS/Linux에서는 이모지, Windows/WSL에서는 ASCII
• "emoji": 강제 🔧 🤖 ⚡
• "ascii": 강제 T: A: S:

safeMode

safeMode가 true(기본값)이면 HUD는 ANSI 코드를 제거하고 ASCII 전용 출력을 사용하여 동시 업데이트 중 터미널 렌더링 손상을 방지합니다. 이는 Windows와 터미널 멀티플렉서 사용 시 특히 중요합니다.

agentsFormat 옵션

• count: agents:2
• codes: agents:Oes(모델 계층 대소문자로 유형 코드화)
• codes-duration: agents:O(2m)es(지속 시간이 포함된 코드)
• detailed: agents:[architect(2m),explore,exec]
• descriptions: O:analyzing code | e:searching(코드 + 수행 중인 작업)
• tasks: analyzing code, searching...
• multiline: 각 에이전트에 대한 전체 세부 정보가 별도 줄에 표시되는 멀티라인 디스플레이

문제 해결

HUD가 표시되지 않는 경우:

1. /oh-my-claudecode:hud setup을 실행하여 자동 설치 및 구성
2. 설정 완료 후 Claude Code 재시작
3. 여전히 작동하지 않으면 /oh-my-claudecode:omc-doctor를 실행하여 전체 진단

레거시 문자열 형식 마이그레이션: 이전 OMC 버전은 statusLine을 일반 문자열(예: "~/.claude/hud/omc-hud.mjs")로 작성했습니다. 최신 Claude Code(v2.1+)는 객체 형식이 필요합니다. 설치 프로그램 또는 /oh-my-claudecode:hud setup을 실행하면 레거시 문자열이 올바른 객체 형식으로 자동 마이그레이션됩니다:

{
  "statusLine": {
    "type": "command",
    "command": "node ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hud/omc-hud.mjs"
  }
}

Node 24+ 호환성: HUD 래퍼 스크립트는 node:path가 아닌 node:os에서 homedir을 가져옵니다. SyntaxError: The requested module 'path' does not provide an export named 'homedir' 오류가 발생하면 설치 프로그램을 다시 실행하여 omc-hud.mjs를 재생성하십시오.

수동 확인:

• HUD 스크립트: ~/.claude/hud/omc-hud.mjs
• 설정: ~/.claude/settings.json에 type과 command 필드가 있는 객체로 statusLine이 구성되어 있어야 함

---

HUD는 활성 세션 중 약 300ms마다 자동으로 업데이트됩니다.