claude-code-hud 0.2.0 → 0.3.1

package/README.md

@@ -1,161 +1,203 @@
 # claude-code-hud
 
-A Terminal HUD (Heads-Up Display) for Claude Code — real-time token usage, git status, and project info in a separate terminal window or tmux pane.
-
-```
-┌────────────────────────────────────────────────────────┐
-│ ◆  HUD  [1 TOKENS] 2 PROJECT  3 GIT    sonnet-4-6      │
-├────────────────────────────────────────────────────────┤
-│ CONTEXT WINDOW                                          │
-│ ████████████████░░░░░░░░░░░  34%  67K / 200K  OK        │
-├────────────────────────────────────────────────────────┤
-│ USAGE WINDOW  (Anthropic API)                           │
-│ 5h ████████████████░░░░  62.0%  resets in 4h            │
-│ wk ████░░░░░░░░░░░░░░░░  15.0%  resets in 144h          │
-├────────────────────────────────────────────────────────┤
-│ INPUT   ██████░░░░░░░░░░░░░░  48.2K  $0.0145            │
-│ OUTPUT  ██░░░░░░░░░░░░░░░░░░   8.1K  $0.0122            │
-│ CACHE   ████████████░░░░░░░░  52.0K  $0.0047            │
-│                                              $0.0314    │
-└────────────────────────────────────────────────────────┘
-```
+[한국어](#한국어) | [English](#english)
 
 ---
 
-## Features
+## 한국어
 
-### TOKENS tab
-- Context window usage gauge (█░ progress bar) with percentage and token counts
-- 5-hour and weekly usage window from Anthropic API (real %)
-- Input / output / cache-read / cache-write breakdown with cost
-- Processing sparkline (▁▂▃▄▅▆▇█) over recent turns
-- Model name display
+Claude Code로 작업할 때 토큰 사용량, git 상태, 파일 구조를 IDE나 별도 탭 없이 터미널 하나에서 확인할 수 있는 HUD입니다.
 
-### PROJECT tab
-- Total file count, package count, detected endpoints
-- Package dependency tree (├─ └─)
-- Endpoint summary (GET / POST / PUT / DELETE counts)
-- Alerts and anomalies
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ ◆  HUD  [1 TOKENS] 2 PROJECT  3 GIT                    sonnet-4-6  ·  up 4m  │
+├──────────────────────────────────────────────────────────────────────────────┤
+│ CONTEXT WINDOW                                                               │
+│ ████████████████████░░░░░░░░░░░░░░░░░░░░░░░  46%  92K / 200K  OK             │
+├──────────────────────────────────────────────────────────────────────────────┤
+│ USAGE WINDOW  (Anthropic API)                                                │
+│ 5h ████████░░░░░░░░░░░░░░░░░░░░  28.0%  resets in 3h                         │
+│ wk ███░░░░░░░░░░░░░░░░░░░░░░░░░   9.0%  resets in 148h                       │
+├──────────────────────────────────────────────────────────────────────────────┤
+│ TOKENS  (this session)                                                       │
+│ input         ░░░░░░░░░░░░░░░░░░░░░░░░    4.8K   0%                          │
+│ output        ░░░░░░░░░░░░░░░░░░░░░░░░  188.5K   0%                          │
+│ cache-read    ████████████████████████   51.5M 100%                          │
+│ cache-write   ██░░░░░░░░░░░░░░░░░░░░░░    3.8M   7%                          │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
 
-### GIT tab
-- Current branch, ahead/behind counts
-- Changed file list (MOD / ADD / DEL)
-- Per-file diff visualization (+/- bars)
-- Recent commit history with hash, message, and time
+### 사용법
 
----
+터미널 두 개를 열고 같은 프로젝트 디렉토리에서 실행하면 됩니다.
 
-## Installation
+```
+터미널 A                         터미널 B
+─────────────────────────────    ─────────────────────────────
+cd ~/my-project                  cd ~/my-project
+claude                           npx claude-code-hud
+(Claude Code 작업 중...)          (HUD 실시간 표시)
+```
 
-### Option 1 — Claude Code Plugin (recommended)
+HUD는 현재 디렉토리를 기준으로 토큰, git, 프로젝트 정보를 자동으로 인식합니다.
 
 ```bash
-/plugin install letsgojh0810/hud-plugin
+# tmux로 한 화면에서 split
+cd ~/my-project
+tmux split-window -h "npx claude-code-hud"
 ```
 
-Then use the `/hud` command inside Claude Code to get a status snapshot.
-
-### Option 2 — npx (no install required)
+### 설치
 
 ```bash
+# 설치 없이 바로 실행
 npx claude-code-hud
-```
-
-Runs the full interactive TUI in your current terminal. Open a separate terminal window or tmux pane first.
 
-### Option 3 — npm global install
-
-```bash
+# 전역 설치
 npm install -g claude-code-hud
 claude-hud
+
+# 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 in another pane:
+**2 PROJECT 탭 — 인터랙티브 파일 브라우저**
+- 디렉토리 트리 (펼치기/접기)
+- 파일 선택 시 소스 코드 뷰어 (split 패널)
+- 패키지 의존성 트리
+- API 엔드포인트 감지
 
-```bash
-# Separate terminal
-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 (open right pane with HUD)
-tmux split-window -h "npx claude-code-hud"
+**3 GIT 탭**
+- 현재 브랜치, ahead/behind 카운트
+- 변경 파일 목록 (MOD / ADD / DEL)
+- 파일별 diff 시각화 (+/- 바)
+- 최근 커밋 히스토리
 
-# Point to a specific project directory
-CLAUDE_PROJECT_ROOT=/path/to/project npx claude-code-hud
-```
+### 키보드 단축키
 
----
+| 키 | 동작 |
+|----|------|
+| `1` `2` `3` | 탭 전환 |
+| `j` / `k` | 스크롤 / 트리 이동 |
+| `→` / `Enter` | 디렉토리 펼치기 / 파일 열기 |
+| `←` / `Esc` | 접기 / 소스 뷰어 닫기 |
+| `d` | 다크 / 라이트 모드 전환 |
+| `r` | 수동 새로고침 |
+| `q` | 종료 |
 
-## Keyboard Shortcuts
+### 요구사항
 
-| Key   | Action                     |
-|-------|----------------------------|
-| `1`   | Switch to TOKENS tab       |
-| `2`   | Switch to PROJECT tab      |
-| `3`   | Switch to GIT tab          |
-| `j`   | Scroll down                |
-| `k`   | Scroll up                  |
-| `d`   | Toggle dark / light mode   |
-| `q`   | Quit                       |
+- Node.js 18+
+- Claude Code 설치 및 로그인 (토큰 데이터 수집)
+- Claude Pro / Max 플랜 권장 (5h / 주간 사용률 표시)
+- Git (GIT 탭 사용 시)
 
 ---
 
-## Requirements
+## English
 
-- **Node.js 18+**
-- **Claude Code** installed and active (for token data from JSONL session files)
-- **Claude Pro or Max plan** recommended for full 5h/7d usage window data from Anthropic API
-- Git (for git status features)
+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.
 
----
+So I built this. Two terminals. One for Claude Code, one for the HUD. That's it.
 
-## Environment Variables
+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.
 
-| Variable              | Default     | Description                                         |
-|-----------------------|-------------|-----------------------------------------------------|
-| `CLAUDE_PROJECT_ROOT` | `process.cwd()` | Root directory of the project to monitor        |
+### Usage
 
----
+Open two terminals in the same project directory.
 
-## How it works
+```
+Terminal A                       Terminal B
+─────────────────────────────    ─────────────────────────────
+cd ~/my-project                  cd ~/my-project
+claude                           npx claude-code-hud
+(working with Claude Code)       (HUD live display)
+```
 
-- **Token data**: Parses `~/.claude/projects/<hash>/sessions/*.jsonl` in real-time using chokidar file watching
-- **Usage window**: Reads Anthropic API usage limits (5h / weekly) when available
-- **Git status**: Polls `simple-git` every 3–5 seconds for branch, diff, and commit info
-- **Project scan**: Uses `fast-glob` to scan files and detect packages/endpoints once, then caches
+The HUD automatically detects your current directory and shows token, git, and project info for that project.
 
----
+```bash
+# tmux split pane
+cd ~/my-project
+tmux split-window -h "npx claude-code-hud"
+```
+
+### Installation
+
+```bash
+# No install — run directly
+npx claude-code-hud
 
-## Color Theme
+# Global install
+npm install -g claude-code-hud
+claude-hud
 
-Toss Blue (`#3182F6`) based palette with full dark and light mode support.
+# Claude Code plugin
+/plugin install letsgojh0810/hud-plugin
+```
 
-Dark mode uses `#0E1117` background. Light mode uses `#FFFFFF`.
-Toggle with the `d` key at any time.
+### Features
 
----
+**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
 
-## Development
+**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)
 
-```bash
-git clone https://github.com/letsgojh0810/hud-plugin.git
-cd hud-plugin
-npm install
-npm run hud        # launches TUI in dev mode
-```
+**3 GIT tab**
+- Branch status, ahead/behind remote
+- Changed file list (MOD / ADD / DEL) with real `+N -N` diff counts
+- Recent commit history
 
----
+### Keyboard Shortcuts
 
-## Notes for Korean users
+| 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 |
 
-이 플러그인은 Claude Code를 터미널에서 집중적으로 사용하는 개발자를 위해 만들어졌습니다.
-토큰 사용량, Git 상태, 프로젝트 구조를 별도 터미널 창에서 실시간으로 확인할 수 있습니다.
+### Requirements
 
----
+- Node.js 18+
+- Claude Code installed and authenticated
+- Claude Pro or Max plan recommended (for real 5h / weekly usage %)
+- Git (optional, for GIT tab)
 
-## License
+### 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
+
+---
 
 MIT — [letsgojh0810](https://github.com/letsgojh0810)

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "claude-code-hud",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Terminal HUD for Claude Code — real-time token usage, git status, project monitor",
   "type": "module",
   "bin": {
-    "claude-hud": "./bin/claude-hud"
+    "claude-hud": "./bin/claude-hud.js"
   },
   "keywords": [
     "claude",

package/tui/hud.tsx

@@ -66,13 +66,13 @@ type DirNode = {
   fileCount: number;    // direct files only
   totalFiles: number;   // recursive total
   children: DirNode[];
+  files: string[];      // direct file names
   expanded: boolean;
 };
 
-type FlatNode = {
-  node: DirNode;
-  depth: number;
-};
+type FlatNode =
+  | { type: 'dir';  node: DirNode; depth: number }
+  | { type: 'file'; filePath: string; fileName: string; depth: number };
 
 // ── Project scanner ────────────────────────────────────────────────────────
 type ProjectInfo = {
@@ -100,7 +100,7 @@ async function scanProject(cwd: string): Promise<ProjectInfo> {
 
   // Build directory tree
   function buildTree(filePaths: string[]): DirNode {
-    const root: DirNode = { name: '.', path: '', fileCount: 0, totalFiles: 0, children: [], expanded: true };
+    const root: DirNode = { name: '.', path: '', fileCount: 0, totalFiles: 0, children: [], files: [], expanded: true };
     for (const file of filePaths) {
       const parts = file.split('/');
       let cur = root;
@@ -108,12 +108,13 @@ async function scanProject(cwd: string): Promise<ProjectInfo> {
         const seg = parts[i];
         let child = cur.children.find(c => c.name === seg);
         if (!child) {
-          child = { name: seg, path: parts.slice(0, i + 1).join('/'), fileCount: 0, totalFiles: 0, children: [], expanded: false };
+          child = { name: seg, path: parts.slice(0, i + 1).join('/'), fileCount: 0, totalFiles: 0, children: [], files: [], expanded: false };
           cur.children.push(child);
         }
         cur = child;
       }
       cur.fileCount++;
+      cur.files.push(parts[parts.length - 1]);
     }
     function calcTotal(n: DirNode): number {
       n.totalFiles = n.fileCount + n.children.reduce((s, c) => s + calcTotal(c), 0);
@@ -169,10 +170,15 @@ function flattenTree(node: DirNode, depth: number, expanded: Record<string, bool
   const result: FlatNode[] = [];
   const sorted = [...node.children].sort((a, b) => b.totalFiles - a.totalFiles);
   for (const child of sorted) {
-    result.push({ node: child, depth });
+    result.push({ type: 'dir', node: child, depth });
     const isExp = expanded[child.path] ?? false;
-    if (isExp && child.children.length > 0) {
+    if (isExp) {
       result.push(...flattenTree(child, depth + 1, expanded));
+      const sortedFiles = [...child.files].sort();
+      for (const f of sortedFiles) {
+        const filePath = child.path ? `${child.path}/${f}` : f;
+        result.push({ type: 'file', filePath, fileName: f, depth: depth + 1 });
+      }
     }
   }
   return result;
@@ -302,43 +308,49 @@ function TokensTab({ usage, history, rateLimits, termWidth, C }: any) {
 }
 
 // ── Tab 2: PROJECT ─────────────────────────────────────────────────────────
-function ProjectTab({ info, treeCursor, treeExpanded, termWidth, C }: any) {
+function ProjectTab({ info, treeCursor, treeExpanded, selectedFile, fileLines, fileScroll, termWidth, C }: any) {
   if (!info) return (
     <Box borderStyle="single" borderColor={C.border} paddingX={1}>
       <Text color={C.dimmer}>scanning project…</Text>
     </Box>
   );
 
-  // Flatten visible tree using treeExpanded from props (closure)
+  // Flatten visible tree using treeExpanded from props
   function flatNodes_inner(node: DirNode, depth: number): FlatNode[] {
     const result: FlatNode[] = [];
     const sorted = [...node.children].sort((a, b) => b.totalFiles - a.totalFiles);
     for (const child of sorted) {
-      result.push({ node: child, depth });
+      result.push({ type: 'dir', node: child, depth });
       const isExp = treeExpanded[child.path] ?? false;
-      if (isExp && child.children.length > 0) {
+      if (isExp) {
         result.push(...flatNodes_inner(child, depth + 1));
+        const sortedFiles = [...child.files].sort();
+        for (const f of sortedFiles) {
+          const filePath = child.path ? `${child.path}/${f}` : f;
+          result.push({ type: 'file', filePath, fileName: f, depth: depth + 1 });
+        }
       }
     }
     return result;
   }
 
-  const flatNodes = info.dirTree ? flatNodes_inner(info.dirTree, 0) : [];
+  const flatNodes: FlatNode[] = info.dirTree ? flatNodes_inner(info.dirTree, 0) : [];
   const safeCursor = Math.min(treeCursor, Math.max(0, flatNodes.length - 1));
 
-  const EXT_LABELS: Record<string, string> = {
-    '.ts': 'TypeScript', '.tsx': 'TypeScript', '.js': 'JavaScript', '.jsx': 'JavaScript',
-    '.py': 'Python', '.go': 'Go', '.java': 'Java', '.rs': 'Rust',
-    '.json': 'JSON', '.md': 'Markdown', '.css': 'CSS', '.html': 'HTML',
-  };
-  const extGroups: Record<string, number> = {};
-  for (const [ext, cnt] of Object.entries(info.byExt as Record<string, number>)) {
-    const label = EXT_LABELS[ext] || 'Other';
-    extGroups[label] = (extGroups[label] || 0) + cnt;
-  }
-  const sortedExts = Object.entries(extGroups).sort((a, b) => b[1] - a[1]).slice(0, 4);
   const totalEndpoints = Object.values(info.endpoints as Record<string, number>).reduce((a: number, b: number) => a + b, 0);
-  const langs = sortedExts.slice(0, 2).map(([l]) => l).join(' / ');
+
+  // 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;
+
+  const EXT_COLOR: Record<string, string> = {
+    '.ts': C.brand, '.tsx': C.brand, '.js': C.cyan, '.jsx': C.cyan,
+    '.py': C.yellow, '.go': C.cyan, '.java': C.yellow, '.rs': C.red,
+    '.json': C.dim, '.md': C.green, '.css': C.purple, '.html': C.yellow,
+    '.mjs': C.cyan, '.cjs': C.cyan,
+  };
 
   return (
     <Box flexDirection="column">
@@ -346,54 +358,95 @@ function ProjectTab({ info, treeCursor, treeExpanded, termWidth, C }: any) {
       <Box borderStyle="single" borderColor={C.border} paddingX={1}>
         <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} packages</Text>
-        <Text color={C.dim}>  │  </Text>
-        <Text color={C.text} bold>~{totalEndpoints} endpoints</Text>
-        <Text color={C.dim}>  │  {langs}</Text>
+        <Text color={C.text} bold>{info.packages.filter((p: any) => p.depth === 0).length} pkgs</Text>
+        <Text color={C.dim}>  │  ~{totalEndpoints} endpoints  │  </Text>
+        {hasFile
+          ? <Text color={C.brand}>{selectedFile}</Text>
+          : <Text color={C.dimmer}>[enter] open file  [←] collapse</Text>
+        }
       </Box>
 
-      {/* Directory tree */}
-      <Box flexDirection="column" borderStyle="single" borderColor={C.border} paddingX={1}>
-        <Text color={C.dim} bold>TREE  <Text color={C.dimmer}>[j/k] move  [enter/→←] expand</Text></Text>
-        {flatNodes.length === 0 && <Text color={C.dimmer}>  (empty)</Text>}
-        {flatNodes.map((fn, idx) => {
-          const isSelected = idx === safeCursor;
-          const isExp = treeExpanded[fn.node.path] ?? false;
-          const hasChildren = fn.node.children.length > 0;
-          const indent = '  '.repeat(fn.depth);
-          const expIcon = hasChildren ? (isExp ? '▼ ' : '▶ ') : '  ';
-          const nameColor = isSelected ? C.brand : fn.depth === 0 ? C.text : C.dim;
-          return (
-            <Box key={`${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={C.dimmer}>  {fn.node.totalFiles}f</Text>
-              {isSelected && fn.node.fileCount > 0 && (
-                <Text color={C.dimmer}>  ({fn.node.fileCount} direct)</Text>
-              )}
-            </Box>
-          );
-        })}
-      </Box>
+      {/* Main area: tree + optional source */}
+      <Box flexDirection="row">
+
+        {/* ── Tree panel ── */}
+        <Box flexDirection="column" borderStyle="single" borderColor={hasFile ? C.brand : C.border} paddingX={1} width={TREE_W}>
+          <Text color={C.dim} bold>TREE</Text>
+          {flatNodes.length === 0 && <Text color={C.dimmer}>  (empty)</Text>}
+          {flatNodes.map((fn, idx) => {
+            const isSelected = idx === safeCursor;
+            const indent = '  '.repeat(fn.depth);
+            if (fn.type === 'dir') {
+              const isExp = treeExpanded[fn.node.path] ?? false;
+              const hasChildren = fn.node.children.length > 0 || fn.node.files.length > 0;
+              const expIcon = hasChildren ? (isExp ? '▼ ' : '▶ ') : '  ';
+              const nameColor = isSelected ? C.brand : fn.depth === 0 ? C.text : C.dim;
+              return (
+                <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={C.dimmer}>  {fn.node.totalFiles}f</Text>
+                </Box>
+              );
+            } else {
+              const ext = fn.fileName.includes('.') ? '.' + fn.fileName.split('.').pop()! : '';
+              const fileColor = isSelected ? C.brand : (EXT_COLOR[ext] ?? C.text);
+              const isOpen = selectedFile === fn.filePath;
+              return (
+                <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>
+                </Box>
+              );
+            }
+          })}
+        </Box>
 
-      {/* Packages */}
-      <Box flexDirection="column" borderStyle="single" borderColor={C.border} paddingX={1}>
-        <Text color={C.dim} bold>PACKAGES</Text>
-        {info.packages.slice(0, 12).map((p: any, i: number) => {
-          const isRoot = p.depth === 0;
-          const nextIsRoot = i + 1 < info.packages.length && info.packages[i + 1].depth === 0;
-          const isLastInGroup = nextIsRoot || i === Math.min(11, info.packages.length - 1);
-          const prefix = isRoot ? '' : (isLastInGroup ? '└─ ' : '├─ ');
-          return (
-            <Box key={i}>
-              <Text color={C.dimmer}>{isRoot ? '' : '   '}{prefix}</Text>
-              <Text color={isRoot ? C.brand : C.text}>{p.name}</Text>
-              <Text color={C.dimmer}>  {p.version}</Text>
-            </Box>
-          );
-        })}
+        {/* ── Source viewer panel ── */}
+        {hasFile && (
+          <Box flexDirection="column" borderStyle="single" borderColor={C.brand} paddingX={1} width={SOURCE_W}>
+            <Text color={C.brand} bold>SOURCE  <Text color={C.dim}>{selectedFile}</Text></Text>
+            {(fileLines as string[]).slice(fileScroll, fileScroll + VISIBLE_LINES).map((line, i) => {
+              const lineNo = fileScroll + i + 1;
+              const truncated = line.length > SOURCE_W - 6 ? line.slice(0, SOURCE_W - 7) + '…' : line;
+              return (
+                <Box key={i}>
+                  <Box width={4} justifyContent="flex-end">
+                    <Text color={C.dimmer}>{lineNo}</Text>
+                  </Box>
+                  <Text color={C.dimmer}>  </Text>
+                  <Text color={C.text}>{truncated}</Text>
+                </Box>
+              );
+            })}
+            {(fileLines as string[]).length > VISIBLE_LINES && (
+              <Text color={C.dimmer}>  ↕ {fileScroll + 1}–{Math.min(fileScroll + VISIBLE_LINES, fileLines.length)} / {fileLines.length} lines  [j/k] scroll  [esc] close</Text>
+            )}
+          </Box>
+        )}
       </Box>
+
+      {/* Packages (hidden when file open to save space) */}
+      {!hasFile && (
+        <Box flexDirection="column" borderStyle="single" borderColor={C.border} paddingX={1}>
+          <Text color={C.dim} bold>PACKAGES</Text>
+          {info.packages.slice(0, 10).map((p: any, i: number) => {
+            const isRoot = p.depth === 0;
+            const nextIsRoot = i + 1 < info.packages.length && info.packages[i + 1].depth === 0;
+            const isLast = nextIsRoot || i === Math.min(9, info.packages.length - 1);
+            const prefix = isRoot ? '' : (isLast ? '└─ ' : '├─ ');
+            return (
+              <Box key={i}>
+                <Text color={C.dimmer}>{isRoot ? '' : '   '}{prefix}</Text>
+                <Text color={isRoot ? C.brand : C.text}>{p.name}</Text>
+                <Text color={C.dimmer}>  {p.version}</Text>
+              </Box>
+            );
+          })}
+        </Box>
+      )}
     </Box>
   );
 }
@@ -502,6 +555,11 @@ function App() {
   const [treeCursor,   setTreeCursor]   = useState(0);
   const [treeExpanded, setTreeExpanded] = useState<Record<string, boolean>>({});
 
+  // Source viewer state
+  const [selectedFile, setSelectedFile] = useState<string | null>(null);
+  const [fileLines,    setFileLines]    = useState<string[]>([]);
+  const [fileScroll,   setFileScroll]   = useState(0);
+
   const refresh = useCallback(() => {
     setUsage(readTokenUsage());
     setHistory(readTokenHistory());
@@ -516,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);
@@ -544,53 +605,84 @@ function App() {
   }, []);
 
   useInput((input, key) => {
-    if (input === 'q' || key.escape) process.exit(0);
+    if (input === 'q' || input === 'ㅂ') process.exit(0);
+
+    // Escape: close file viewer first, then quit
+    if (key.escape) {
+      if (selectedFile) { setSelectedFile(null); setFileLines([]); setFileScroll(0); return; }
+      process.exit(0);
+    }
+
     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 (tab === 1) {
+    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) {
         const flat = project?.dirTree ? flattenTree(project.dirTree, 0, treeExpanded) : [];
         setTreeCursor(c => Math.min(c + 1, flat.length - 1));
       } else {
         setScrollY(s => Math.min(s + 1, 20));
       }
     }
-    if (input === 'k' || key.upArrow) {
-      if (tab === 1) setTreeCursor(c => Math.max(c - 1, 0));
-      else setScrollY(s => Math.max(s - 1, 0));
+    if (input === 'k' || input === 'ㅏ' || key.upArrow) {
+      if (tab === 1 && selectedFile) {
+        setFileScroll(s => Math.max(s - 1, 0));
+      } else if (tab === 1) {
+        setTreeCursor(c => Math.max(c - 1, 0));
+      } else {
+        setScrollY(s => Math.max(s - 1, 0));
+      }
     }
 
-    // Enter / Space — toggle expand in tree
+    // Enter / Space — dir: toggle expand, file: open source viewer
     if ((key.return || input === ' ') && tab === 1 && project?.dirTree) {
       const flat = flattenTree(project.dirTree, 0, treeExpanded);
-      const selected = flat[treeCursor];
-      if (selected && selected.node.children.length > 0) {
-        const path = selected.node.path;
+      const sel = flat[treeCursor];
+      if (!sel) return;
+      if (sel.type === 'dir') {
+        const path = sel.node.path;
         setTreeExpanded(prev => ({ ...prev, [path]: !(prev[path] ?? false) }));
+      } else {
+        // file: toggle source viewer
+        if (selectedFile === sel.filePath) {
+          setSelectedFile(null); setFileLines([]); setFileScroll(0);
+        } else {
+          try {
+            const content = fs.readFileSync(join(cwd, sel.filePath), 'utf-8');
+            setFileLines(content.split('\n'));
+          } catch {
+            setFileLines(['(cannot read file)']);
+          }
+          setSelectedFile(sel.filePath);
+          setFileScroll(0);
+        }
       }
     }
 
-    // Arrow right = expand, left = collapse
+    // Arrow right = expand dir, left = collapse
     if (key.rightArrow && tab === 1 && project?.dirTree) {
       const flat = flattenTree(project.dirTree, 0, treeExpanded);
-      const selected = flat[treeCursor];
-      if (selected) setTreeExpanded(prev => ({ ...prev, [selected.node.path]: true }));
+      const sel = flat[treeCursor];
+      if (sel?.type === 'dir') setTreeExpanded(prev => ({ ...prev, [sel.node.path]: true }));
     }
     if (key.leftArrow && tab === 1) {
+      if (selectedFile) { setSelectedFile(null); setFileLines([]); setFileScroll(0); return; }
       if (project?.dirTree) {
         const flat = flattenTree(project.dirTree, 0, treeExpanded);
-        const selected = flat[treeCursor];
-        if (selected) setTreeExpanded(prev => ({ ...prev, [selected.node.path]: false }));
+        const sel = flat[treeCursor];
+        if (sel?.type === 'dir') setTreeExpanded(prev => ({ ...prev, [sel.node.path]: false }));
       }
     }
   });
@@ -622,7 +714,7 @@ function App() {
       {/* ── Content (with scroll offset) ── */}
       <Box flexDirection="column" marginTop={-scrollY}>
         {tab === 0 && <TokensTab  usage={usage} history={history} rateLimits={rateLimits} termWidth={termWidth} C={C} />}
-        {tab === 1 && <ProjectTab info={project} treeCursor={treeCursor} treeExpanded={treeExpanded} termWidth={termWidth} C={C} />}
+        {tab === 1 && <ProjectTab info={project} treeCursor={treeCursor} treeExpanded={treeExpanded} selectedFile={selectedFile} fileLines={fileLines} fileScroll={fileScroll} termWidth={termWidth} C={C} />}
         {tab === 2 && <GitTab     git={git} termWidth={termWidth} C={C} />}
       </Box>
 
@@ -632,7 +724,7 @@ function App() {
           <Text color={C.green}>● </Text>
           <Text color={C.dimmer}>[1/2/3] 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 ? '[enter/→←] expand  ' : ''}</Text>
+          <Text color={tab === 1 ? C.brand : C.dimmer}>{tab === 1 ? (selectedFile ? '[esc/←] close  [j/k] scroll  ' : '[enter] open  [→←] expand  ') : ''}</Text>
           <Text color={C.dimmer}>[r] refresh  [d] theme  [q] quit</Text>
         </Box>
         <Text color={C.dimmer}>↻ {since}</Text>