claude-roi 0.5.0 → 0.7.0

package/CLAUDE.md

@@ -0,0 +1,119 @@
+# CLAUDE.md — Codelens-AI
+
+## Project Overview
+
+**Codelens AI** (`claude-roi` on npm) is a CLI tool that measures ROI from AI coding agents by correlating Claude Code token usage with git commit output. It parses Claude Code session files, analyzes git history, and serves an interactive dashboard at `http://localhost:3457`.
+
+**Version:** 0.6.0
+**License:** MIT
+**npm package:** `claude-roi`
+
+## Tech Stack
+
+- **Runtime:** Node.js >= 18, ES modules (`"type": "module"`)
+- **Backend:** Express.js 5.0.0
+- **CLI:** Commander.js 13.0.0
+- **Frontend:** Single-file HTML (`src/dashboard.html`) with vanilla JS + Chart.js 4.4.7
+- **Testing:** Playwright (E2E)
+- **Styling:** Inline CSS with CSS variables, glassmorphism design, dark/light theme
+
+## Project Structure
+
+```
+src/
+├── index.js           # CLI entry point & orchestration (Commander)
+├── claude-parser.js   # Parses JSONL session files from ~/.claude/projects/
+├── git-analyzer.js    # Git log analysis, branch detection, diff stats
+├── correlator.js      # Matches sessions to commits via file overlap + time window
+├── metrics.js         # ROI calculations, grades, insights, heatmap, survival rate
+├── server.js          # Express REST API routes
+├── cache.js           # Smart caching with stale file detection
+├── dashboard.html     # Single-file SPA dashboard (3000+ lines)
+└── agents/            # Agent integration stubs (claude/, cursor/)
+
+tests/
+└── dashboard.spec.js  # Playwright E2E tests
+
+.github/workflows/
+├── ci.yml             # CI: syntax check, Node 18/20/22 matrix
+└── release.yml        # npm publish on version tag push
+```
+
+## Data Flow
+
+```
+Claude Sessions (JSONL) → claude-parser.js → [Cache] → git-analyzer.js
+→ correlator.js → metrics.js → server.js (REST API) → dashboard.html
+```
+
+## Key API Routes (server.js)
+
+- `GET /` — dashboard HTML
+- `GET /api/all` — full payload
+- `GET /api/summary` — hero stats + insights
+- `GET /api/timeline` — daily cost/output chart data
+- `GET /api/sessions` — paginated sessions with sorting
+- `GET /api/models` — model breakdown
+- `GET /api/heatmap` — productivity heatmap
+- `GET /api/tools` — tool usage breakdown
+- `GET /api/survival` — line survival stats
+- `GET /api/tokens` — detailed token analytics
+- `POST /api/refresh` — force re-parse
+
+## CLI Usage
+
+```bash
+npx claude-roi                  # defaults: 30 days, port 3457
+npx claude-roi --days 90        # custom lookback
+npx claude-roi --port 8080      # custom port
+npx claude-roi --no-open        # don't auto-open browser
+npx claude-roi --json           # dump raw JSON to stdout
+npx claude-roi --project X      # filter by project name
+npx claude-roi --refresh        # force full re-parse
+```
+
+## Development Commands
+
+```bash
+npm install                     # install dependencies
+npm test                        # run Playwright E2E tests (needs fixtures)
+node src/index.js               # run locally
+node --check src/*.js           # syntax validation
+```
+
+## Key Design Decisions
+
+- **Single-file dashboard** — no build step, served directly by Express
+- **Zero-config** — auto-discovers `~/.claude/projects/`
+- **Smart caching** — incremental parsing, only re-processes changed JSONL files (`~/.cache/agent-analytics/`)
+- **File-first correlation** — sessions matched to commits by file overlap, 2-hour temporal buffer
+- **Privacy-first** — all data stays local, no telemetry
+- **Version-aware pricing** — token costs reflect Anthropic's pricing tiers per model
+
+## Coding Conventions
+
+- ES module imports (`import`/`export`)
+- No build tooling or transpilation
+- Inline styles and scripts in dashboard.html (no external CSS/JS bundles)
+- Express 5 (path params, async error handling)
+- Functions and variables use camelCase
+- Constants defined at module top
+
+## Available Skills
+
+Use these skills when working on this project:
+
+- **`/simplify`** — Review changed code for reuse, quality, and efficiency, then fix issues found. Use after writing or modifying code.
+- **`/frontend-design`** — Create distinctive, production-grade frontend interfaces. Use when modifying `dashboard.html` or building new UI components.
+- **`/claude-developer-platform`** — Build apps with the Claude API or Anthropic SDK. Use when working on agent integrations in `src/agents/`.
+- **`/find-skills`** — Discover and install new agent skills for extended capabilities.
+- **`/keybindings-help`** — Configure keyboard shortcuts for Claude Code.
+
+## Important Notes
+
+- The dashboard is a single 3000+ line HTML file — changes should maintain the inline architecture
+- Cache is stored at `~/.cache/agent-analytics/parsed-sessions.json`
+- Session JSONL files are at `~/.claude/projects/`
+- Token pricing is hardcoded in `claude-parser.js` — update when Anthropic changes pricing
+- Playwright tests require Claude session fixtures to run (run locally, not in CI)
+- CI runs syntax checks only; E2E tests are local-only

package/README.md

@@ -1,5 +1,7 @@
 # Codelens AI
 
+**[codelensai-dev.vercel.app](https://codelensai-dev.vercel.app/)**
+
 **Agent Productivity-to-Cost Correlator** — Is your AI coding agent actually shipping code?
 
 Codelens AI ties Claude Code token usage to actual git output. It reads your local Claude Code session files, correlates them with git commits by timestamp, and serves a dashboard answering: *"Am I getting ROI from my AI coding agent?"*
@@ -77,6 +79,11 @@ This parses your `~/.claude/projects/` session data, analyzes your git repos, an
 | **Model Comparison**  | Efficiency breakdown across Opus, Sonnet, and Haiku             |
 | **Branch Awareness**  | What % of AI commits landed on production                       |
 | **Peak Hours**        | Hour-of-day x day-of-week productivity heatmap                  |
+| **Autonomy Score**    | Composite A-F grade measuring how independently the agent works |
+| **Autopilot Ratio**   | Assistant messages per user prompt (higher = more autonomous)   |
+| **Self-Heal Score**   | % of bash calls that are test/lint commands (self-verification) |
+| **Toolbelt Coverage** | % of available tools used per session (workflow breadth)        |
+| **Commit Velocity**   | Tool calls per commit (lower = more efficient)                  |
 
 ## CLI Options
 
@@ -88,6 +95,7 @@ claude-roi --no-open              # don't auto-open browser
 claude-roi --json                 # dump all metrics as JSON to stdout
 claude-roi --project techops      # filter to a specific project
 claude-roi --refresh              # force full re-parse (ignore cache)
+claude-roi --autonomy             # print autonomy score to terminal and exit
 ```
 
 ## Dashboard
@@ -100,7 +108,8 @@ The dashboard includes:
 - **Model comparison** — cost breakdown by Claude model
 - **Session length analysis** — which session sizes have the best ROI
 - **Productivity heatmap** — GitHub-style grid showing when you're most productive
-- **Sessions table** — sortable, expandable table with per-session metrics and matched commits
+- **Agent Autonomy** — autonomy score badge, autopilot ratio, self-heal score, toolbelt coverage, commit velocity, and top verification commands
+- **Sessions table** — sortable, expandable table with per-session metrics, matched commits, and autopilot ratio
 
 ## How It Works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-roi",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Correlate Claude Code token usage with git output to measure AI coding agent ROI",
   "type": "module",
   "bin": {
@@ -31,7 +31,7 @@
   "bugs": {
     "url": "https://github.com/Akshat2634/Codelens-AI/issues"
   },
-  "homepage": "https://github.com/Akshat2634/Codelens-AI#readme",
+  "homepage": "https://codelensai-dev.vercel.app/",
   "engines": {
     "node": ">=18.0.0"
   },

package/skills-lock.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "skills": {
+    "frontend-design": {
+      "source": "anthropics/skills",
+      "sourceType": "github",
+      "computedHash": "063a0e6448123cd359ad0044cc46b0e490cc7964d45ef4bb9fd842bd2ffbca67"
+    }
+  }
+}

package/src/cache.js

@@ -4,7 +4,7 @@ import os from 'node:os';
 
 const CACHE_DIR = path.join(os.homedir(), '.cache', 'agent-analytics');
 const CACHE_FILE = path.join(CACHE_DIR, 'parsed-sessions.json');
-const CACHE_VERSION = 1;
+const CACHE_VERSION = 2;
 
 export function loadCache() {
   if (!existsSync(CACHE_FILE)) {

package/src/claude-parser.js

@@ -96,6 +96,43 @@ function toRelativePath(absolutePath, repoPath) {
   return absolutePath.split('/').pop();
 }
 
+// Commands that are clearly NOT verification even if they contain matching keywords
+const NON_VERIFICATION_PATTERNS = [
+  /^\s*node\s+-e\b/,        // inline JS eval
+  /^\s*find\s+/,            // file search
+  /^\s*cat\s+/,             // file display
+  /^\s*echo\s+/,            // printing
+  /^\s*ls\b/,               // listing
+  /^\s*rm\s+/,              // file deletion
+];
+
+// Patterns that identify test/lint/typecheck commands (for autonomy self-heal score)
+const VERIFICATION_PATTERNS = [
+  /\bnpm\s+(test|run\s+(test|lint|check|typecheck))\b/,
+  /\b(pnpm|yarn|bun)\s+(run\s+)?(test|lint|check|typecheck)\b/,
+  /\b(jest|vitest|mocha|ava)\b/,
+  /\b(pytest|python\s+-m\s+(pytest|unittest))\b/,
+  /\b(go\s+test|cargo\s+(test|clippy))\b/,
+  /\b(eslint|biome|prettier\b.*--check)/,
+  /\btsc(\s+--noEmit|\s+-p)\b/,
+  /\b(mypy|ruff|flake8|pylint|rubocop)\b/,
+  /\bnode\s+--check\b/,
+  /\bmake\s+(test|check|lint)\b/,
+];
+
+function isVerificationCommand(command) {
+  if (!command || typeof command !== 'string') return false;
+  // Strip cd/path and env var prefixes to get the core command
+  const core = command
+    .replace(/^(?:cd\s+\S+\s*&&\s*)+/g, '')
+    .replace(/^(?:cd\s+\S+\s*;\s*)+/g, '')
+    .replace(/^(?:\w+=\S+\s+)+/g, '')
+    .trim();
+  // Exclude commands that are clearly not verification
+  if (NON_VERIFICATION_PATTERNS.some(p => p.test(core))) return false;
+  return VERIFICATION_PATTERNS.some(p => p.test(core));
+}
+
 function extractToolUse(session, msg) {
   const content = msg.content;
   if (!Array.isArray(content)) return;
@@ -108,6 +145,17 @@ function extractToolUse(session, msg) {
     // Count tool calls
     session.toolCalls[toolName] = (session.toolCalls[toolName] || 0) + 1;
 
+    // Track Bash commands for autonomy self-heal scoring
+    if (toolName === 'Bash') {
+      const command = block.input?.command || block.input?.content;
+      if (command) {
+        session.totalBashCalls++;
+        const isVerif = isVerificationCommand(command);
+        if (isVerif) session.verificationBashCalls++;
+        session.bashCommands.push({ command: command.slice(0, 200), isVerification: isVerif });
+      }
+    }
+
     // Track files written/read
     const filePath = block.input?.file_path;
     if (!filePath) continue;
@@ -145,6 +193,9 @@ function createEmptySession(sessionId) {
     filesRead: [],
     userMessageCount: 0,
     assistantMessageCount: 0,
+    bashCommands: [],
+    totalBashCalls: 0,
+    verificationBashCalls: 0,
   };
 }
 
@@ -380,6 +431,11 @@ function mergeSubagentIntoSession(parent, sub) {
     parent.toolCalls[tool] = (parent.toolCalls[tool] || 0) + count;
   }
 
+  // Merge bash command tracking
+  parent.totalBashCalls += sub.totalBashCalls;
+  parent.verificationBashCalls += sub.verificationBashCalls;
+  parent.bashCommands.push(...sub.bashCommands);
+
   // Merge files
   for (const f of sub.filesWritten) {
     if (!parent.filesWritten.includes(f)) parent.filesWritten.push(f);