oh-my-hi 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.1.3] - 2026-03-31
+
+### Added
+- Dashboard guide document (GUIDE.md) with detailed walkthrough of each section
+- Update instructions in README and Help page (CLI + in-session commands)
+- Shell-styled command block in Help page
+- Privacy section in README
+- Improved `--data-only` and `--enable-auto` descriptions with bookmark/refresh tips
+- Version display in sidebar now auto-injected from package.json at build time
+
 ## [0.1.2] - 2026-03-31
 
 ### Added

package/GUIDE.md

@@ -0,0 +1,163 @@
+# Dashboard Guide
+
+A guide to each section of the oh-my-hi dashboard.
+
+
+## Sidebar
+
+The left sidebar provides navigation, workspace selection, and date range filtering.
+
+### Workspace Selector
+
+Switch between **Global** (your entire Claude Code configuration) and **per-project** scopes. Each scope shows only the harness components and usage data relevant to that workspace.
+
+### Date Range
+
+Filter all usage data by time period:
+
+| Button | Description |
+|--------|-------------|
+| **7d** | Last 7 days (today inclusive) |
+| **30d** | Last 30 days (today inclusive) |
+| **All** | All collected data since first session |
+| **📅** | Custom date range picker |
+
+Hover over a non-active button to preview the date range in a tooltip. The active range is shown below the buttons.
+
+### Search
+
+Type to filter sidebar items by name. Matches are highlighted across all categories.
+
+### Categories
+
+Below the main navigation, each harness component category is listed with an item count badge. Click to expand and see individual items; click an item to view its detail page.
+
+---
+
+## Main Pages
+
+### 📊 Harness (Overview)
+
+The landing page showing a high-level summary of your harness activity.
+
+| Section | Description |
+|---------|-------------|
+| **Stat Cards** | Total usage, skill calls, agent calls, and command invocations for the selected period. Each card shows the change percentage vs. the previous period. |
+| **Category Distribution** | Donut chart showing the proportion of skills, agents, and commands. |
+| **Daily Trend** | Line chart of daily activity (skills + agents + commands combined). |
+| **Popular Skills** | Top 5 most-used skills ranked by call count. |
+| **Activity Heatmap** | GitHub-style calendar heatmap of daily activity intensity. |
+| **Recent Activity** | Timeline of the 10 most recent skill, agent, and command invocations. |
+| **Unused Items** | Skills and agents that were registered but never called in the selected period. |
+
+---
+
+### 🪙 Tokens (Overview)
+
+Token usage analytics across all Claude Code sessions.
+
+| Section | Description |
+|---------|-------------|
+| **Stat Cards** | Total tokens, input tokens, output tokens, cache tokens — each with period-over-period change. |
+| **Estimated Cost** | Total cost, daily average cost, and per-model cost cards. Based on Anthropic API token pricing (not actual CLI subscription billing). |
+| **Cost Calculation** | Expandable section with the pricing formula, collapsible model pricing table (per 1M tokens), and a link to [anthropic.com/pricing](https://www.anthropic.com/pricing). |
+| **Model Distribution** | Donut chart of token usage by model. |
+| **Daily Token Usage** | Line chart of daily token consumption trend. |
+| **Token Activity** | Calendar heatmap of daily token usage intensity. |
+| **Token Usage by Model** | Table breakdown: input, output, cache, total tokens, and estimated cost per model. |
+| **Token Insights** | Auto-generated analysis cards covering cache efficiency, response efficiency, model usage, cost breakdown, daily patterns, and peak hours. |
+
+#### Cost Calculation Formula
+
+```
+Cost = (Input × input price + Output × output price
+      + Cache Read × cache read price + Cache Write × cache write price) ÷ 1,000,000
+```
+
+Prices are per 1M tokens (USD), sourced from Anthropic's official API pricing. Claude Code CLI is subscription-based, so this estimate is for reference only.
+
+---
+
+### 📋 Tokens > Analysis
+
+Deeper analysis of token consumption patterns.
+
+| Section | Description |
+|---------|-------------|
+| **Tokens by Task Category** | Horizontal bar chart grouping token usage by auto-classified work type (code editing, documentation, planning, etc.). Categories are derived from skill/agent descriptions and saved in `task-categories.json` for customization. |
+| **Token Usage by Tool** | Horizontal bar chart of tokens attributed to specific skills, agents, or tools (top 10). |
+| **Prompt Statistics** | Total prompts, average prompt length (chars), short prompt ratio (≤100 chars), long prompt ratio (≥500 chars). |
+| **Response Latency** | Average, median (P50), 95th percentile (P95), and max response time (human→assistant interval). |
+| **Session Analysis** | Total sessions, average messages per session, average session duration, longest session. |
+| **Hourly Token Distribution** | Bar chart of token usage by hour of day (24h). |
+| **Cache Efficiency** | Fresh input, cache read, cache creation token counts with percentages and overall cache hit rate. |
+
+---
+
+### 🗂️ Structure
+
+Visual overview of your harness architecture.
+
+| Section | Description |
+|---------|-------------|
+| **Component Flow** | SVG diagram showing how harness components relate to each other, grouped into three layers: **Context** (auto-loaded: CLAUDE.md, rules, principles, memory), **Event-driven** (hooks, MCP servers, plugins), and **User-invoked** (skills, agents, commands, teams, plans). |
+| **File Tree** | Expandable tree view listing every registered component by category. Click any item to jump to its detail page. Plugins show active/inactive badges. |
+
+---
+
+### Category Pages
+
+Click any category in the sidebar (Skills, Agents, Plugins, Hooks, etc.) to see a dedicated page for that category.
+
+| Section | Description |
+|---------|-------------|
+| **Stat Cards** | Total items, usage count, and period-over-period change. |
+| **Popular Items** | Top 5 most-used items within the category (ranked cards). |
+| **Activity Heatmap** | Calendar heatmap filtered to this category only. |
+| **Recent Activity** | Latest invocations of items in this category. |
+| **Unused Items** | Registered items with zero calls in the selected period. |
+
+---
+
+### Item Detail Pages
+
+Click any individual item (skill, agent, plugin, etc.) to see its detail page.
+
+| Section | Description |
+|---------|-------------|
+| **Header** | Item name, type badge, file path, and description (from frontmatter). |
+| **Metadata** | Parsed frontmatter fields displayed in a formatted card. |
+| **Content Preview** | Full content of the item's definition file (markdown rendered). |
+| **Usage Stats** | Call count and activity heatmap for this specific item (for skills, agents, commands). |
+| **Related Items** | For plugins: list of skills provided by the plugin. For skills: parent plugin link if applicable. |
+
+---
+
+### ❓ Help
+
+In-dashboard reference page.
+
+| Section | Description |
+|---------|-------------|
+| **Usage** | How to run the `/omh` command. |
+| **Parameters** | Table of all command parameters (`--data-only`, `--enable-auto`, etc.). |
+| **Data Sources** | Reference for each data parser: what files are read and what data is extracted (config files, skills, agents, plugins, hooks, memory, MCP servers, rules, commands, teams, plans, todos, scopes). |
+| **Token & Activity** | How token usage, prompt stats, latency, and activity data are parsed from transcript JSONL files. |
+
+---
+
+## General Features
+
+### Dark / Light Mode
+
+Toggle via the theme button in the sidebar footer. Preference is persisted in `localStorage`.
+
+### Period Comparison
+
+Stat cards with a change percentage compare the selected period against the immediately preceding period of equal length. For example, 7d compares the last 7 days vs. the 7 days before that.
+
+### Data Refresh
+
+Run `/omh --data-only` to regenerate data and the web-ui without opening a new browser tab. Bookmark the generated local file (`output/index.html`) and refresh the page anytime to see the latest data.
+
+Enable auto-refresh with `/omh --enable-auto` to rebuild data on every session end — just refresh the bookmarked tab to see updates.

package/README.md

@@ -5,6 +5,7 @@
 
 Parses your entire Claude Code configuration and usage data, then generates an interactive single-file HTML dashboard you can open locally.
 
+<img src="./assets/dashboard.png" alt="Dashboard preview" width="800">
 
 ## What it shows
 
@@ -14,6 +15,9 @@ Parses your entire Claude Code configuration and usage data, then generates an i
 - **Task categories** — auto-classified token usage by work type (code editing, docs, planning, etc.)
 - **Multi-workspace** — switch between global and per-project scopes
 
+<img src="./assets/token-overview.png" alt="Tokens" width="800">
+<img src="./assets/insights.png" alt="Insights" width="800">
+
 ## Installation
 
 #### From the Command Line
@@ -33,6 +37,18 @@ claude plugin install oh-my-hi
 /plugin install oh-my-hi@oh-my-hi-marketplace
 ```
 
+## Update
+
+To update to the latest version, run the same install command:
+
+```bash
+# From the Command Line
+$ claude plugin install oh-my-hi
+
+# Claude Code (in-session)
+/plugin install oh-my-hi@oh-my-hi-marketplace
+```
+
 ## Usage
 
 Run in Claude Code:
@@ -64,6 +80,10 @@ Enable automatic data refresh so the dashboard stays up to date:
 
 This registers a Stop hook that rebuilds the dashboard data whenever a Claude Code session ends. Refresh the browser tab to see the latest data.
 
+## Guide
+
+See **[GUIDE.md](GUIDE.md)** for a detailed walkthrough of each dashboard section — overview, token analytics, cost estimation, structure view, category pages, and more.
+
 ## How it works
 
 1. **Parse** — Reads your Claude Code config directory for skills, agents, plugins, hooks, memory, MCP servers, rules, principles, commands, teams, plans, and usage transcripts
@@ -77,6 +97,10 @@ This registers a Stop hook that rebuilds the dashboard data whenever a Claude Co
 - **English**: Built-in default
 - **Other languages**: A template locale file is auto-generated on first build. Translate it and rebuild
 
+## Privacy
+
+All data stays on your machine. `oh-my-hi` reads only local Claude Code config files and transcripts — nothing is sent to external servers. The generated dashboard is a standalone HTML file opened via `file://` protocol, with no network requests. Your usage data, token statistics, and configuration details never leave your local environment.
+
 ## Browser support
 
 The dashboard opens as a local `file://` HTML file. No web server required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-hi",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Claude Code harness insights dashboard",
   "repository": {
     "type": "git",
@@ -16,5 +16,9 @@
     "insights",
     "analytics"
   ],
-  "homepage": "https://github.com/netil/oh-my-hi"
+  "homepage": "https://github.com/netil/oh-my-hi",
+  "devDependencies": {
+    "billboard.js": "^3.18.0",
+    "esbuild": "^0.27.4"
+  }
 }

package/scripts/generate-dashboard.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'url';
 import path from 'path';
 import fs from 'fs';
 import { execSync } from 'child_process';
+import { transformSync } from 'esbuild';
 
 import { parseSkills } from './parsers/skills.mjs';
 import { parseAgents } from './parsers/agents.mjs';
@@ -35,7 +36,7 @@ if (args.includes('--help')) {
 
 Usage:
   oh-my-hi                    Full build (index.html + data.json)
-  oh-my-hi --data-only        Data-only refresh (fast reload)
+  oh-my-hi --data-only        Regenerate data + web-ui (skip browser open)
   oh-my-hi --enable-auto      Enable auto data refresh on session end
   oh-my-hi --disable-auto     Disable auto data refresh
   oh-my-hi --status           Check auto-refresh status
@@ -180,8 +181,60 @@ async function main() {
   const safeJson = JSON.stringify(data);
   fs.writeFileSync(dataPath, safeJson, 'utf-8');
 
-  // 5b) Load locale for system language
+  // 5a-2) Minify usage data for inline HTML (key shortening + sessionId indexing)
+  const USAGE_KEY_MAP = {
+    timestamp: 'ts', model: 'm', inputTokens: 'it', outputTokens: 'ot',
+    cacheRead: 'cr', cacheCreation: 'cc', rawInput: 'ri', context: 'cx',
+    contextName: 'cn', sessionId: 'sid', latencyMs: 'ms', charLen: 'cl',
+    name: 'n', tool: 't', count: 'c', date: 'd', command: 'cmd', project: 'p',
+    messageCount: 'mc', sessionCount: 'sc', toolCallCount: 'tc',
+  };
+  function minifyUsageData(scopeDataObj) {
+    const result = {};
+    for (const [scope, sdata] of Object.entries(scopeDataObj)) {
+      const copy = { ...sdata };
+      if (copy.usage) {
+        const u = copy.usage;
+        // Build sessionId lookup table
+        const sidSet = new Set();
+        for (const arr of Object.values(u)) {
+          if (!Array.isArray(arr)) continue;
+          for (const item of arr) {
+            if (item.sessionId != null) sidSet.add(item.sessionId);
+          }
+        }
+        const sidList = [...sidSet];
+        const sidIndex = Object.fromEntries(sidList.map((s, i) => [s, i]));
+
+        // Shorten keys and replace sessionId with index
+        const minUsage = {};
+        for (const [field, arr] of Object.entries(u)) {
+          if (!Array.isArray(arr)) { minUsage[field] = arr; continue; }
+          minUsage[field] = arr.map(item => {
+            const obj = {};
+            for (const [k, v] of Object.entries(item)) {
+              if (k === 'sessionId') {
+                obj.sid = v != null ? sidIndex[v] : null;
+              } else {
+                obj[USAGE_KEY_MAP[k] || k] = v;
+              }
+            }
+            return obj;
+          });
+        }
+        minUsage._sidList = sidList;
+        copy.usage = minUsage;
+      }
+      result[scope] = copy;
+    }
+    return result;
+  }
+  const inlineData = { ...data, scopeData: minifyUsageData(data.scopeData), _minified: true };
+  const inlineJson = JSON.stringify(inlineData);
+
+  // 5b) Load locales
   const LOCALES_DIR = path.join(TEMPLATES, 'locales');
+  const enObj = JSON.parse(fs.readFileSync(path.join(LOCALES_DIR, 'en.json'), 'utf-8'));
   let localeObj = {};
   const localePath = path.join(LOCALES_DIR, systemLocale + '.json');
   if (systemLocale !== 'en' && fs.existsSync(localePath)) {
@@ -191,42 +244,53 @@ async function main() {
       console.log(`  locale: ${systemLocale} (${Object.keys(localeObj).length - 1} keys)`);
     } catch { /* fallback to English */ }
   }
-  // For unknown locales: generate English template file on first run
+  // For unknown locales: copy en.json as template on first run
   if (systemLocale !== 'en' && !fs.existsSync(localePath)) {
-    const enKeys = {};
-    const appSrc = fs.readFileSync(path.join(TEMPLATES, 'app.js'), 'utf-8');
-    const enMatch = appSrc.match(/I18N\.en\s*=\s*\{([\s\S]*?)\n  \};/);
-    if (enMatch) {
-      for (const line of enMatch[1].split('\n')) {
-        const m = line.match(/^\s*(\w+):\s*"(.*)"/);
-        if (m) enKeys[m[1]] = m[2];
-      }
-    }
     fs.mkdirSync(LOCALES_DIR, { recursive: true });
-    fs.writeFileSync(localePath, JSON.stringify(enKeys, null, 2), 'utf-8');
+    fs.writeFileSync(localePath, JSON.stringify(enObj, null, 2), 'utf-8');
     console.log(`  locale: created template ${localePath} (translate and rebuild)`);
   }
 
   // 5c) index.html — always regenerated (data is inlined for file:// compatibility)
   const template = fs.readFileSync(path.join(TEMPLATES, 'dashboard.html'), 'utf-8');
-  const styles = fs.readFileSync(path.join(TEMPLATES, 'styles.css'), 'utf-8');
-  const appJs = fs.readFileSync(path.join(TEMPLATES, 'app.js'), 'utf-8');
+  const rawStyles = fs.readFileSync(path.join(TEMPLATES, 'styles.css'), 'utf-8');
+  const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf-8'));
+  const rawAppJs = fs.readFileSync(path.join(TEMPLATES, 'app.js'), 'utf-8')
+    .replace(/__VERSION__/g, JSON.stringify(pkg.version));
+
+  // billboard.js (pkgd includes d3) + CSS
+  const bbDir = path.join(ROOT, 'node_modules', 'billboard.js', 'dist');
+  if (!fs.existsSync(bbDir)) {
+    console.error('oh-my-hi: ❌ node_modules not found. Run `npm install` in', ROOT);
+    process.exit(1);
+  }
+  const bbJs = fs.readFileSync(path.join(bbDir, 'billboard.pkgd.min.js'), 'utf-8');
+  const bbCss = fs.readFileSync(path.join(bbDir, 'billboard.min.css'), 'utf-8');
+  const bbDarkCss = fs.readFileSync(path.join(bbDir, 'theme', 'dark.min.css'), 'utf-8');
+
+  const styles = transformSync(rawStyles, { loader: 'css', minify: true }).code;
+  const appJs = transformSync(rawAppJs, { loader: 'js', minify: true }).code;
 
   const escapeForScript = (str) => str
     .replaceAll('</', String.raw`<\u002f`)
     .replaceAll('\u2028', String.raw`\u2028`)
     .replaceAll('\u2029', String.raw`\u2029`);
 
-  const escapedJson = escapeForScript(safeJson);
+  const escapedJson = escapeForScript(inlineJson);
   const escapedLocale = escapeForScript(JSON.stringify(localeObj));
 
   // Use a single-pass replacer to avoid cross-contamination when data payloads
   // contain placeholder-like strings (e.g. __LOCALE_DATA__ inside skill descriptions).
   const placeholders = {
+    __BB_CSS__: bbCss,
+    __BB_DARK_CSS_STR__: JSON.stringify(bbDarkCss),
+    __BB_JS__: bbJs,
     __STYLES__: styles,
+    __EN_DATA__: escapeForScript(JSON.stringify(enObj)),
     __LOCALE_DATA__: escapedLocale,
     __APP_JS__: appJs,
     __DATA__: escapedJson,
+    __VERSION__: pkg.version,
   };
   const placeholderRe = new RegExp(Object.keys(placeholders).map(k => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'), 'g');
   const html = template.replace(placeholderRe, (match) => placeholders[match]);
@@ -394,53 +458,18 @@ async function collectProjectData(configPath, projectPath) {
 /**
  * Build task categories by classifying contextNames into work types.
  *
- * Classification is persisted in task-categories.json:
- *  - Existing entries are preserved (user can edit the file to override).
- *  - New contextNames are auto-classified from their description at build time.
+ * Classification is auto-generated at every build:
+ *  - contextNames are classified from their description using keyword matching.
  *  - Built-in tools (context='tool') use a fixed structural mapping.
+ *  - Category labels come from locale files (taskCat_* keys).
  */
 const TASK_CAT_FILE = path.join(OUTPUT, 'task-categories.json');
 
-// Category schema — universal work types (fixed structure)
-const WORK_TYPE_META = {
-  'code-edit':   { icon: '✏️', ko: '코드 편집',       en: 'Code Editing' },
-  'code-search': { icon: '🔍', ko: '코드 탐색',       en: 'Code Search' },
-  'execution':   { icon: '▶️', ko: '실행 / 디버깅',    en: 'Execution & Debug' },
-  'review':      { icon: '🔎', ko: '코드 리뷰',       en: 'Code Review' },
-  'planning':    { icon: '📐', ko: '설계 / 계획',      en: 'Planning & Design' },
-  'docs':        { icon: '📝', ko: '문서 작성',        en: 'Documentation' },
-  'browser':     { icon: '🌐', ko: '브라우저',         en: 'Browser Automation' },
-  'workflow':    { icon: '⚙️', ko: '워크플로 자동화',    en: 'Workflow Automation' },
-  'team':        { icon: '👥', ko: '팀 관리',          en: 'Team Management' },
-  'config':      { icon: '🔧', ko: '설정 / 유지보수',   en: 'Config & Maintenance' },
-  'general':     { icon: '💬', ko: '일반 대화',        en: 'General' },
-  'other':       { icon: '📦', ko: '기타',            en: 'Other' },
-};
-
-// Built-in tool → category (structural, not user data)
-const TOOL_CATEGORY = {
-  Edit: 'code-edit', Write: 'code-edit', NotebookEdit: 'code-edit',
-  Read: 'code-search', Grep: 'code-search', Glob: 'code-search',
-  LSP: 'code-search', ToolSearch: 'code-search', Explore: 'code-search',
-  AskUserQuestion: 'code-search',
-  Bash: 'execution',
-  EnterPlanMode: 'planning', ExitPlanMode: 'planning', Plan: 'planning',
-  TaskCreate: 'planning', TaskUpdate: 'planning', TaskOutput: 'planning', TaskStop: 'planning',
-  TeamCreate: 'team', TeamDelete: 'team', SendMessage: 'team',
-  WebFetch: 'browser', WebSearch: 'browser',
-};
-
-// Category keyword seeds — used ONLY for auto-classifying new items
-const CAT_KEYWORDS = {
-  'review':   ['review', 'lint', 'simplif', '리뷰', '검수', '검토'],
-  'planning': ['plan', 'design', 'architect', 'brainstorm', '계획', '설계', '기획'],
-  'docs':     ['doc', 'report', 'meeting', 'wiki', 'publish', 'humaniz', 'summary', '문서', '회의', '보고', '정리', '요약', '작성', '기술공유', '기록'],
-  'browser':  ['browser', 'chrome', 'scrape', 'page', '브라우저'],
-  'workflow': ['workflow', 'n8n', 'cron', 'schedule', '자동화', '워크플로'],
-  'team':     ['team', 'leader', 'manager', '팀', '매니저'],
-  'config':   ['config', 'setting', 'setup', 'hook', 'plugin', 'health', 'improve', 'skill-creator', '설정', '개선'],
-  'execution':['debug', 'test', 'exec', 'build', 'implement', '디버그', '실행', '테스트', '구현'],
-};
+// Work types loaded from external file (categories, tool mapping, keywords)
+const WORK_TYPES = JSON.parse(fs.readFileSync(path.join(TEMPLATES, 'work-types.json'), 'utf-8'));
+const WORK_TYPE_META = WORK_TYPES.categories;
+const TOOL_CATEGORY = WORK_TYPES.toolMapping;
+const CAT_KEYWORDS = WORK_TYPES.keywords;
 
 function buildTaskCategories(scopeData) {
   // 1. Collect descriptions from harness data
@@ -454,13 +483,7 @@ function buildTaskCategories(scopeData) {
     }
   }
 
-  // 2. Load existing persistent mapping (user overrides preserved)
-  let persisted = {};
-  try {
-    persisted = JSON.parse(fs.readFileSync(TASK_CAT_FILE, 'utf-8'));
-  } catch { /* first run or missing file */ }
-
-  // 3. Collect all contextNames from token data
+  // 2. Collect all contextNames from token data
   const allNames = new Set();
   for (const sd of Object.values(scopeData)) {
     for (const e of (sd.usage?.tokenEntries || [])) {
@@ -468,7 +491,7 @@ function buildTaskCategories(scopeData) {
     }
   }
 
-  // 4. Auto-classify items not in persisted mapping
+  // 3. Auto-classify each contextName
   function autoClassify(name, contextType) {
     if (contextType === 'tool' && TOOL_CATEGORY[name]) return TOOL_CATEGORY[name];
     if (contextType === 'general') return 'general';
@@ -485,22 +508,17 @@ function buildTaskCategories(scopeData) {
     return bestCat || 'other';
   }
 
-  // 5. Build final mapping: persisted → auto-classified → tool mapping
+  // 4. Build mapping: auto-classify all contextNames
   const mapping = {};
   for (const sd of Object.values(scopeData)) {
     for (const e of (sd.usage?.tokenEntries || [])) {
       const name = e.contextName || 'conversation';
       if (mapping[name]) continue;
-
-      if (persisted[name]) {
-        mapping[name] = persisted[name];
-      } else {
-        mapping[name] = autoClassify(name, e.context || 'general');
-      }
+      mapping[name] = autoClassify(name, e.context || 'general');
     }
   }
 
-  // 6. Save updated mapping to file (user-editable)
+  // 5. Save mapping for reference
   const sorted = {};
   for (const key of Object.keys(mapping).sort()) sorted[key] = mapping[key];
   fs.writeFileSync(TASK_CAT_FILE, JSON.stringify(sorted, null, 2), 'utf-8');