claude-code-hud 0.3.5 → 0.3.7

package/README.md

@@ -6,7 +6,7 @@
 
 ## 한국어
 
-Claude Code로 작업할 때 토큰 사용량, git 상태, 파일 구조를 IDE나 별도 탭 없이 터미널 하나에서 확인할 수 있는 HUD입니다.
+Claude Code로 작업할 때 토큰 사용량, git 상태, 파일 구조, 세션 히스토리를 IDE나 별도 툴 없이 터미널 하나에서 확인할 수 있는 HUD입니다.
 
 <img src="./demo.gif" width="700" alt="demo">
 
@@ -22,6 +22,8 @@ claude                           npx claude-code-hud
 (Claude Code 작업 중...)          (HUD 실시간 표시)
 ```
 
+<img src="./capture.png" width="700" alt="side-by-side terminals">
+
 HUD는 현재 디렉토리를 기준으로 토큰, git, 프로젝트 정보를 자동으로 인식합니다.
 
 ```bash
@@ -33,21 +35,22 @@ tmux split-window -h "npx claude-code-hud"
 ### 설치
 
 ```bash
-# 설치 없이 바로 실행
-npx claude-code-hud
+# 방법1. 전역 설치 (권장)
+> npm install -g claude-code-hud
+> claude-hud
 
-# 전역 설치
-npm install -g claude-code-hud
-claude-hud
+# 방법2. 설치 없이 바로 실행
+> npx claude-code-hud
 ```
 
 ### 기능
 
 **1 TOKENS 탭**
 - 컨텍스트 윈도우 사용량 게이지 (OK / MID / WARN) — 사용량에 따라 헤더 색상 변경
-- Anthropic API 기반 5h / 주간 사용률 (실제 값, 추정치 아님) — `1h 23m` 형식으로 리셋까지 남은 시간 표시
+- Anthropic API 기반 5h / 주간 사용률 — `1h 23m` 형식으로 리셋까지 남은 시간 표시
 - input / output / cache-read / cache-write 토큰 분류
 - 세션 output 통계 (total / avg / peak)
+- `now` — 현재 진행 중인 작업 (마지막 사용자 메시지) 한 줄 표시
 
 **2 PROJECT 탭 — 인터랙티브 파일 브라우저**
 - 디렉토리 트리 (펼치기/접기)
@@ -72,16 +75,20 @@ claude-hud
 - 최근 커밋 히스토리
 - **브랜치 전환** — `b` 키로 로컬 브랜치 목록 표시, 선택해서 바로 checkout
 
+**4 TIMELINE 탭**
+- 현재 세션에서 사용자가 입력한 메시지 히스토리
+- 시간 + 내용 표시, 10개씩 j/k 스크롤
+
 ### 키보드 단축키
 
 | 키 | 동작 |
 |----|------|
-| `1` `2` `3` | 탭 전환 |
+| `1` `2` `3` `4` | 탭 전환 |
 | `j` / `k` | 스크롤 / 트리 이동 |
 | `→` / `Enter` | 디렉토리 펼치기 / 파일 열기 |
 | `←` / `Esc` | 접기 / 소스 뷰어 닫기 |
 | `b` | 브랜치 전환 (GIT 탭) |
-| `d` | 다크 / 라이트 모드 전환 |
+| `d` | 액센트 색상 변경 (blue → red → amber → green → pink) |
 | `r` | 수동 새로고침 |
 | `q` | 종료 |
 
@@ -115,7 +122,7 @@ Claude Code를 한 번 실행하면 `~/.claude/.credentials.json`에 credentials
 
 ## English
 
-A Terminal HUD (Heads-Up Display) for Claude Code — real-time token usage, git status, and interactive project file browser. No IDE, no extra tabs. Just a second terminal window.
+A Terminal HUD (Heads-Up Display) for Claude Code — real-time token usage, git status, interactive project file browser, and session history. No IDE, no extra tabs. Just a second terminal window.
 
 <img src="./demo.gif" width="700" alt="demo">
 
@@ -131,6 +138,8 @@ claude                           npx claude-code-hud
 (working with Claude Code)       (HUD live display)
 ```
 
+<img src="./capture.png" width="700" alt="side-by-side terminals">
+
 ```bash
 # tmux split pane
 cd ~/my-project
@@ -140,13 +149,12 @@ tmux split-window -h "npx claude-code-hud"
 ### Installation
 
 ```bash
-# No install — run directly
-npx claude-code-hud
-
-# Global install
-npm install -g claude-code-hud
-claude-hud
+# Option 1. Global install (recommended)
+> npm install -g claude-code-hud
+> claude-hud
 
+# Option 2. Run directly without install
+> npx claude-code-hud
 ```
 
 ### Features
@@ -156,6 +164,7 @@ claude-hud
 - Real 5h / weekly usage from Anthropic OAuth API — not estimates. Reset time shown as `1h 23m`
 - Input / output / cache-read / cache-write breakdown
 - Session output stats: total / avg / peak per hour
+- `now` line — last user message (current task at a glance)
 
 **2 PROJECT tab — interactive file browser**
 - Navigable directory tree with expand/collapse
@@ -164,6 +173,15 @@ claude-hud
 - 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  M             │    3
+    ▶ hooks/         4f         │    4  render(<App />)
+  ▶ scripts/         6f         │    …  [j/k] scroll  [esc] close
+```
+
 **3 GIT tab**
 - Branch status, ahead/behind remote
 - Changed file list (MOD / ADD / DEL) with real `+N -N` diff counts
@@ -171,16 +189,20 @@ claude-hud
 - Recent commit history
 - **Branch switcher** — press `b` to list local branches and checkout instantly
 
+**4 TIMELINE tab**
+- User message history from the current Claude Code session
+- Timestamped entries, 10 per page, j/k to scroll
+
 ### Keyboard Shortcuts
 
 | Key | Action |
 |-----|--------|
-| `1` `2` `3` | Switch tabs |
+| `1` `2` `3` `4` | Switch tabs |
 | `j` / `k` | Scroll / move tree cursor |
 | `→` / `Enter` | Expand dir / open file |
 | `←` / `Esc` | Collapse / close source viewer |
 | `b` | Branch switcher (GIT tab) |
-| `d` | Toggle dark / light mode |
+| `d` | Cycle accent color (blue → red → amber → green → pink) |
 | `r` | Manual refresh |
 | `q` | Quit |
 
@@ -206,6 +228,7 @@ Run `claude` once to authenticate — credentials are saved to `~/.claude/.crede
 ### How it works
 
 - **Token data**: Watches `~/.claude/projects/*/sessions/*.jsonl` with chokidar — updates instantly on each Claude response
+- **Timeline**: Reads the same JSONL files, filters `type === "user"` entries for message history
 - **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

package/package.json

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

package/scripts/lib/token-reader.mjs

@@ -34,15 +34,23 @@ function getContextWindow(model) {
   return 200000;
 }
 
-/** Find the most recently modified .jsonl session file */
-function findLatestSession() {
+/** Convert cwd to the Claude project directory name (/ replaced with -) */
+function cwdToProjectDir(cwd) {
+  return cwd.replace(/\//g, '-');
+}
+
+/** Find the most recently modified .jsonl session file for the given cwd */
+function findLatestSession(cwd) {
   const projectsDir = path.join(os.homedir(), '.claude', 'projects');
   if (!fs.existsSync(projectsDir)) return null;
 
+  const targetDir = cwd ? cwdToProjectDir(cwd) : null;
+
   let latest = null;
   let latestMtime = 0;
 
-  const projects = fs.readdirSync(projectsDir);
+  const projects = fs.readdirSync(projectsDir)
+    .filter(p => !targetDir || p === targetDir);
   for (const proj of projects) {
     const projDir = path.join(projectsDir, proj);
 
@@ -66,12 +74,13 @@ function findLatestSession() {
   return latest;
 }
 
-/** Collect all JSONL lines across all sessions with their timestamps */
-function readAllLines() {
+/** Collect all JSONL lines for the given cwd (or all projects if no cwd) */
+function readAllLines(cwd) {
   const projectsDir = path.join(os.homedir(), '.claude', 'projects');
   if (!fs.existsSync(projectsDir)) return [];
+  const targetDir = cwd ? cwdToProjectDir(cwd) : null;
   const result = [];
-  for (const proj of fs.readdirSync(projectsDir)) {
+  for (const proj of fs.readdirSync(projectsDir).filter(p => !targetDir || p === targetDir)) {
     const projDir = path.join(projectsDir, proj);
     let files = [];
     try { files = fs.readdirSync(projDir).filter(f => f.endsWith('.jsonl')); } catch { continue; }
@@ -94,15 +103,17 @@ function readAllLines() {
   return result;
 }
 
-export function readTokenHistory() {
-  const allLines = readAllLines();
+export function readTokenHistory(cwd) {
+  const allLines = readAllLines(cwd);
   const now = Date.now();
   const h5  = now - 5  * 60 * 60 * 1000;
   const wk  = now - 7  * 24 * 60 * 60 * 1000;
   const h12 = now - 12 * 60 * 60 * 1000;
+  const todayMidnight = new Date(); todayMidnight.setHours(0, 0, 0, 0);
+  const todayStart = todayMidnight.getTime();
 
   const empty = () => ({ inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } });
-  const acc5h = empty(), accWk = empty();
+  const acc5h = empty(), accWk = empty(), accToday = empty();
 
   // 12 hourly buckets (index 0 = oldest, 11 = most recent)
   const buckets = Array(12).fill(0);
@@ -126,8 +137,9 @@ export function readTokenHistory() {
       acc.cost.cacheWrite += (cw  / M) * pricing.cacheWrite;
     };
 
-    if (ts >= wk) { addTo(accWk); }
-    if (ts >= h5) { addTo(acc5h); }
+    if (ts >= wk)         { addTo(accWk); }
+    if (ts >= h5)         { addTo(acc5h); }
+    if (ts >= todayStart) { addTo(accToday); }
 
     if (ts >= h12) {
       const hoursAgo = (now - ts) / (60 * 60 * 1000);
@@ -136,15 +148,15 @@ export function readTokenHistory() {
     }
   }
 
-  [acc5h, accWk].forEach(acc => {
+  [acc5h, accWk, accToday].forEach(acc => {
     acc.cost.total = acc.cost.input + acc.cost.output + acc.cost.cacheRead + acc.cost.cacheWrite;
   });
 
-  return { last5h: acc5h, lastWeek: accWk, hourlyBuckets: buckets };
+  return { last5h: acc5h, lastWeek: accWk, today: accToday, hourlyBuckets: buckets };
 }
 
-export function readTokenUsage() {
-  const sessionFile = findLatestSession();
+export function readTokenUsage(cwd) {
+  const sessionFile = findLatestSession(cwd);
   if (!sessionFile) {
     return empty();
   }

package/tui/hud.tsx

@@ -218,10 +218,13 @@ async function readSessionTimeline(cwd: string): Promise<TimelineEntry[]> {
   const projectsDir = join(os.homedir(), '.claude', 'projects');
   if (!fs.existsSync(projectsDir)) return [];
 
+  const targetDirName = cwd.replace(/\//g, '-');
+
   let latestFile: string | null = null;
   let latestMtime = 0;
   try {
     for (const projectHash of fs.readdirSync(projectsDir)) {
+      if (projectHash !== targetDirName) continue;
       const sessionDir = join(projectsDir, projectHash);
       if (!fs.statSync(sessionDir).isDirectory()) continue;
       for (const file of fs.readdirSync(sessionDir)) {
@@ -245,6 +248,8 @@ async function readSessionTimeline(cwd: string): Promise<TimelineEntry[]> {
       const obj = JSON.parse(line);
       if (obj.type !== 'user') continue;
       const content = obj.message?.content;
+      // Skip tool_result messages (not direct user prompts)
+      if (Array.isArray(content) && content.some((b: any) => b.type === 'tool_result')) continue;
       const textBlock = Array.isArray(content)
         ? content.find((b: any) => b.type === 'text')
         : null;
@@ -398,6 +403,20 @@ function TokensTab({ usage, history, rateLimits, termWidth, currentActivity, C }
         );
       })()}
 
+      {/* Today summary + sparkline */}
+      <Section title="TODAY" C={C}>
+        <Box>
+          <Text color={C.dimmer}>in  </Text>
+          <Text color={C.brand}  bold>{fmtNum(history.today?.inputTokens ?? 0)}</Text>
+          <Text color={C.dimmer}>   out  </Text>
+          <Text color={C.purple} bold>{fmtNum(history.today?.outputTokens ?? 0)}</Text>
+          <Text color={C.dimmer}>   cache  </Text>
+          <Text color={C.cyan}   bold>{fmtNum((history.today?.cacheReadTokens ?? 0) + (history.today?.cacheWriteTokens ?? 0))}</Text>
+          <Text color={C.dimmer}>   </Text>
+          <Text color={costColor(history.today?.cost?.total ?? 0, C)} bold>{fmtCost(history.today?.cost?.total ?? 0)}</Text>
+        </Box>
+      </Section>
+
       {/* Current activity */}
       {currentActivity && (
         <Box borderStyle="single" borderColor={C.border} paddingX={1}>
@@ -410,7 +429,7 @@ function TokensTab({ usage, history, rateLimits, termWidth, currentActivity, C }
 }
 
 // ── Tab 2: PROJECT ─────────────────────────────────────────────────────────
-function ProjectTab({ info, treeCursor, treeExpanded, selectedFile, fileLines, fileScroll, termWidth, git, C }: any) {
+function ProjectTab({ info, treeCursor, treeExpanded, selectedFile, fileLines, fileScroll, termWidth, contentH, git, C }: any) {
   if (!info) return (
     <Box borderStyle="single" borderColor={C.border} paddingX={1}>
       <Text color={C.dimmer}>scanning project…</Text>
@@ -436,16 +455,26 @@ function ProjectTab({ info, treeCursor, treeExpanded, selectedFile, fileLines, f
     return result;
   }
 
-  const flatNodes: FlatNode[] = info.dirTree ? flatNodes_inner(info.dirTree, 0) : [];
+  const ch = contentH ?? 30;
+  const hasFile = !!selectedFile;
+
+  // Budget: summary=3, tree border+header+marginTop=4, packages≈14 when shown
+  const showPackages = !hasFile && ch >= 28;
+  const packagesBudget = showPackages ? 14 : 0;
+  const maxTreeRows = Math.max(4, ch - 7 - packagesBudget);
+  const treePanelH = Math.max(4, ch - 3 - packagesBudget);
+  const VISIBLE_LINES = Math.max(4, ch - 8);
+
+  // Flatten nodes
+  const allFlatNodes: FlatNode[] = info.dirTree ? flatNodes_inner(info.dirTree, 0) : [];
+  const flatNodes = allFlatNodes.slice(0, maxTreeRows);
   const safeCursor = Math.min(treeCursor, Math.max(0, flatNodes.length - 1));
 
   const totalEndpoints = Object.values(info.endpoints as Record<string, number>).reduce((a: number, b: number) => a + b, 0);
 
   // Split layout when file is open
-  const hasFile = !!selectedFile;
   const TREE_W = hasFile ? Math.max(28, Math.floor(termWidth * 0.36)) : termWidth - 2;
   const SOURCE_W = hasFile ? termWidth - TREE_W - 5 : 0;
-  const VISIBLE_LINES = 22;
 
   // Git changed file sets
   const gitModified = new Set<string>([...(git?.modified ?? []), ...(git?.added ?? []), ...(git?.deleted ?? [])]);
@@ -460,9 +489,9 @@ function ProjectTab({ info, treeCursor, treeExpanded, selectedFile, fileLines, f
   };
 
   return (
-    <Box flexDirection="column">
+    <Box flexDirection="column" height={ch}>
       {/* Summary bar */}
-      <Box borderStyle="single" borderColor={C.border} paddingX={1}>
+      <Box borderStyle="single" borderColor={C.border} paddingX={1} height={3}>
         <Text color={C.text} bold>{info.totalFiles} files</Text>
         <Text color={C.dim}>  │  </Text>
         <Text color={C.text} bold>{info.packages.filter((p: any) => p.depth === 0).length} pkgs</Text>
@@ -474,10 +503,10 @@ function ProjectTab({ info, treeCursor, treeExpanded, selectedFile, fileLines, f
       </Box>
 
       {/* Main area: tree + optional source */}
-      <Box flexDirection="row">
+      <Box flexDirection="row" height={treePanelH}>
 
         {/* ── Tree panel ── */}
-        <Box flexDirection="column" borderStyle="single" borderColor={hasFile ? C.brand : C.border} paddingX={1} width={TREE_W}>
+        <Box flexDirection="column" borderStyle="single" borderColor={hasFile ? C.brand : C.border} paddingX={1} width={TREE_W} height={treePanelH}>
           <Text color={C.dimmer} bold>▸ <Text color={C.text}>TREE</Text></Text>
           <Box marginTop={1} flexDirection="column">
           {flatNodes.length === 0 && <Text color={C.dimmer}>  (empty)</Text>}
@@ -493,7 +522,7 @@ function ProjectTab({ info, treeCursor, treeExpanded, selectedFile, fileLines, f
                 <Box key={`d_${fn.node.path}_${idx}`}>
                   <Text color={C.dimmer}>{indent}</Text>
                   <Text color={isSelected ? C.brand : C.dimmer}>{expIcon}</Text>
-                  <Text color={nameColor} bold={isSelected}>{fn.node.name}/</Text>
+                  <Text color={nameColor} bold={isSelected} wrap="truncate">{fn.node.name}/</Text>
                   <Text color={C.dimmer}>  {fn.node.totalFiles}f</Text>
                 </Box>
               );
@@ -510,7 +539,7 @@ function ProjectTab({ info, treeCursor, treeExpanded, selectedFile, fileLines, f
                 <Box key={`f_${fn.filePath}_${idx}`}>
                   <Text color={C.dimmer}>{indent}</Text>
                   <Text color={isSelected ? C.brand : C.dimmer}>{isOpen ? '▶ ' : '  '}</Text>
-                  <Text color={fileColor} bold={isSelected || isOpen}>{fn.fileName}</Text>
+                  <Text color={fileColor} bold={isSelected || isOpen} wrap="truncate">{fn.fileName}</Text>
                   {gitBadge ? <Text color={gitColor!} bold>{gitBadge}</Text> : null}
                 </Box>
               );
@@ -521,7 +550,7 @@ function ProjectTab({ info, treeCursor, treeExpanded, selectedFile, fileLines, f
 
         {/* ── Source viewer panel ── */}
         {hasFile && (
-          <Box flexDirection="column" borderStyle="single" borderColor={C.brand} paddingX={1} width={SOURCE_W}>
+          <Box flexDirection="column" borderStyle="single" borderColor={C.brand} paddingX={1} width={SOURCE_W} height={treePanelH}>
             <Text color={C.dimmer} bold>▸ <Text color={C.text}>SOURCE  <Text color={C.dim}>{selectedFile}</Text></Text></Text>
             <Box marginTop={1} flexDirection="column">
             {(fileLines as string[]).slice(fileScroll, fileScroll + VISIBLE_LINES).map((line, i) => {
@@ -533,7 +562,7 @@ function ProjectTab({ info, treeCursor, treeExpanded, selectedFile, fileLines, f
                     <Text color={C.dimmer}>{lineNo}</Text>
                   </Box>
                   <Text color={C.dimmer}>  </Text>
-                  <Text color={C.text}>{truncated}</Text>
+                  <Text color={C.text} wrap="truncate">{truncated}</Text>
                 </Box>
               );
             })}
@@ -546,8 +575,8 @@ function ProjectTab({ info, treeCursor, treeExpanded, selectedFile, fileLines, f
       </Box>
 
       {/* Packages (hidden when file open to save space) */}
-      {!hasFile && (
-        <Box flexDirection="column" borderStyle="single" borderColor={C.border} paddingX={1}>
+      {showPackages && (
+        <Box flexDirection="column" borderStyle="single" borderColor={C.border} paddingX={1} height={packagesBudget}>
           <Text color={C.dimmer} bold>▸ <Text color={C.text}>PACKAGES</Text></Text>
           <Box marginTop={1} flexDirection="column">
           {info.packages.slice(0, 10).map((p: any, i: number) => {
@@ -715,8 +744,8 @@ function App() {
   const cwd = process.env.CLAUDE_PROJECT_ROOT || process.cwd();
   const C = makeTheme(accent);
 
-  const [usage,      setUsage]      = useState<any>(readTokenUsage());
-  const [history,    setHistory]    = useState<any>(readTokenHistory());
+  const [usage,      setUsage]      = useState<any>(readTokenUsage(cwd));
+  const [history,    setHistory]    = useState<any>(readTokenHistory(cwd));
   const [git,        setGit]        = useState<any>(readGitInfo(cwd));
   const [project,    setProject]    = useState<ProjectInfo | null>(null);
   const [rateLimits, setRateLimits] = useState<any>(getUsageSync());
@@ -730,6 +759,17 @@ function App() {
   const [fileLines,    setFileLines]    = useState<string[]>([]);
   const [fileScroll,   setFileScroll]   = useState(0);
 
+  // Help overlay state
+  const [showHelp, setShowHelp] = useState(false);
+
+  // Token warning blink state
+  const [blinkOn, setBlinkOn] = useState(true);
+
+  // Loading spinner state
+  const [loading,   setLoading]   = useState(true);
+  const [spinFrame, setSpinFrame] = useState(0);
+  const SPIN = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'];
+
   // Branch switcher state
   const [branchMode,   setBranchMode]   = useState(false);
   const [branchList,   setBranchList]   = useState<string[]>([]);
@@ -741,8 +781,8 @@ function App() {
   const [currentActivity,  setCurrentActivity]  = useState<string>('');
 
   const refresh = useCallback(() => {
-    setUsage(readTokenUsage());
-    setHistory(readTokenHistory());
+    setUsage(readTokenUsage(cwd));
+    setHistory(readTokenHistory(cwd));
     setGit(readGitInfo(cwd));
     setUpdatedAt(Date.now());
     getUsage().then(setRateLimits).catch(() => {});
@@ -757,7 +797,7 @@ function App() {
 
   useEffect(() => {
     // Scan project once
-    scanProject(cwd).then(setProject).catch(() => {});
+    scanProject(cwd).then(p => { setProject(p); setLoading(false); }).catch(() => { setLoading(false); });
     // Initial API usage fetch
     getUsage().then(setRateLimits).catch(() => {});
     // Initial timeline load
@@ -786,11 +826,15 @@ function App() {
           depth: 2, persistent: true, ignoreInitial: true,
           ignored: (p: string) => !p.endsWith('.jsonl'),
         });
-        watcher.on('change', refresh);
+        let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+        watcher.on('change', () => {
+          if (debounceTimer) clearTimeout(debounceTimer);
+          debounceTimer = setTimeout(refresh, 800);
+        });
       });
     }
 
-    const tickInterval = setInterval(() => setTick(t => t + 1), 1000);
+    const tickInterval = setInterval(() => setTick(t => t + 1), 5000);
 
     return () => {
       stdout?.off('resize', onResize);
@@ -800,7 +844,16 @@ function App() {
     };
   }, []);
 
+  useEffect(() => {
+    if (!loading) return;
+    const id = setInterval(() => setSpinFrame(f => f + 1), 80);
+    return () => clearInterval(id);
+  }, [loading]);
+
   useInput((input, key) => {
+    if (input === '?') { setShowHelp(h => !h); return; }
+    if (key.escape && showHelp) { setShowHelp(false); return; }
+
     // Branch switcher intercepts input when active
     if (branchMode) {
       if (input === 'j' || key.downArrow) {
@@ -932,11 +985,28 @@ function App() {
   const uptime = fmtSince(SESSION_START - Date.now() + (Date.now() - SESSION_START));  // forces tick dep
   void tick;
 
+  const ctxPct = usage.contextWindow > 0 ? usage.totalTokens / usage.contextWindow : 0;
+
+  useEffect(() => {
+    if (ctxPct <= 0.85) { setBlinkOn(true); return; }
+    const id = setInterval(() => setBlinkOn(b => !b), 600);
+    return () => clearInterval(id);
+  }, [ctxPct > 0.85]);
+
+  if (termWidth < 60 || termHeight < 15) {
+    return (
+      <Box width={termWidth} height={termHeight} alignItems="center" justifyContent="center" flexDirection="column">
+        <Text color={C.yellow} bold>⚠ terminal too small</Text>
+        <Text color={C.dimmer}>{termWidth}×{termHeight}  —  min 60×15</Text>
+      </Box>
+    );
+  }
+
   return (
-    <Box flexDirection="column">
+    <Box flexDirection="column" height={termHeight}>
 
       {/* ── Header / Tab bar ── */}
-      <Box borderStyle="single" borderColor={usage.contextWindow > 0 && usage.totalTokens / usage.contextWindow > 0.85 ? C.red : usage.contextWindow > 0 && usage.totalTokens / usage.contextWindow > 0.65 ? C.yellow : C.brand} paddingX={1} justifyContent="space-between">
+      <Box height={3} borderStyle="single" borderColor={ctxPct > 0.85 ? (blinkOn ? C.red : C.border) : ctxPct > 0.65 ? C.yellow : C.brand} paddingX={1} justifyContent="space-between">
         <Box>
           <Text color={C.brand} bold>◆ HUD</Text>
           {TAB_NAMES.map((name, i) => (
@@ -961,31 +1031,53 @@ function App() {
         const contentH = Math.max(4, termHeight - 7);
         return (
           <Box flexDirection="column" height={contentH} overflow="hidden">
-            <Box flexDirection="column" marginTop={-scrollY}>
-              {tab === 0 && <TokensTab   usage={usage} history={history} rateLimits={rateLimits} termWidth={termWidth} currentActivity={currentActivity} C={C} />}
-              {tab === 1 && <ProjectTab  info={project} treeCursor={treeCursor} treeExpanded={treeExpanded} selectedFile={selectedFile} fileLines={fileLines} fileScroll={fileScroll} termWidth={termWidth} git={git} C={C} />}
-              {tab === 2 && <GitTab      git={git} termWidth={termWidth} branchMode={branchMode} branchList={branchList} branchCursor={branchCursor} C={C} />}
-              {tab === 3 && <TimelineTab timeline={timeline} timelineScroll={timelineScroll} C={C} />}
-            </Box>
+            {showHelp ? (
+              <Box flexDirection="column" borderStyle="round" borderColor={C.brand} paddingX={2} paddingY={1}>
+                <Text color={C.brand} bold>  Keyboard Shortcuts</Text>
+                <Text> </Text>
+                <Text><Text color={C.dim}>  1 / 2 / 3 / 4    </Text><Text color={C.text}>switch tabs</Text></Text>
+                <Text><Text color={C.dim}>  j / k            </Text><Text color={C.text}>scroll / tree move</Text></Text>
+                <Text><Text color={C.dim}>  → / Enter        </Text><Text color={C.text}>expand dir / open file</Text></Text>
+                <Text><Text color={C.dim}>  ← / Esc          </Text><Text color={C.text}>collapse / close</Text></Text>
+                <Text><Text color={C.dim}>  b                </Text><Text color={C.text}>branch switcher (GIT tab)</Text></Text>
+                <Text><Text color={C.dim}>  d                </Text><Text color={C.text}>cycle accent color</Text></Text>
+                <Text><Text color={C.dim}>  r                </Text><Text color={C.text}>refresh</Text></Text>
+                <Text><Text color={C.dim}>  q / Esc          </Text><Text color={C.text}>quit</Text></Text>
+                <Text><Text color={C.dim}>  ?                </Text><Text color={C.text}>toggle this help</Text></Text>
+                <Text> </Text>
+                <Text color={C.dimmer}>  Korean: ㅓ/ㅏ (j/k)  ㅇ (d)  ㄱ (r)  ㅂ (q)  ㅠ (b)</Text>
+              </Box>
+            ) : loading ? (
+              <Box height={contentH} alignItems="center" justifyContent="center">
+                <Text color={C.brand} bold>{SPIN[spinFrame % SPIN.length]} scanning project…</Text>
+              </Box>
+            ) : (
+              <Box flexDirection="column" height={contentH} marginTop={-scrollY}>
+                {tab === 0 && <TokensTab   usage={usage} history={history} rateLimits={rateLimits} termWidth={termWidth} currentActivity={currentActivity} C={C} />}
+                {tab === 1 && <ProjectTab  info={project} treeCursor={treeCursor} treeExpanded={treeExpanded} selectedFile={selectedFile} fileLines={fileLines} fileScroll={fileScroll} termWidth={termWidth} contentH={contentH - 1} git={git} C={C} />}
+                {tab === 2 && <GitTab      git={git} termWidth={termWidth} branchMode={branchMode} branchList={branchList} branchCursor={branchCursor} C={C} />}
+                {tab === 3 && <TimelineTab timeline={timeline} timelineScroll={timelineScroll} C={C} />}
+              </Box>
+            )}
           </Box>
         );
       })()}
 
       {/* ── Footer row 1: keys ── */}
-      <Box justifyContent="space-between" paddingX={1}>
+      <Box height={1} justifyContent="space-between" paddingX={1}>
         <Box>
           <Text color={C.green}>● </Text>
           <Text color={C.dimmer}>[1/2/3/4] tabs  </Text>
           <Text color={tab === 1 ? C.brand : C.dimmer}>[j/k] {tab === 1 ? 'tree' : 'scroll'}  </Text>
-          <Text color={tab === 1 ? C.brand : C.dimmer}>{tab === 1 ? (selectedFile ? '[esc/←] close  [j/k] scroll  ' : '[enter] open  [→←] expand  ') : ''}</Text>
+          <Text color={tab === 1 ? C.brand : C.dimmer}>{tab === 1 ? (selectedFile ? '[esc] close  ' : '[↵/→←] open  ') : ''}</Text>
           {tab === 2 && !branchMode && <Text color={C.brand}>[b] branch  </Text>}
-          <Text color={C.dimmer}>[r] refresh  [d] color  [q] quit</Text>
+          <Text color={C.dimmer}>[r] refresh  [d] color  [?] help  [q] quit</Text>
         </Box>
         <Text color={C.dimmer}>↻ {since}</Text>
       </Box>
 
       {/* ── Footer row 2: current dir ── */}
-      <Box paddingX={1} borderStyle="single" borderColor={C.brand}>
+      <Box height={3} paddingX={1} borderStyle="single" borderColor={C.brand}>
         <Text color={C.brand} bold>◆ </Text>
         <Text color={C.text} bold>~/{basename(cwd)}</Text>
       </Box>