claude-cli-analytics 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# Claude CLI Analytics Dashboard
+
+Claude CLI 대화 로그를 분석하여 토큰 효율성, 캐시 활용률, 컨텍스트 사용 패턴을 시각화하는 대시보드
+
+## ✨ Features
+
+- 📊 **Dashboard**: 전체 효율성 지표, 토큰 분포, 트렌드 차트
+- 📝 **Session Detail**: 세션별 대화 타임라인, 질문별 읽은 컨텍스트 로그
+- 🔄 **Real-time Refresh**: 새로고침 버튼으로 최신 데이터 로드
+- 🏆 **Engineering Grade**: S/A/B/C 등급 + SEI (Spec Efficiency Index) 분석
+- 🔍 **Auto-detection**: `.claude/projects` 경로 자동 탐색 — init 불필요
+- 📦 **NPM 패키지**: `npm install -g`로 어디서든 설치 가능
+
+## 🚀 설치 및 실행
+
+### ✅ NPM (권장)
+
+```bash
+# 글로벌 설치
+npm install -g claude-cli-analytics
+
+# 실행 (자동으로 ~/.claude/projects 탐색)
+claude-cli-analytics
+```
+
+### 📦 npx (설치 없이 실행)
+
+```bash
+npx claude-cli-analytics
+```
+
+### 🛠️ 소스에서 빌드 (기여용)
+
+```bash
+git clone https://github.com/igeunpyo/claude-analytics.git
+cd claude-analytics
+npm install
+npm run build
+npm start
+
+# 또는 글로벌로 링크하여 사용
+npm link
+claude-cli-analytics
+```
+
+### ⚡ 개발 모드
+
+```bash
+npm run dev
+```
+
+- Frontend: http://localhost:3000
+- Backend API: http://localhost:3001
+
+## 🛠️ Requirements
+
+- Node.js 18+ (권장: 20+)
+- npm 9+
+
+## 🔍 .claude 경로 자동 탐색
+
+**별도의 `init` 과정이 필요 없습니다.** 서버 시작 시 자동으로 Claude Code의 데이터 디렉토리를 탐색합니다.
+
+Claude Code는 설치 방법에 관계없이 항상 `~/.claude/projects`에 세션 데이터를 저장합니다:
+
+| 설치 방법 | 데이터 경로 |
+|----------|-----------|
+| `brew install --cask claude-code` | `~/.claude/projects` |
+| `npm install -g @anthropic-ai/claude-code` | `~/.claude/projects` |
+| 직접 다운로드 | `~/.claude/projects` |
+
+### 경로 탐색 우선순위
+
+1. `CLAUDE_PROJECTS_DIR` 환경변수 (최우선)
+2. 저장된 설정 파일 (`~/.claude-analytics/config.json`)
+3. 자동 탐색 (`~/.claude/projects`, `$XDG_CONFIG_HOME/claude/projects`)
+4. 기본 경로 (`~/.claude/projects`)
+
+### 커스텀 경로 사용
+
+```bash
+# 환경변수로 지정
+CLAUDE_PROJECTS_DIR=/path/to/claude/projects claude-cli-analytics
+
+# CLI 옵션으로 지정
+claude-cli-analytics --path /path/to/claude/projects
+
+# 포트 변경
+claude-cli-analytics --port 8080
+```
+
+## 📈 분석 지표
+
+### 1. 컨텍스트 지표
+
+| 지표 | 계산 방식 | 의미 |
+|------|----------|------|
+| **평균 컨텍스트** | `(input_tokens + cache_read) / 요청수` | 요청당 평균 컨텍스트 크기 |
+| **위험 레벨** | `<20K: 안전, 20-50K: 주의, >50K: 위험` | 컨텍스트 과부하 경고 |
+| **리미트 영향도** | `(총 컨텍스트 / 44,000) × 100%` | Claude Pro 5시간 한도 대비 사용량 |
+
+### 2. 품질 지표
+
+| 지표 | 계산 방식 | 목표 | 의미 |
+|------|----------|------|------|
+| **중복 읽기율** | `(전체읽기 - 고유파일) / 전체읽기 × 100` | <20% | 같은 파일을 여러 번 읽은 비율 |
+| **Read/Edit 비율** | `Read도구 횟수 / Edit도구 횟수` | ≥5:1 | 수정 전 충분한 탐색 여부 |
+| **반복 수정율** | `(전체수정 - 고유파일) / 전체수정 × 100` | <20% | 같은 파일을 여러 번 수정한 비율 |
+| **수정당 토큰** | `총 컨텍스트 / Edit 횟수` | <50K | 수정 1회당 소비된 토큰 |
+
+### 3. Engineering Grade (S/A/B/C)
+
+100점 만점 종합 점수로 산출:
+- **Efficiency (40%)**: 캐시 히트율 기반
+- **Stability (30%)**: 도구 오류율 기반
+- **Precision (30%)**: Read/Edit 비율 기반
+- **Penalty**: 팬텀 파일 접근 횟수 × 5
+
+```
+🏆 S급 (90+): Elite — 최적화된 워크플로우
+⭐ A급 (80+): Good — 우수한 효율성
+✅ B급 (60+): Average — 개선 여지 있음
+⚠️ C급 (40+): Below Average — 최적화 필요
+```
+
+### 4. Spec Efficiency Index (SEI)
+
+```
+SEI = (Accuracy × 100) / log₁₀(Spec Volume + 1)
+```
+
+`.claude/` 컨텍스트 파일 읽기 후 오류율을 측정하여 스펙 문서의 실효성을 평가합니다.
+
+## 🔧 API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/analytics` | 전체 요약 통계 |
+| `GET /api/sessions` | 세션 목록 (SEI + Grade 포함) |
+| `GET /api/sessions/:id` | 세션 상세 (메시지, 토큰, 파일) |
+| `GET /api/projects` | 프로젝트 목록 |
+| `GET /api/config` | 현재 설정 + 자동 탐색 결과 |
+| `GET /api/health` | 서버 상태 확인 |
+| `POST /api/refresh` | 데이터 새로고침 |
+
+## 📁 Project Structure
+
+```
+claude-cli-analytics/
+├── src/                      # React Frontend
+│   ├── pages/
+│   │   ├── Dashboard.tsx     # 메인 대시보드
+│   │   └── SessionDetail.tsx # 세션 상세 페이지
+│   ├── App.tsx               # 라우팅
+│   └── index.css             # Tailwind CSS
+├── server/
+│   ├── index.ts              # Express API 서버
+│   ├── config.ts             # 설정 + 자동 탐색
+│   ├── analyzer.ts           # 세션 분석 로직
+│   ├── parser.ts             # JSONL 파서
+│   └── types.ts              # 타입 정의
+├── bin/
+│   └── cli.js                # CLI 진입점 (--port, --path, --help)
+├── dist/
+│   ├── client/               # 빌드된 프론트엔드
+│   └── server/               # 빌드된 백엔드
+├── package.json
+├── tsconfig.server.json      # 서버 빌드 설정
+└── vite.config.ts
+```
+
+## 📄 License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+// ── Claude Analytics CLI ──
+// Supports: --port <number>, --path <dir>, --help
+
+const args = process.argv.slice(2);
+
+// Handle --help
+if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+  Claude Analytics Dashboard
+  
+  Usage: claude-cli-analytics [options]
+
+  Options:
+    --port <number>   Server port (default: 3001)
+    --path <dir>      Claude projects directory (overrides auto-detection)
+    --help, -h        Show this help message
+
+  Auto-detection:
+    Automatically finds Claude Code data at ~/.claude/projects
+    Works with all installation methods (homebrew, npm, direct install)
+
+  Environment variables:
+    CLAUDE_PROJECTS_DIR   Override projects directory path
+    PORT                  Override server port
+`);
+    process.exit(0);
+}
+
+// Parse --port
+const portIdx = args.indexOf('--port');
+if (portIdx !== -1 && args[portIdx + 1]) {
+    process.env.PORT = args[portIdx + 1];
+}
+
+// Parse --path
+const pathIdx = args.indexOf('--path');
+if (pathIdx !== -1 && args[pathIdx + 1]) {
+    process.env.CLAUDE_PROJECTS_DIR = args[pathIdx + 1];
+}
+
+// Start the server
+import('../dist/server/index.js');

package/dist/client/assets/index-BkOIudNK.css

@@ -0,0 +1 @@
+@import"https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&display=swap";:root{--bg-primary: #ffffff;--bg-secondary: #f8f9fa;--bg-tertiary: #f1f3f4;--bg-surface: #ffffff;--text-primary: #202124;--text-secondary: #5f6368;--text-tertiary: #9aa0a6;--blue-primary: #1a73e8;--blue-light: #e8f0fe;--blue-dark: #1557b0;--green-primary: #1e8e3e;--green-light: #e6f4ea;--orange-primary: #e37400;--orange-light: #fef7e0;--purple-primary: #7b1fa2;--purple-light: #f3e8fd;--red-primary: #d93025;--red-light: #fce8e6;--border-color: #e8eaed;--border-light: #f1f3f4;--shadow-sm: 0 1px 3px rgba(32, 33, 36, .04);--shadow-md: 0 4px 12px rgba(32, 33, 36, .06);--shadow-lg: 0 8px 24px rgba(32, 33, 36, .08);--shadow-xl: 0 12px 40px rgba(32, 33, 36, .1);--radius-sm: 12px;--radius-md: 20px;--radius-lg: 24px;--radius-xl: 32px;--radius-pill: 999px;--transition-fast: .15s cubic-bezier(.4, 0, .2, 1);--transition-normal: .25s cubic-bezier(.4, 0, .2, 1);--transition-slow: .35s cubic-bezier(.4, 0, .2, 1)}*{box-sizing:border-box;margin:0;padding:0}body{font-family:Inter,-apple-system,BlinkMacSystemFont,system-ui,Segoe UI,sans-serif;background-color:var(--bg-secondary);color:var(--text-primary);line-height:1.6;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;letter-spacing:-.011em}.app-container{min-height:100vh}.header{background:#ffffffb8;backdrop-filter:blur(20px) saturate(180%);-webkit-backdrop-filter:blur(20px) saturate(180%);border-bottom:1px solid rgba(232,234,237,.6);padding:0 32px;height:64px;position:sticky;top:0;z-index:100;transition:background var(--transition-normal)}.header-content{max-width:1200px;margin:0 auto;display:flex;align-items:center;justify-content:space-between;height:100%}.logo{font-size:17px;font-weight:600;color:var(--text-primary);display:flex;align-items:center;gap:10px;text-decoration:none;letter-spacing:-.02em}.logo-icon{display:inline-flex;align-items:center;justify-content:center;width:32px;height:32px;border-radius:10px;background:var(--text-primary);color:#fff;font-size:12px;font-weight:700;letter-spacing:.5px}.nav{display:flex;align-items:center;gap:4px}.nav-link{font-size:14px;font-weight:500;color:var(--text-secondary);text-decoration:none;padding:8px 16px;border-radius:var(--radius-pill);transition:all var(--transition-fast)}.nav-link:hover{background:var(--bg-tertiary);color:var(--text-primary)}.main{min-height:calc(100vh - 130px)}.container{max-width:1200px;margin:0 auto;padding:40px 32px}.footer{text-align:center;padding:32px;color:var(--text-tertiary);font-size:13px;font-weight:400}.card{background:var(--bg-primary);border-radius:var(--radius-lg);border:none;box-shadow:var(--shadow-sm);padding:28px;transition:all var(--transition-normal)}.card:hover{box-shadow:var(--shadow-md)}.card-header{display:flex;align-items:center;justify-content:space-between;margin-bottom:24px}.card-title{font-size:16px;font-weight:600;color:var(--text-primary);letter-spacing:-.02em}.stat-card{background:var(--bg-primary);border-radius:var(--radius-lg);border:none;box-shadow:var(--shadow-sm);padding:28px;display:flex;flex-direction:column;gap:8px;transition:all var(--transition-normal)}.stat-card:hover{box-shadow:var(--shadow-md);transform:translateY(-2px)}.stat-label{font-size:13px;color:var(--text-tertiary);font-weight:500}.stat-value{font-size:32px;font-weight:700;color:var(--text-primary);line-height:1.2;letter-spacing:-.03em}.stat-value.blue{color:var(--blue-primary)}.stat-value.green{color:var(--green-primary)}.stat-value.orange{color:var(--orange-primary)}.stat-value.purple{color:var(--purple-primary)}.btn{display:inline-flex;align-items:center;justify-content:center;gap:8px;padding:10px 24px;border-radius:var(--radius-pill);font-size:14px;font-weight:500;cursor:pointer;transition:all var(--transition-fast);border:none;letter-spacing:-.01em}.btn-primary{background:var(--text-primary);color:#fff}.btn-primary:hover{background:#3c4043;box-shadow:var(--shadow-md)}.btn-secondary{background:var(--bg-primary);color:var(--text-primary);border:1px solid var(--border-color)}.btn-secondary:hover{background:var(--bg-tertiary);border-color:#dadce0}.select,.input{padding:10px 18px;border-radius:var(--radius-sm);border:1px solid var(--border-color);background:var(--bg-primary);color:var(--text-primary);font-size:14px;font-weight:400;font-family:inherit;cursor:pointer;transition:all var(--transition-fast)}.select{padding-right:40px;appearance:none;background-image:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24' fill='none' stroke='%235f6368' stroke-width='2'%3E%3Cpath d='M6 9l6 6 6-6'/%3E%3C/svg%3E");background-repeat:no-repeat;background-position:right 14px center}.select:focus,.input:focus{outline:none;border-color:var(--blue-primary);box-shadow:0 0 0 3px #1a73e81f}.tag{display:inline-flex;align-items:center;padding:4px 12px;border-radius:var(--radius-pill);font-size:12px;font-weight:500}.tag-blue{background:var(--blue-light);color:var(--blue-primary)}.tag-green{background:var(--green-light);color:var(--green-primary)}.tag-orange{background:var(--orange-light);color:var(--orange-primary)}.tag-purple{background:var(--purple-light);color:var(--purple-primary)}.table-container{overflow-x:auto;border-radius:var(--radius-sm)}table{width:100%;border-collapse:collapse}table th{text-align:left;font-size:12px;font-weight:600;color:var(--text-tertiary);padding:12px 16px;text-transform:uppercase;letter-spacing:.04em;border-bottom:1px solid var(--border-color)}table td{padding:14px 16px;border-bottom:1px solid var(--border-light);font-size:14px;color:var(--text-secondary);transition:background var(--transition-fast)}table tr:last-child td{border-bottom:none}table tbody tr{transition:background var(--transition-fast)}table tbody tr:hover td{background:var(--bg-secondary)}.chart-container{padding:20px 0}.message-card{background:var(--bg-primary);border-radius:var(--radius-md);border:none;box-shadow:var(--shadow-sm);padding:20px;margin-bottom:12px;transition:box-shadow var(--transition-fast)}.message-card:hover{box-shadow:var(--shadow-md)}.message-card.user{border-left:3px solid var(--blue-primary)}.message-card.assistant{border-left:3px solid var(--purple-primary)}.message-header{display:flex;align-items:center;justify-content:space-between;margin-bottom:12px}.message-content{font-size:14px;color:var(--text-secondary);line-height:1.7;white-space:pre-wrap}.file-tags{display:flex;flex-wrap:wrap;gap:6px;margin:8px 0}.file-tag{display:inline-flex;align-items:center;padding:4px 10px;background:var(--bg-tertiary);border-radius:var(--radius-pill);font-size:11px;font-family:SF Mono,Fira Code,Monaco,monospace;color:var(--text-secondary);max-width:200px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.file-tag.spec{background:var(--purple-light);color:var(--purple-primary)}.grid-4{display:grid;grid-template-columns:repeat(4,1fr);gap:20px}.grid-3{display:grid;grid-template-columns:repeat(3,1fr);gap:20px}.grid-2{display:grid;grid-template-columns:repeat(2,1fr);gap:24px}@media(max-width:1200px){.grid-4,.grid-3{grid-template-columns:repeat(2,1fr)}}@media(max-width:768px){.grid-4,.grid-3,.grid-2{grid-template-columns:1fr}.container{padding:20px 16px}.header{padding:0 16px}}.spinner,.loading-spinner{width:36px;height:36px;border:3px solid var(--border-color);border-top-color:var(--text-primary);border-radius:50%;animation:spin .7s linear infinite}@keyframes spin{to{transform:rotate(360deg)}}@keyframes fadeIn{0%{opacity:0;transform:translateY(8px)}to{opacity:1;transform:translateY(0)}}@keyframes pulse{0%,to{opacity:1}50%{opacity:.3}}::-webkit-scrollbar{width:6px;height:6px}::-webkit-scrollbar-track{background:transparent}::-webkit-scrollbar-thumb{background:var(--border-color);border-radius:3px}::-webkit-scrollbar-thumb:hover{background:var(--text-tertiary)}.info-tooltip{position:relative;display:inline-flex;align-items:center;margin-left:4px;cursor:help}.info-tooltip-icon{width:15px;height:15px;border-radius:50%;background:var(--bg-tertiary);color:var(--text-tertiary);font-size:10px;font-weight:600;display:inline-flex;align-items:center;justify-content:center;transition:all var(--transition-fast)}.info-tooltip:hover .info-tooltip-icon{background:var(--text-primary);color:#fff}.info-tooltip-text{display:none;position:absolute;bottom:calc(100% + 8px);left:50%;transform:translate(-50%);background:var(--text-primary);color:#fff;padding:10px 14px;border-radius:var(--radius-sm);font-size:12px;line-height:1.5;white-space:pre-wrap;min-width:220px;max-width:320px;z-index:1000;box-shadow:var(--shadow-lg)}.info-tooltip:hover .info-tooltip-text{display:block}