claude-code-hud 0.2.0 → 0.3.0

package/README.md

@@ -1,89 +1,97 @@
 # 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.
+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.
 
 ```
-┌────────────────────────────────────────────────────────┐
-│ ◆  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    │
-└────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ ◆  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%                          │
+└──────────────────────────────────────────────────────────────────────────────┘
 ```
 
 ---
 
 ## 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
-
-### PROJECT tab
-- Total file count, package count, detected endpoints
-- Package dependency tree (├─ └─)
-- Endpoint summary (GET / POST / PUT / DELETE counts)
-- Alerts and anomalies
-
-### GIT tab
-- Current branch, ahead/behind counts
+### 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
+```
+
+### 3 GIT tab
+- Current branch, ahead/behind remote counts
 - Changed file list (MOD / ADD / DEL)
-- Per-file diff visualization (+/- bars)
-- Recent commit history with hash, message, and time
+- Per-file diff visualization with real `+N -N` line counts
+- Recent commit history with hash, message, and relative time
 
 ---
 
 ## Installation
 
-### Option 1 — Claude Code Plugin (recommended)
+### Option 1 — npx (no install required)
 
 ```bash
-/plugin install letsgojh0810/hud-plugin
+npx claude-code-hud
 ```
 
-Then use the `/hud` command inside Claude Code to get a status snapshot.
-
-### Option 2 — npx (no install required)
+### Option 2 — npm global install
 
 ```bash
-npx claude-code-hud
+npm install -g claude-code-hud
+claude-hud
 ```
 
-Runs the full interactive TUI in your current terminal. Open a separate terminal window or tmux pane first.
-
-### Option 3 — npm global install
+### Option 3 — Claude Code Plugin
 
 ```bash
-npm install -g claude-code-hud
-claude-hud
+/plugin install letsgojh0810/hud-plugin
 ```
 
 ---
 
 ## Usage
 
-Run in a **separate terminal window** or **tmux split pane** while Claude Code is active in another pane:
+Run in a **separate terminal window** or **tmux split pane** while Claude Code is active:
 
 ```bash
-# Separate terminal
+# Separate terminal — run from your project directory
+cd ~/my-project
 npx claude-code-hud
 
-# tmux split (open right pane with HUD)
-tmux split-window -h "npx claude-code-hud"
+# tmux split pane
+tmux split-window -h "cd ~/my-project && npx claude-code-hud"
 
-# Point to a specific project directory
+# Specify project root explicitly
 CLAUDE_PROJECT_ROOT=/path/to/project npx claude-code-hud
 ```
 
@@ -91,50 +99,67 @@ CLAUDE_PROJECT_ROOT=/path/to/project npx claude-code-hud
 
 ## 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                       |
+### Global
+
+| 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                     |
+
+### TOKENS / GIT tab
+
+| Key     | Action       |
+|---------|--------------|
+| `j` / `↓` | Scroll down |
+| `k` / `↑` | Scroll up   |
+
+### PROJECT tab — file browser
+
+| 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)     |
 
 ---
 
 ## Requirements
 
 - **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)
+- **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)
 
 ---
 
 ## Environment Variables
 
-| Variable              | Default     | Description                                         |
-|-----------------------|-------------|-----------------------------------------------------|
-| `CLAUDE_PROJECT_ROOT` | `process.cwd()` | Root directory of the project to monitor        |
+| Variable              | Default         | Description                              |
+|-----------------------|-----------------|------------------------------------------|
+| `CLAUDE_PROJECT_ROOT` | `process.cwd()` | Project root directory to monitor        |
 
 ---
 
 ## How it works
 
-- **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
+- **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
 
 ---
 
 ## Color Theme
 
-Toss Blue (`#3182F6`) based palette with full dark and light mode support.
-
-Dark mode uses `#0E1117` background. Light mode uses `#FFFFFF`.
-Toggle with the `d` key at any time.
+Toss Blue (`#3182F6`) based palette. Full dark and light mode — toggle with `d`.
 
 ---
 
@@ -144,18 +169,11 @@ Toggle with the `d` key at any time.
 git clone https://github.com/letsgojh0810/hud-plugin.git
 cd hud-plugin
 npm install
-npm run hud        # launches TUI in dev mode
+npm run hud
 ```
 
 ---
 
-## Notes for Korean users
-
-이 플러그인은 Claude Code를 터미널에서 집중적으로 사용하는 개발자를 위해 만들어졌습니다.
-토큰 사용량, Git 상태, 프로젝트 구조를 별도 터미널 창에서 실시간으로 확인할 수 있습니다.
-
----
-
 ## License
 
 MIT — [letsgojh0810](https://github.com/letsgojh0810)

package/bin/claude-hud.js

@@ -0,0 +1,31 @@
+#!/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);
+});

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "claude-code-hud",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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());
@@ -544,7 +602,14 @@ function App() {
   }, []);
 
   useInput((input, key) => {
-    if (input === 'q' || key.escape) process.exit(0);
+    if (input === 'q') 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); }
@@ -554,11 +619,14 @@ function App() {
     if (input === 'r') {
       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 (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 {
@@ -566,31 +634,52 @@ function App() {
       }
     }
     if (input === 'k' || key.upArrow) {
-      if (tab === 1) setTreeCursor(c => Math.max(c - 1, 0));
-      else setScrollY(s => Math.max(s - 1, 0));
+      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 +711,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 +721,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>