claude-code-hud 0.3.0 → 0.3.1

package/README.md

@@ -1,19 +1,25 @@
 # claude-code-hud
 
-A Terminal HUD (Heads-Up Display) for Claude Code — real-time token usage, git status, and interactive project file browser in a separate terminal window or tmux pane.
+[한국어](#한국어) | [English](#english)
+
+---
+
+## 한국어
+
+Claude Code로 작업할 때 토큰 사용량, git 상태, 파일 구조를 IDE나 별도 탭 없이 터미널 하나에서 확인할 수 있는 HUD입니다.
 
 ```
 ┌──────────────────────────────────────────────────────────────────────────────┐
-│ ◆  HUD  [1 TOKENS] 2 PROJECT  3 GIT                    sonnet-4-6  ·  up 4m │
+│ ◆  HUD  [1 TOKENS] 2 PROJECT  3 GIT                    sonnet-4-6  ·  up 4m  │
 ├──────────────────────────────────────────────────────────────────────────────┤
-│ CONTEXT WINDOW                                                                │
+│ CONTEXT WINDOW                                                               │
 │ ████████████████████░░░░░░░░░░░░░░░░░░░░░░░  46%  92K / 200K  OK             │
 ├──────────────────────────────────────────────────────────────────────────────┤
-│ USAGE WINDOW  (Anthropic API)                                                 │
+│ USAGE WINDOW  (Anthropic API)                                                │
 │ 5h ████████░░░░░░░░░░░░░░░░░░░░  28.0%  resets in 3h                         │
 │ wk ███░░░░░░░░░░░░░░░░░░░░░░░░░   9.0%  resets in 148h                       │
 ├──────────────────────────────────────────────────────────────────────────────┤
-│ TOKENS  (this session)                                                        │
+│ TOKENS  (this session)                                                       │
 │ input         ░░░░░░░░░░░░░░░░░░░░░░░░    4.8K   0%                          │
 │ output        ░░░░░░░░░░░░░░░░░░░░░░░░  188.5K   0%                          │
 │ cache-read    ████████████████████████   51.5M 100%                          │
@@ -21,159 +27,177 @@ A Terminal HUD (Heads-Up Display) for Claude Code — real-time token usage, git
 └──────────────────────────────────────────────────────────────────────────────┘
 ```
 
----
-
-## Features
+### 사용법
 
-### 1 TOKENS tab
-- Context window usage gauge with percentage (OK / MID / WARN)
-- **5h and weekly usage** from Anthropic OAuth API — real percentages, not estimates
-- Input / output / cache-read / cache-write token breakdown with bars
-- Output tokens sparkline (▁▂▃▄▅▆▇█) over the last 12 hours
-- Model name and session uptime
-
-### 2 PROJECT tab — interactive file browser
-- Directory tree with `▶`/`▼` expand/collapse
-- **Source file viewer** — select any file and read its contents in a split panel
-- File count per directory, extension-based color coding
-- Package dependency tree from `package.json`
-- API endpoint detection (GET / POST / PUT / DELETE / PATCH)
+터미널 두 개를 열고 같은 프로젝트 디렉토리에서 실행하면 됩니다.
 
 ```
-TREE                            │ SOURCE  src/index.ts
-▼ src/            23f           │  1  import React from 'react'
-  ▼ components/    8f           │  2  import { render } from 'ink'
-    Header.tsx   ◀ open         │  3
-  ▶ hooks/         4f           │  4  render(<App />)
-▶ scripts/         6f           │  …  [j/k] scroll  [esc] close
+터미널 A                         터미널 B
+─────────────────────────────    ─────────────────────────────
+cd ~/my-project                  cd ~/my-project
+claude                           npx claude-code-hud
+(Claude Code 작업 중...)          (HUD 실시간 표시)
 ```
 
-### 3 GIT tab
-- Current branch, ahead/behind remote counts
-- Changed file list (MOD / ADD / DEL)
-- Per-file diff visualization with real `+N -N` line counts
-- Recent commit history with hash, message, and relative time
-
----
-
-## Installation
-
-### Option 1 — npx (no install required)
+HUD는 현재 디렉토리를 기준으로 토큰, git, 프로젝트 정보를 자동으로 인식합니다.
 
 ```bash
-npx claude-code-hud
+# tmux로 한 화면에서 split
+cd ~/my-project
+tmux split-window -h "npx claude-code-hud"
 ```
 
-### Option 2 — npm global install
+### 설치
 
 ```bash
+# 설치 없이 바로 실행
+npx claude-code-hud
+
+# 전역 설치
 npm install -g claude-code-hud
 claude-hud
-```
 
-### Option 3 — Claude Code Plugin
-
-```bash
+# Claude Code 플러그인
 /plugin install letsgojh0810/hud-plugin
 ```
 
----
+### 기능
 
-## Usage
+**1 TOKENS 탭**
+- 컨텍스트 윈도우 사용량 게이지 (OK / MID / WARN)
+- Anthropic API 기반 5h / 주간 사용률 (실제 값, 추정치 아님)
+- input / output / cache-read / cache-write 토큰 분류
+- 최근 12시간 output 토큰 sparkline
 
-Run in a **separate terminal window** or **tmux split pane** while Claude Code is active:
+**2 PROJECT 탭 — 인터랙티브 파일 브라우저**
+- 디렉토리 트리 (펼치기/접기)
+- 파일 선택 시 소스 코드 뷰어 (split 패널)
+- 패키지 의존성 트리
+- API 엔드포인트 감지
 
-```bash
-# Separate terminal — run from your project directory
-cd ~/my-project
-npx claude-code-hud
+```
+TREE                            │ SOURCE  src/index.ts
+▼ src/            23f           │  1  import React from 'react'
+  ▼ components/    8f           │  2  import { render } from 'ink'
+    Header.tsx   ◀ open         │  3
+  ▶ hooks/         4f           │  4  render(<App />)
+▶ scripts/         6f           │  …  [j/k] scroll  [esc] close
+```
 
-# tmux split pane
-tmux split-window -h "cd ~/my-project && npx claude-code-hud"
+**3 GIT 탭**
+- 현재 브랜치, ahead/behind 카운트
+- 변경 파일 목록 (MOD / ADD / DEL)
+- 파일별 diff 시각화 (+/- 바)
+- 최근 커밋 히스토리
 
-# Specify project root explicitly
-CLAUDE_PROJECT_ROOT=/path/to/project npx claude-code-hud
-```
+### 키보드 단축키
+
+| 키 | 동작 |
+|----|------|
+| `1` `2` `3` | 탭 전환 |
+| `j` / `k` | 스크롤 / 트리 이동 |
+| `→` / `Enter` | 디렉토리 펼치기 / 파일 열기 |
+| `←` / `Esc` | 접기 / 소스 뷰어 닫기 |
+| `d` | 다크 / 라이트 모드 전환 |
+| `r` | 수동 새로고침 |
+| `q` | 종료 |
+
+### 요구사항
+
+- Node.js 18+
+- Claude Code 설치 및 로그인 (토큰 데이터 수집)
+- Claude Pro / Max 플랜 권장 (5h / 주간 사용률 표시)
+- Git (GIT 탭 사용 시)
 
 ---
 
-## Keyboard Shortcuts
+## English
 
-### Global
+When working with Claude Code in the terminal, I kept running into the same friction: how many tokens are left? what's the git status? what does this file structure look like? — answering any of these meant switching to another app or opening more terminal tabs.
 
-| Key     | Action                   |
-|---------|--------------------------|
-| `1`     | Switch to TOKENS tab     |
-| `2`     | Switch to PROJECT tab    |
-| `3`     | Switch to GIT tab        |
-| `d`     | Toggle dark / light mode |
-| `r`     | Manual refresh           |
-| `q`     | Quit                     |
+So I built this. Two terminals. One for Claude Code, one for the HUD. That's it.
 
-### TOKENS / GIT tab
+A Terminal HUD (Heads-Up Display) for Claude Code — real-time token usage, git status, and interactive project file browser in a separate terminal window or tmux pane.
 
-| Key     | Action       |
-|---------|--------------|
-| `j` / `↓` | Scroll down |
-| `k` / `↑` | Scroll up   |
+### Usage
 
-### PROJECT tab — file browser
+Open two terminals in the same project directory.
 
-| Key          | Action                        |
-|--------------|-------------------------------|
-| `j` / `↓`   | Move cursor down              |
-| `k` / `↑`   | Move cursor up                |
-| `→` / `Enter`| Expand directory              |
-| `←`          | Collapse directory / close viewer |
-| `Enter` on file | Open source viewer        |
-| `Esc`        | Close source viewer           |
-| `j` / `k`   | Scroll source (when open)     |
+```
+Terminal A                       Terminal B
+─────────────────────────────    ─────────────────────────────
+cd ~/my-project                  cd ~/my-project
+claude                           npx claude-code-hud
+(working with Claude Code)       (HUD live display)
+```
 
----
+The HUD automatically detects your current directory and shows token, git, and project info for that project.
 
-## Requirements
+```bash
+# tmux split pane
+cd ~/my-project
+tmux split-window -h "npx claude-code-hud"
+```
 
-- **Node.js 18+**
-- **Claude Code** installed and authenticated (for token data)
-- **Claude Pro or Max plan** recommended — enables real 5h/weekly usage % from Anthropic API
-- Git (optional, for GIT tab)
+### Installation
 
----
+```bash
+# No install — run directly
+npx claude-code-hud
 
-## Environment Variables
+# Global install
+npm install -g claude-code-hud
+claude-hud
 
-| Variable              | Default         | Description                              |
-|-----------------------|-----------------|------------------------------------------|
-| `CLAUDE_PROJECT_ROOT` | `process.cwd()` | Project root directory to monitor        |
+# Claude Code plugin
+/plugin install letsgojh0810/hud-plugin
+```
 
----
+### Features
 
-## How it works
+**1 TOKENS tab**
+- Context window usage gauge (OK / MID / WARN)
+- Real 5h / weekly usage from Anthropic OAuth API — not estimates
+- Input / output / cache-read / cache-write breakdown
+- Output tokens sparkline over the last 12 hours
 
-- **Token data**: Watches `~/.claude/projects/*/sessions/*.jsonl` with chokidar — updates instantly when Claude responds
-- **Usage window**: Calls `api.anthropic.com/api/oauth/usage` with your local Claude credentials (same as Claude Code uses) — cached 5 min
-- **Git status**: Polls git every 3 seconds
-- **Project scan**: One-time fast-glob scan on startup, `r` to rescan
+**2 PROJECT tab — interactive file browser**
+- Navigable directory tree with expand/collapse
+- Source file viewer in a split panel
+- Package dependency tree from `package.json`
+- API endpoint detection (GET / POST / PUT / DELETE / PATCH)
 
----
+**3 GIT tab**
+- Branch status, ahead/behind remote
+- Changed file list (MOD / ADD / DEL) with real `+N -N` diff counts
+- Recent commit history
 
-## Color Theme
+### Keyboard Shortcuts
 
-Toss Blue (`#3182F6`) based palette. Full dark and light mode — toggle with `d`.
+| Key | Action |
+|-----|--------|
+| `1` `2` `3` | Switch tabs |
+| `j` / `k` | Scroll / move tree cursor |
+| `→` / `Enter` | Expand dir / open file |
+| `←` / `Esc` | Collapse / close source viewer |
+| `d` | Toggle dark / light mode |
+| `r` | Manual refresh |
+| `q` | Quit |
 
----
+### Requirements
 
-## Development
+- Node.js 18+
+- Claude Code installed and authenticated
+- Claude Pro or Max plan recommended (for real 5h / weekly usage %)
+- Git (optional, for GIT tab)
 
-```bash
-git clone https://github.com/letsgojh0810/hud-plugin.git
-cd hud-plugin
-npm install
-npm run hud
-```
+### How it works
 
----
+- **Token data**: Watches `~/.claude/projects/*/sessions/*.jsonl` with chokidar — updates instantly on each Claude response
+- **Usage window**: Calls `api.anthropic.com/api/oauth/usage` using local Claude credentials — cached 5 min
+- **Git**: Polls every 3 seconds
+- **Project scan**: One-time fast-glob scan on startup, `r` to rescan
 
-## License
+---
 
 MIT — [letsgojh0810](https://github.com/letsgojh0810)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hud",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Terminal HUD for Claude Code — real-time token usage, git status, project monitor",
   "type": "module",
   "bin": {

package/tui/hud.tsx

@@ -574,7 +574,10 @@ function App() {
     // Initial API usage fetch
     getUsage().then(setRateLimits).catch(() => {});
 
-    const onResize = () => setTermWidth(stdout?.columns ?? 80);
+    const onResize = () => {
+      process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+      setTermWidth(stdout?.columns ?? 80);
+    };
     stdout?.on('resize', onResize);
 
     const poll = setInterval(refresh, 3000);
@@ -602,7 +605,7 @@ function App() {
   }, []);
 
   useInput((input, key) => {
-    if (input === 'q') process.exit(0);
+    if (input === 'q' || input === 'ㅂ') process.exit(0);
 
     // Escape: close file viewer first, then quit
     if (key.escape) {
@@ -613,17 +616,17 @@ function App() {
     if (input === '1') { setTab(0); setScrollY(0); }
     if (input === '2') { setTab(1); setScrollY(0); }
     if (input === '3') { setTab(2); setScrollY(0); }
-    if (input === 'd') setDark(d => !d);
+    if (input === 'd' || input === 'ㅇ') setDark(d => !d);
 
     // r = manual refresh
-    if (input === 'r') {
+    if (input === 'r' || input === 'ㄱ') {
       refresh();
       setProject(null);
       setSelectedFile(null); setFileLines([]); setFileScroll(0);
       scanProject(cwd).then(p => { setProject(p); setTreeCursor(0); }).catch(() => {});
     }
 
-    if (input === 'j' || key.downArrow) {
+    if (input === 'j' || input === 'ㅓ' || key.downArrow) {
       if (tab === 1 && selectedFile) {
         setFileScroll(s => Math.min(s + 1, Math.max(0, fileLines.length - 5)));
       } else if (tab === 1) {
@@ -633,7 +636,7 @@ function App() {
         setScrollY(s => Math.min(s + 1, 20));
       }
     }
-    if (input === 'k' || key.upArrow) {
+    if (input === 'k' || input === 'ㅏ' || key.upArrow) {
       if (tab === 1 && selectedFile) {
         setFileScroll(s => Math.max(s - 1, 0));
       } else if (tab === 1) {

package/bin/claude-hud

@@ -1,31 +0,0 @@
-#!/usr/bin/env node
-/**
- * claude-code-hud entry point
- * Launches the Ink TUI for Claude Code token/git monitoring
- */
-import { spawn } from 'child_process';
-import { existsSync } from 'fs';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-
-const __dir = dirname(fileURLToPath(import.meta.url));
-const hudFile = join(__dir, '..', 'tui', 'hud.tsx');
-
-// Use local tsx if available, otherwise try PATH
-const localTsx = join(__dir, '..', 'node_modules', '.bin', 'tsx');
-const tsxBin = existsSync(localTsx) ? localTsx : 'tsx';
-
-const proc = spawn(tsxBin, [hudFile], {
-  stdio: 'inherit',
-  env: { ...process.env, CLAUDE_PROJECT_ROOT: process.env.CLAUDE_PROJECT_ROOT || process.cwd() },
-});
-
-proc.on('exit', (code) => process.exit(code ?? 0));
-proc.on('error', (err) => {
-  if (err.code === 'ENOENT') {
-    console.error('tsx not found. Run: npm install -g tsx');
-  } else {
-    console.error('Failed to start HUD:', err.message);
-  }
-  process.exit(1);
-});