claude-code-hud 0.2.0

package/README.md

@@ -0,0 +1,161 @@
+# 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    │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 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
+- Changed file list (MOD / ADD / DEL)
+- Per-file diff visualization (+/- bars)
+- Recent commit history with hash, message, and time
+
+---
+
+## Installation
+
+### Option 1 — Claude Code Plugin (recommended)
+
+```bash
+/plugin install letsgojh0810/hud-plugin
+```
+
+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
+```
+
+---
+
+## Usage
+
+Run in a **separate terminal window** or **tmux split pane** while Claude Code is active in another pane:
+
+```bash
+# Separate terminal
+npx claude-code-hud
+
+# tmux split (open right pane with HUD)
+tmux split-window -h "npx claude-code-hud"
+
+# Point to a specific project directory
+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                       |
+
+---
+
+## 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)
+
+---
+
+## Environment Variables
+
+| Variable              | Default     | Description                                         |
+|-----------------------|-------------|-----------------------------------------------------|
+| `CLAUDE_PROJECT_ROOT` | `process.cwd()` | Root directory of the project 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
+
+---
+
+## 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.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/letsgojh0810/hud-plugin.git
+cd hud-plugin
+npm install
+npm run hud        # launches TUI in dev mode
+```
+
+---
+
+## Notes for Korean users
+
+이 플러그인은 Claude Code를 터미널에서 집중적으로 사용하는 개발자를 위해 만들어졌습니다.
+토큰 사용량, Git 상태, 프로젝트 구조를 별도 터미널 창에서 실시간으로 확인할 수 있습니다.
+
+---
+
+## License
+
+MIT — [letsgojh0810](https://github.com/letsgojh0810)

package/bin/claude-hud

@@ -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/bin/start.mjs

@@ -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/commands/hud.md

@@ -0,0 +1,40 @@
+---
+name: hud
+description: Show HUD status — token usage, git info, 5h/7d usage percentages
+---
+
+Run the following and display output in a code block:
+
+```bash
+node -e "
+import('${CLAUDE_PLUGIN_ROOT}/scripts/lib/token-reader.mjs').then(async ({ readTokenUsage }) => {
+  const { readGitInfo } = await import('${CLAUDE_PLUGIN_ROOT}/scripts/lib/git-info.mjs');
+  const { getUsage } = await import('${CLAUDE_PLUGIN_ROOT}/scripts/lib/usage-api.mjs');
+
+  const usage = readTokenUsage();
+  const git = readGitInfo(process.cwd());
+  const limits = await getUsage();
+
+  const ctxPct = Math.round(usage.totalTokens / usage.contextWindow * 100);
+  const model = usage.model.replace('claude-', '').replace(/-202\d+(-\d+)?$/, '');
+
+  console.log('◆ HUD  ─  ' + model);
+  console.log('');
+  console.log('Context  ' + ctxPct + '%  (' + Math.round(usage.totalTokens/1000) + 'K / ' + Math.round(usage.contextWindow/1000) + 'K)');
+  if (limits) {
+    console.log('5h usage ' + limits.fiveHourPercent.toFixed(1) + '%');
+    console.log('wk usage ' + limits.weeklyPercent.toFixed(1) + '%');
+  }
+  console.log('');
+  console.log('Branch   ' + git.branch + (git.ahead ? ' +' + git.ahead : '') + (git.behind ? ' -' + git.behind : ''));
+  if (git.totalChanges > 0) {
+    const changes = [...git.modified.map(f => 'M ' + f), ...git.added.map(f => 'A ' + f), ...git.deleted.map(f => 'D ' + f)].slice(0, 5);
+    changes.forEach(c => console.log('         ' + c));
+  }
+  console.log('');
+  console.log('TUI → run in separate terminal: npx claude-code-hud');
+});
+"
+```
+
+Display the output exactly as-is.

package/hooks/hooks.json

@@ -0,0 +1,29 @@
+{
+  "description": "HUD hooks for Claude Code — token tracking, git status, session summary",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/session-start.mjs\"",
+            "timeout": 8
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/stop-hud.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "claude-code-hud",
+  "version": "0.2.0",
+  "description": "Terminal HUD for Claude Code — real-time token usage, git status, project monitor",
+  "type": "module",
+  "bin": {
+    "claude-hud": "./bin/claude-hud"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "hud",
+    "token",
+    "git",
+    "dashboard",
+    "tui",
+    "terminal"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/letsgojh0810/hud-plugin.git"
+  },
+  "scripts": {
+    "hud": "tsx tui/hud.tsx",
+    "start": "node bin/start.mjs"
+  },
+  "files": [
+    "bin",
+    "tui",
+    "scripts",
+    "commands",
+    "hooks",
+    "skills"
+  ],
+  "dependencies": {
+    "@types/react": "^19.2.14",
+    "chokidar": "^5.0.0",
+    "fast-glob": "^3.3.3",
+    "ink": "^6.8.0",
+    "react": "^19.2.4",
+    "tsx": "^4.21.0"
+  }
+}

package/scripts/full-hud.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * HUD — Full dashboard
+ * Shows complete token breakdown, cost, git status, recent commits.
+ */
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+const { readTokenUsage } = await import(join(__dir, 'lib/token-reader.mjs'));
+const { readGitInfo } = await import(join(__dir, 'lib/git-info.mjs'));
+const { tokenPanel, gitPanel, divider } = await import(join(__dir, 'lib/formatter.mjs'));
+
+const cwd = process.env.CLAUDE_PROJECT_ROOT || process.cwd();
+
+const usage = readTokenUsage();
+const git = readGitInfo(cwd);
+
+const D = divider(54);
+
+const lines = [
+  `◆ HUD  —  Full Dashboard`,
+  D,
+  '',
+  '[TOKENS]',
+  tokenPanel(usage),
+  '',
+  '[GIT]',
+  gitPanel(git),
+  '',
+  D,
+];
+
+process.stdout.write(lines.join('\n') + '\n');

package/scripts/lib/formatter.mjs

@@ -0,0 +1,131 @@
+/**
+ * ASCII/Unicode formatting for HUD output.
+ * Inspired by the toss-blue design system.
+ */
+
+const BLOCK_FULL = '█';
+const BLOCK_EMPTY = '░';
+const SPARK = ['▁','▂','▃','▄','▅','▆','▇','█'];
+
+export function bar(value, max, width = 20) {
+  const pct = Math.min(value / max, 1);
+  const filled = Math.round(pct * width);
+  return BLOCK_FULL.repeat(filled) + BLOCK_EMPTY.repeat(width - filled);
+}
+
+export function pct(value, max) {
+  return Math.round((value / max) * 100);
+}
+
+export function fmtK(n) {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}K`;
+  return String(n);
+}
+
+export function fmtCost(n) {
+  if (n === 0) return '$0.0000';
+  if (n < 0.001) return `$${n.toFixed(5)}`;
+  if (n < 0.01)  return `$${n.toFixed(4)}`;
+  return `$${n.toFixed(3)}`;
+}
+
+export function statusLabel(used, max) {
+  const p = used / max;
+  if (p >= 0.9) return 'CRITICAL';
+  if (p >= 0.75) return 'WARN';
+  if (p >= 0.5) return 'MID';
+  return 'OK';
+}
+
+/** Compact 1-line token bar */
+export function tokenLine(usage) {
+  const { totalTokens, contextWindow, model } = usage;
+  const b = bar(totalTokens, contextWindow, 20);
+  const p = pct(totalTokens, contextWindow);
+  const st = statusLabel(totalTokens, contextWindow);
+  const cost = fmtCost(usage.cost.total);
+  const shortModel = model.replace('claude-', '').replace(/-\d{8}$/, '');
+  return `ctx  ${b}  ${fmtK(totalTokens)}/${fmtK(contextWindow)}  ${p}%  ${st}  ${cost}  [${shortModel}]`;
+}
+
+/** Full token panel (multi-line) */
+export function tokenPanel(usage) {
+  const { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, totalTokens, contextWindow, model, cost } = usage;
+  const W = 24;
+
+  const lines = [];
+  lines.push(`CONTEXT WINDOW`);
+  lines.push(`  ${bar(totalTokens, contextWindow, W)}  ${fmtK(totalTokens)} / ${fmtK(contextWindow)}  ${statusLabel(totalTokens, contextWindow)}`);
+  lines.push('');
+  lines.push('BREAKDOWN');
+
+  const rows = [
+    { label: 'input   ', val: inputTokens,      cost: cost.input      },
+    { label: 'output  ', val: outputTokens,      cost: cost.output     },
+    { label: 'cache·r ', val: cacheReadTokens,  cost: cost.cacheRead  },
+    { label: 'cache·w ', val: cacheWriteTokens, cost: cost.cacheWrite },
+  ];
+
+  for (const r of rows) {
+    const b = bar(r.val, totalTokens || 1, 16);
+    lines.push(`  ${r.label}  ${b}  ${fmtK(r.val).padStart(7)}    ${fmtCost(r.cost)}`);
+  }
+
+  lines.push('');
+  lines.push(`COST TOTAL   ${fmtCost(cost.total)}`);
+  lines.push(`MODEL        ${model}`);
+  return lines.join('\n');
+}
+
+/** Git summary line */
+export function gitLine(git) {
+  if (!git.isRepo) return 'git  (not a git repository)';
+  const branch = `⎇ ${git.branch}`;
+  const changes = git.totalChanges > 0 ? `  ${git.totalChanges} changed` : '  clean';
+  const sync = git.ahead > 0 ? `  ↑${git.ahead}` : git.behind > 0 ? `  ↓${git.behind}` : '';
+  return `git  ${branch}${sync}${changes}`;
+}
+
+/** Full git panel */
+export function gitPanel(git) {
+  if (!git.isRepo) return 'Not a git repository.';
+  const lines = [];
+
+  lines.push(`BRANCH   ⎇ ${git.branch}`);
+  if (git.ahead > 0 || git.behind > 0) {
+    lines.push(`         ↑ ${git.ahead} ahead  ↓ ${git.behind} behind`);
+  }
+  lines.push('');
+
+  const allChanges = [
+    ...git.modified.map(f => ({ st: 'MOD', f })),
+    ...git.added.map(f => ({ st: 'ADD', f })),
+    ...git.deleted.map(f => ({ st: 'DEL', f })),
+  ];
+
+  if (allChanges.length > 0) {
+    lines.push(`CHANGED FILES (${allChanges.length})`);
+    for (const { st, f } of allChanges.slice(0, 10)) {
+      lines.push(`  ${st}  ${f}`);
+    }
+    if (allChanges.length > 10) lines.push(`  ... and ${allChanges.length - 10} more`);
+  } else {
+    lines.push('  working tree clean');
+  }
+
+  if (git.recentCommits.length > 0) {
+    lines.push('');
+    lines.push('RECENT COMMITS');
+    for (const c of git.recentCommits) {
+      lines.push(`  ${c.hash}  ${c.msg}  (${c.time})`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/** Divider line */
+export function divider(width = 52) {
+  return '─'.repeat(width);
+}

package/scripts/lib/git-info.mjs

@@ -0,0 +1,67 @@
+/**
+ * Git status via child_process. No external deps.
+ */
+import { execSync } from 'child_process';
+
+function run(cmd, cwd) {
+  try {
+    return execSync(cmd, { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return '';
+  }
+}
+
+export function readGitInfo(cwd = process.cwd()) {
+  const branch = run('git rev-parse --abbrev-ref HEAD', cwd) || 'unknown';
+  if (branch === 'unknown' || branch === 'HEAD') {
+    return { isRepo: false, branch: 'unknown', ahead: 0, behind: 0, modified: [], added: [], deleted: [], recentCommits: [], totalChanges: 0 };
+  }
+
+  // ahead/behind
+  const aheadBehind = run('git rev-list --left-right --count @{upstream}...HEAD 2>/dev/null || echo "0\t0"', cwd);
+  const [behind = 0, ahead = 0] = aheadBehind.split('\t').map(Number);
+
+  // status
+  const statusOut = run('git status --porcelain', cwd);
+  const modified = [], added = [], deleted = [];
+  for (const line of statusOut.split('\n').filter(Boolean)) {
+    const st = line.slice(0, 2).trim();
+    const file = line.slice(2).trimStart();
+    if (st === 'M' || st === 'MM' || st === 'AM') modified.push(file);
+    else if (st === 'A' || st === '??' ) added.push(file);
+    else if (st === 'D') deleted.push(file);
+  }
+
+  // recent commits
+  const logOut = run('git log --oneline -5 --format="%h|%s|%cr"', cwd);
+  const recentCommits = logOut.split('\n').filter(Boolean).map(l => {
+    const [hash, ...rest] = l.split('|');
+    const time = rest.pop();
+    const msg = rest.join('|');
+    return { hash, msg, time };
+  });
+
+  // diff stats: actual +/- line counts per file
+  const numstatOut = run('git diff --numstat HEAD 2>/dev/null', cwd);
+  const diffStats = {};
+  for (const line of numstatOut.split('\n').filter(Boolean)) {
+    const [addStr, delStr, ...fileParts] = line.split('\t');
+    const file = fileParts.join('\t');
+    const add = parseInt(addStr) || 0;
+    const del = parseInt(delStr) || 0;
+    if (file) diffStats[file] = { add, del };
+  }
+
+  return {
+    isRepo: true,
+    branch,
+    ahead: Number(ahead),
+    behind: Number(behind),
+    modified,
+    added,
+    deleted,
+    recentCommits,
+    diffStats,
+    totalChanges: modified.length + added.length + deleted.length,
+  };
+}