claude-cli-analytics 0.0.1 → 0.0.5

package/README.md

@@ -4,8 +4,9 @@ Claude CLI 대화 로그를 분석하여 토큰 효율성, 캐시 활용률, 컨
 
 ## ✨ Features
 
-- 📊 **Dashboard**: 전체 효율성 지표, 토큰 분포, 트렌드 차트
-- 📝 **Session Detail**: 세션별 대화 타임라인, 질문별 읽은 컨텍스트 로그
+- 📊 **Dashboard**: Anthropic 스킬 평가 프레임워크 기반 지표, 토큰 분포, 트렌드 차트
+- 📝 **Session Detail**: 세션별 대화 타임라인, 도구 사용 내역, 6카테고리 지표 패널
+- 💬 **대화형 도구 표시**: AskUserQuestion 등 대화형 도구의 Q&A 내용을 카드로 표시
 - 🔄 **Real-time Refresh**: 새로고침 버튼으로 최신 데이터 로드
 - 🏆 **Engineering Grade**: S/A/B/C 등급 + SEI (Spec Efficiency Index) 분석
 - 🔍 **Auto-detection**: `.claude/projects` 경로 자동 탐색 — init 불필요
@@ -32,7 +33,7 @@ npx claude-cli-analytics
 ### 🛠️ 소스에서 빌드 (기여용)
 
 ```bash
-git clone https://github.com/igeunpyo/claude-analytics.git
+git clone https://github.com/rootTiket/claude-analytics.git
 cd claude-analytics
 npm install
 npm run build
@@ -54,9 +55,38 @@ npm run dev
 
 ## 🛠️ Requirements
 
-- Node.js 18+ (권장: 20+)
+- Node.js 20+
 - npm 9+
 
+## 🚀 사용법
+
+### 대시보드 시작
+기본적으로 **백그라운드 모드**로 실행됩니다:
+```bash
+claude-cli-analytics
+```
+브라우저에서 `http://localhost:3001`이 자동으로 열리며, 서버는 백그라운드에서 실행됩니다.
+
+### 대시보드 중지
+백그라운드 프로세스를 중지합니다:
+```bash
+claude-cli-analytics exit
+```
+
+### 상태 확인
+대시보드 실행 여부를 확인합니다:
+```bash
+claude-cli-analytics status
+```
+
+### 옵션
+```bash
+claude-cli-analytics --port 8080     # 커스텀 포트로 실행
+claude-cli-analytics --path /foo     # 커스텀 프로젝트 디렉토리
+claude-cli-analytics --foreground    # 포그라운드 실행 (Ctrl+C로 중지)
+claude-cli-analytics --help          # 도움말 표시
+```
+
 ## 🔍 .claude 경로 자동 탐색
 
 **별도의 `init` 과정이 필요 없습니다.** 서버 시작 시 자동으로 Claude Code의 데이터 디렉토리를 탐색합니다.
@@ -81,91 +111,149 @@ Claude Code는 설치 방법에 관계없이 항상 `~/.claude/projects`에 세
 ```bash
 # 환경변수로 지정
 CLAUDE_PROJECTS_DIR=/path/to/claude/projects claude-cli-analytics
+```
 
-# CLI 옵션으로 지정
-claude-cli-analytics --path /path/to/claude/projects
+## 📈 분석 지표 (Anthropic Skill Evaluation Framework)
 
-# 포트 변경
-claude-cli-analytics --port 8080
-```
+> Anthropic의 공식 스킬 평가 프레임워크를 기반으로 구성된 지표입니다.
 
-## 📈 분석 지표
+---
 
-### 1. 컨텍스트 지표
+### 📊 정량적 지표 (Quantitative Metrics)
 
-| 지표 | 계산 방식 | 의미 |
-|------|----------|------|
-| **평균 컨텍스트** | `(input_tokens + cache_read) / 요청수` | 요청당 평균 컨텍스트 크기 |
-| **위험 레벨** | `<20K: 안전, 20-50K: 주의, >50K: 위험` | 컨텍스트 과부하 경고 |
-| **리미트 영향도** | `(총 컨텍스트 / 44,000) × 100%` | Claude Pro 5시간 한도 대비 사용량 |
+#### 1. 컨텍스트 자동 탐색 성공률 (Skill Trigger Rate)
 
-### 2. 품질 지표
+> *Anthropic 기준: 관련 쿼리의 90%에서 스킬이 트리거됨*
 
 | 지표 | 계산 방식 | 목표 | 의미 |
 |------|----------|------|------|
-| **중복 읽기율** | `(전체읽기 - 고유파일) / 전체읽기 × 100` | <20% | 같은 파일을 여러 번 읽은 비율 |
-| **Read/Edit 비율** | `Read도구 횟수 / Edit도구 횟수` | ≥5:1 | 수정 전 충분한 탐색 여부 |
-| **반복 수정율** | `(전체수정 - 고유파일) / 전체수정 × 100` | <20% | 같은 파일을 여러 번 수정한 비율 |
-| **수정당 토큰** | `총 컨텍스트 / Edit 횟수` | <50K | 수정 1회당 소비된 토큰 |
+| **캐시 히트율** | `cache_read / (input + cache_read) × 100` | ≥ 70% | 스킬(컨텍스트)이 자동으로 로드된 비율 |
+| **스펙 컨텍스트 활용률** | `spec 파일 읽은 세션 / 전체 세션 × 100` | ≥ 90% | `.claude/` 스펙이 자동 트리거된 비율 |
+| **위험 레벨** | `<20K: 최적, 20-50K: 주의, >50K: 위험` | 최적 | 컨텍스트 과부하 경고 |
+| **리미트 영향도** | `(총 컨텍스트 / 44,000) × 100%` | — | Claude Pro 5시간 한도 대비 사용량 |
 
-### 3. Engineering Grade (S/A/B/C)
+**측정 방법**: 테스트 쿼리 10~20개를 실행하여, 자동으로 캐시 히트가 되는 비율과 스펙 컨텍스트가 로드되는 비율을 추적합니다.
 
-100점 만점 종합 점수로 산출:
-- **Efficiency (40%)**: 캐시 히트율 기반
-- **Stability (30%)**: 도구 오류율 기반
-- **Precision (30%)**: Read/Edit 비율 기반
-- **Penalty**: 팬텀 파일 접근 횟수 × 5
+#### 2. 도구 호출 효율성 (Tool Call Efficiency)
 
-```
-🏆 S급 (90+): Elite — 최적화된 워크플로우
-⭐ A급 (80+): Good — 우수한 효율성
-✅ B급 (60+): Average — 개선 여지 있음
-⚠️ C급 (40+): Below Average — 최적화 필요
-```
+> *Anthropic 기준: X도구 호출로 워크플로우 완료*
+
+| 지표 | 계산 방식 | 목표 | 의미 |
+|------|----------|------|------|
+| **Read/Edit 비율** | `Read도구 횟수 / Edit도구 횟수` | ≥ 5:1 | 수정 전 충분한 탐색 여부 |
+| **수정당 토큰** | `총 컨텍스트 / Edit 횟수` | < 50K | 수정 1회당 소비된 토큰 |
+| **중복 읽기율** | `(전체읽기 - 고유파일) / 전체읽기 × 100` | < 20% | 불필요한 반복 읽기 비율 |
+| **반복 수정율** | `(전체수정 - 고유파일) / 전체수정 × 100` | < 20% | 같은 파일 반복 수정 비율 |
+
+**측정 방법**: 스킬(스펙 컨텍스트) 활성화 전후 동일 작업을 비교하여 도구 호출 횟수와 총 토큰 소비량을 집계합니다.
+
+#### 3. API 실패율 (Failed API Calls per Workflow)
+
+> *Anthropic 기준: 워크플로당 실패한 API 호출 0회*
 
-### 4. Spec Efficiency Index (SEI)
+| 지표 | 계산 방식 | 목표 | 의미 |
+|------|----------|------|------|
+| **도구 오류율** | `오류 도구 호출 / 전체 도구 호출 × 100` | 0% | 실패한 도구 호출 비율 |
+| **오류 상세** | 도구별 오류 메시지 및 빈도 집계 | — | 재시도율 및 오류 코드 추적 |
+| **세션 종료 유형** | `clean / forced / unknown` | clean | 비정상 종료 여부 |
+
+**측정 방법**: 테스트 실행 중 도구 호출 로그를 모니터링하며, 재시도율 및 오류 코드를 추적합니다.
+
+---
+
+### 🎯 정성적 지표 (Qualitative Metrics)
+
+#### 4. 사용자 개입 빈도 (User Intervention Frequency)
+
+> *Anthropic 기준: 사용자가 Claude에게 다음 단계를 묻지 않아도 됨*
+
+| 지표 | 계산 방식 | 목표 | 의미 |
+|------|----------|------|------|
+| **Human Turns** | 사용자 메시지(명령 포함) 횟수 | 최소화 | 사용자가 방향 전환/명확화한 횟수 |
+| **Auto Turns** | 자동 실행된 턴 수 | 최대화 | 사용자 개입 없이 진행된 턴 수 |
+| **HT/Edit 비율** | `Human Turns / Edit 횟수` | < 1.0 | 수정당 사용자 개입 빈도 |
+
+**측정 방법**: 테스트 중 사용자가 방향을 전환하거나 명확히 설명해야 하는 빈도를 기록합니다.
+
+#### 5. 워크플로우 자립 완료율 (Workflow Autonomy)
+
+> *Anthropic 기준: 사용자 수정 없이 완료되는 워크플로우*
+
+| 지표 | 계산 방식 | 목표 | 의미 |
+|------|----------|------|------|
+| **반복 수정율** | `(전체수정 - 고유파일) / 전체수정 × 100` | < 20% | 재작업 없이 완료된 비율 |
+| **효율성 점수** | 캐시·오류·작업 효율 종합 (100점) | ≥ 80 | 워크플로우 자립 완성도 |
+| **SEI** | `(Accuracy × 100) / log₁₀(Spec Volume + 1)` | — | 스펙 문서의 실효성 |
+
+**측정 방법**: 동일 요청을 3~5회 실행하여 구조적 일관성과 품질 측면에서 출력을 비교합니다.
+
+#### 6. 세션 간 일관성 (Cross-Session Consistency)
+
+> *Anthropic 기준: 세션 간 일관된 결과*
+
+| 지표 | 계산 방식 | 목표 | 의미 |
+|------|----------|------|------|
+| **Engineering Grade** | Efficiency(40%) + Stability(30%) + Precision(30%) - Penalty | S급 | 세션별 품질 등급 일관성 |
+| **등급 분포** | S/A/B/C 세션 비율 | S·A ≥ 80% | 전체 세션의 품질 편차 |
+| **스펙 유무 비교** | 스펙 있는 세션 vs 없는 세션 성과 차이 | — | 컨텍스트 효과의 일관성 |
+
+**측정 방법**: 신규 사용자가 최소한의 안내만으로 첫 시도에서 작업을 완료할 수 있는지 평가합니다.
 
 ```
-SEI = (Accuracy × 100) / log₁₀(Spec Volume + 1)
+🏆 S급 (90+): Elite — 최적화된 워크플로우, 일관된 고품질
+⭐ A급 (80+): Good — 우수한 효율성, 안정적 결과
+✅ B급 (60+): Average — 개선 여지 있음, 세션 간 편차 존재
+⚠️ C급 (40+): Below Average — 최적화 필요, 일관성 부족
 ```
 
-`.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` | 데이터 새로고침 |
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/analytics` | GET | 전체 요약 통계 |
+| `/api/sessions` | GET | 세션 목록 (SEI + Grade 포함) |
+| `/api/sessions/:id` | GET | 세션 상세 (메시지, 토큰, 파일) |
+| `/api/projects` | GET | 프로젝트 목록 |
+| `/api/config` | GET | 현재 설정 + 자동 탐색 결과 |
+| `/api/config` | POST | 프로젝트 경로 설정 저장 |
+| `/api/health` | GET | 서버 상태 확인 |
+| `/api/refresh` | POST | 데이터 새로고침 |
 
 ## 📁 Project Structure
 
 ```
 claude-cli-analytics/
-├── src/                      # React Frontend
+├── src/                          # React Frontend
 │   ├── pages/
-│   │   ├── Dashboard.tsx     # 메인 대시보드
-│   │   └── SessionDetail.tsx # 세션 상세 페이지
-│   ├── App.tsx               # 라우팅
-│   └── index.css             # Tailwind CSS
+│   │   ├── Dashboard.tsx         # 메인 대시보드
+│   │   ├── SessionDetail.tsx     # 세션 상세 페이지
+│   │   └── Setup.tsx             # 초기 설정 페이지
+│   ├── components/
+│   │   ├── InfoTooltip.tsx       # 정보 툴팁
+│   │   └── badges/
+│   │       ├── GradeBadge.tsx    # 등급 배지
+│   │       └── DangerBadge.tsx   # 위험도 배지
+│   ├── types/
+│   │   └── index.ts              # 프론트엔드 타입 정의
+│   ├── utils/
+│   │   ├── constants.ts          # 도구 아이콘 등 상수
+│   │   └── format.ts             # 포맷 유틸리티
+│   ├── App.tsx                   # 라우팅
+│   └── index.css                 # Tailwind CSS
 ├── server/
-│   ├── index.ts              # Express API 서버
-│   ├── config.ts             # 설정 + 자동 탐색
-│   ├── analyzer.ts           # 세션 분석 로직
-│   ├── parser.ts             # JSONL 파서
-│   └── types.ts              # 타입 정의
+│   ├── index.ts                  # Express API 서버
+│   ├── config.ts                 # 설정 + 자동 탐색
+│   ├── analyzer.ts               # 세션 분석 로직
+│   ├── parser.ts                 # JSONL 파서
+│   └── types.ts                  # 서버 타입 정의
 ├── bin/
-│   └── cli.js                # CLI 진입점 (--port, --path, --help)
+│   ├── cli.cjs                   # CLI 진입점 (--port, --path, --help)
+│   └── sanity.mjs                # 설치 검증 스크립트
 ├── dist/
-│   ├── client/               # 빌드된 프론트엔드
-│   └── server/               # 빌드된 백엔드
+│   ├── client/                   # 빌드된 프론트엔드
+│   └── server/                   # 빌드된 백엔드
 ├── package.json
-├── tsconfig.server.json      # 서버 빌드 설정
+├── tsconfig.server.json          # 서버 빌드 설정
 └── vite.config.ts
 ```
 

package/bin/cli.cjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+// ── Claude CLI Analytics — CLI Entry Point (CJS) ──
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn, execSync } = require('child_process');
+
+const PID_DIR = path.join(os.homedir(), '.claude-analytics');
+const PID_FILE = path.join(PID_DIR, 'server.pid');
+const LOG_FILE = path.join(PID_DIR, 'server.log');
+const SERVER_SCRIPT = path.resolve(__dirname, '..', 'dist', 'server', 'index.js');
+
+const args = process.argv.slice(2);
+const command = args.find(a => !a.startsWith('-'));
+
+// ── Help ──
+if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+  Claude CLI Analytics Dashboard
+
+  Usage: claude-cli-analytics [command] [options]
+
+  Commands:
+    (default)         Start dashboard (background)
+    exit, stop        Stop the running dashboard
+    status            Check if dashboard is running
+
+  Options:
+    --port <number>   Server port (default: 3001)
+    --path <dir>      Claude projects directory
+    --foreground, -f  Run in foreground (Ctrl+C to stop)
+    --help, -h        Show this help
+
+  Examples:
+    claude-cli-analytics              # background start
+    claude-cli-analytics exit         # stop
+    claude-cli-analytics -f           # foreground
+    claude-cli-analytics --port 8080  # custom port
+`);
+    process.exit(0);
+}
+
+// ── Helpers ──
+function readPid() {
+    try {
+        if (fs.existsSync(PID_FILE)) {
+            return parseInt(fs.readFileSync(PID_FILE, 'utf-8').trim(), 10);
+        }
+    } catch { /* */ }
+    return null;
+}
+
+function isRunning(pid) {
+    try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function getPort() {
+    const i = args.indexOf('--port');
+    return (i !== -1 && args[i + 1]) || process.env.PORT || '3001';
+}
+
+function cleanPid() {
+    try { fs.unlinkSync(PID_FILE); } catch { /* */ }
+}
+
+// ── exit / stop ──
+if (command === 'exit' || command === 'stop') {
+    const pid = readPid();
+    if (pid && isRunning(pid)) {
+        try {
+            process.kill(pid, 'SIGTERM');
+            cleanPid();
+            console.log(`  ✅ Dashboard stopped (PID: ${pid})`);
+        } catch (e) {
+            console.error(`  ❌ Failed to stop PID ${pid}: ${e.message}`);
+        }
+    } else {
+        cleanPid();
+        console.log('  ⚠️  Dashboard is not running');
+    }
+    process.exit(0);
+}
+
+// ── status ──
+if (command === 'status') {
+    const pid = readPid();
+    if (pid && isRunning(pid)) {
+        console.log(`  🟢 Running (PID: ${pid}) → http://localhost:${getPort()}`);
+    } else {
+        cleanPid();
+        console.log('  ⚪ Dashboard is not running');
+    }
+    process.exit(0);
+}
+
+// ── Start ──
+try {
+    const existingPid = readPid();
+    if (existingPid && isRunning(existingPid)) {
+        console.log(`  ⚠️  Already running (PID: ${existingPid}) → http://localhost:${getPort()}`);
+        console.log(`  Run 'claude-cli-analytics exit' to stop`);
+        process.exit(0);
+    }
+
+    // Parse env
+    const env = { ...process.env };
+    const portIdx = args.indexOf('--port');
+    if (portIdx !== -1 && args[portIdx + 1]) env.PORT = args[portIdx + 1];
+    const pathIdx = args.indexOf('--path');
+    if (pathIdx !== -1 && args[pathIdx + 1]) env.CLAUDE_PROJECTS_DIR = args[pathIdx + 1];
+
+    const foreground = args.includes('--foreground') || args.includes('-f');
+
+    if (foreground) {
+        // Foreground: import directly (CJS can require() the script, but default export handling might differ)
+        // Since `dist/server/index.js` is ESM (due to type: module in package.json), we might need `import()`
+        // However, we are in CJS now. Dynamic import works in CJS.
+        Object.assign(process.env, env);
+        (async () => {
+            try {
+                await import('../dist/server/index.js');
+            } catch (e) {
+                console.error('[CLI CRASH]', e);
+                process.exit(1);
+            }
+        })();
+    } else {
+        // Background
+        if (!fs.existsSync(PID_DIR)) fs.mkdirSync(PID_DIR, { recursive: true });
+
+        // Use append mode for log
+        const logFd = fs.openSync(LOG_FILE, 'a');
+        const port = env.PORT || '3001';
+
+        const child = spawn(process.execPath, [SERVER_SCRIPT], {
+            detached: true,
+            stdio: ['ignore', logFd, logFd],
+            env,
+        });
+
+        const pid = child.pid;
+        if (!pid) throw new Error("Failed to spawn process");
+
+        fs.writeFileSync(PID_FILE, String(pid));
+        child.unref();
+
+        console.log(`
+  🔍 Claude Analytics Dashboard
+  🌐 http://localhost:${port}
+  📋 PID: ${pid}
+
+  Stop:   claude-cli-analytics exit
+  Status: claude-cli-analytics status`);
+
+        try {
+            const cmd = process.platform === 'darwin' ? 'open'
+                : process.platform === 'win32' ? 'start' : 'xdg-open';
+            execSync(`${cmd} http://localhost:${port}`, { stdio: 'ignore' });
+        } catch { /* */ }
+
+        process.exit(0);
+    }
+} catch (err) {
+    console.error('[CLI CRASH]', err);
+    process.exit(1);
+}

package/bin/sanity.mjs

@@ -0,0 +1,3 @@
+console.log("Hello World");
+import fs from 'fs';
+console.log("Imports ok");