chekk 0.1.0

package/bin/chekk.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { run } from '../src/index.js';
+
+const program = new Command();
+
+program
+  .name('chekk')
+  .description('See how you prompt. Analyze your AI coding workflow.')
+  .version('0.1.0')
+  .option('--offline', 'Skip prose generation and show raw metrics only')
+  .option('--json', 'Output raw metrics as JSON')
+  .option('--no-upload', 'Skip the claim/upload prompt')
+  .action(async (options) => {
+    await run(options);
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "chekk",
+  "version": "0.1.0",
+  "description": "See how you prompt. Chekk analyzes your AI coding workflow and tells you what kind of engineer you are.",
+  "bin": {
+    "chekk": "./bin/chekk.js"
+  },
+  "type": "module",
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "start": "node bin/chekk.js"
+  },
+  "keywords": [
+    "ai",
+    "coding",
+    "claude",
+    "cursor",
+    "copilot",
+    "developer",
+    "analysis",
+    "prompt",
+    "engineering",
+    "vibe-coding",
+    "workflow"
+  ],
+  "author": "Chekk <timi@chekk.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/omarionnn/chekk"
+  },
+  "homepage": "https://chekk.dev",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "ora": "^8.0.1"
+  }
+}

package/src/detect.js

@@ -0,0 +1,94 @@
+import { existsSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+/**
+ * Detect installed AI coding tools and count available sessions.
+ */
+export function detectTools() {
+  const home = homedir();
+  const results = [];
+
+  // Claude Code: ~/.claude/projects/
+  const claudeProjectsDir = join(home, '.claude', 'projects');
+  if (existsSync(claudeProjectsDir)) {
+    const projects = readdirSync(claudeProjectsDir).filter(f => {
+      const full = join(claudeProjectsDir, f);
+      return statSync(full).isDirectory();
+    });
+
+    let totalSessions = 0;
+    let totalLines = 0;
+    const projectDetails = [];
+
+    for (const project of projects) {
+      const projectDir = join(claudeProjectsDir, project);
+      const jsonlFiles = readdirSync(projectDir).filter(f =>
+        f.endsWith('.jsonl') && !f.startsWith('agent-')
+      );
+
+      if (jsonlFiles.length > 0) {
+        totalSessions += jsonlFiles.length;
+        // Rough line count for display
+        for (const file of jsonlFiles) {
+          try {
+            const stat = statSync(join(projectDir, file));
+            totalLines += Math.floor(stat.size / 500); // rough estimate
+          } catch {}
+        }
+        projectDetails.push({
+          name: project.replace(/-/g, '/').replace(/^\//, ''),
+          sessions: jsonlFiles.length,
+          path: projectDir,
+        });
+      }
+    }
+
+    if (totalSessions > 0) {
+      results.push({
+        tool: 'Claude Code',
+        sessions: totalSessions,
+        projects: projectDetails,
+        estimatedPrompts: totalLines,
+        basePath: claudeProjectsDir,
+      });
+    }
+  }
+
+  // Cursor: ~/Library/Application Support/Cursor/User/workspaceStorage/
+  const cursorPaths = [
+    join(home, 'Library', 'Application Support', 'Cursor', 'User', 'workspaceStorage'),  // macOS
+    join(home, '.config', 'Cursor', 'User', 'workspaceStorage'),  // Linux
+    join(home, 'AppData', 'Roaming', 'Cursor', 'User', 'workspaceStorage'),  // Windows
+  ];
+  for (const cursorPath of cursorPaths) {
+    if (existsSync(cursorPath)) {
+      results.push({
+        tool: 'Cursor',
+        sessions: 0,
+        projects: [],
+        estimatedPrompts: 0,
+        basePath: cursorPath,
+        status: 'detected_not_supported',
+        message: 'Cursor support coming in V2',
+      });
+      break;
+    }
+  }
+
+  // Codex: ~/.codex/
+  const codexPath = join(home, '.codex');
+  if (existsSync(codexPath)) {
+    results.push({
+      tool: 'Codex',
+      sessions: 0,
+      projects: [],
+      estimatedPrompts: 0,
+      basePath: codexPath,
+      status: 'detected_not_supported',
+      message: 'Codex support coming in V2',
+    });
+  }
+
+  return results;
+}

package/src/display.js

@@ -0,0 +1,137 @@
+import chalk from 'chalk';
+
+/**
+ * Display detection results.
+ */
+export function displayDetection(tools) {
+  console.log();
+
+  for (const tool of tools) {
+    if (tool.status === 'detected_not_supported') {
+      console.log(chalk.dim(`   Found ${tool.tool} — ${tool.message}`));
+    } else {
+      console.log(
+        chalk.green(`   Found ${tool.tool}`) +
+        chalk.dim(` (${tool.sessions} sessions across ${tool.projects.length} projects)`)
+      );
+    }
+  }
+  console.log();
+}
+
+/**
+ * Display a progress bar.
+ */
+function progressBar(score, width = 20) {
+  const filled = Math.round((score / 100) * width);
+  const empty = width - filled;
+
+  const color = score >= 80 ? chalk.green :
+                score >= 60 ? chalk.yellow :
+                score >= 40 ? chalk.hex('#FFA500') :
+                chalk.red;
+
+  return color('\u2588'.repeat(filled)) + chalk.dim('\u2591'.repeat(empty));
+}
+
+/**
+ * Display the final Chekk results with prose from the API.
+ */
+export function displayResults(result, prose) {
+  const { overall, archetype, tier } = result;
+
+  const tierColor = tier === 'LEGENDARY' ? chalk.hex('#FFD700') :
+                    tier === 'RARE' ? chalk.hex('#A855F7') :
+                    tier === 'UNCOMMON' ? chalk.hex('#3B82F6') :
+                    chalk.dim;
+
+  console.log(chalk.dim('\u2500'.repeat(50)));
+  console.log();
+
+  // Prose sections
+  if (prose && prose.sections) {
+    for (const section of prose.sections) {
+      console.log(`   ${section.emoji}  ${chalk.bold(section.title)}`);
+      // Word-wrap the description
+      const lines = wordWrap(section.description, 45);
+      for (const line of lines) {
+        console.log(chalk.italic(`   ${chalk.dim('"')}${line}${chalk.dim('"')}`));
+      }
+      console.log();
+    }
+  }
+
+  console.log(chalk.dim('\u2500'.repeat(50)));
+  console.log();
+
+  // Archetype + tier
+  console.log(`   ${chalk.bold('\u2192')} You're ${chalk.bold.white(archetype.name)}`);
+  if (prose && prose.tagline) {
+    console.log(`     ${chalk.dim('"' + prose.tagline + '"')}`);
+  }
+  console.log();
+  console.log(`   ${chalk.bold('\u2192')} Tier: ${tierColor(tier)}  ${progressBar(overall)} ${chalk.bold(overall)}`);
+  console.log();
+}
+
+/**
+ * Display offline/raw metric results (no API call).
+ */
+export function displayOfflineResults(result) {
+  const { overall, scores, archetype, tier } = result;
+
+  const tierColor = tier === 'LEGENDARY' ? chalk.hex('#FFD700') :
+                    tier === 'RARE' ? chalk.hex('#A855F7') :
+                    tier === 'UNCOMMON' ? chalk.hex('#3B82F6') :
+                    chalk.dim;
+
+  console.log(chalk.dim('\u2500'.repeat(50)));
+  console.log();
+
+  console.log(`   ${chalk.bold('Decomposition')}    ${progressBar(scores.decomposition)}  ${scores.decomposition}`);
+  console.log(`   ${chalk.bold('Debug Efficiency')} ${progressBar(scores.debugCycles)}  ${scores.debugCycles}`);
+  console.log(`   ${chalk.bold('AI Leverage')}      ${progressBar(scores.aiLeverage)}  ${scores.aiLeverage}`);
+  console.log(`   ${chalk.bold('Workflow')}         ${progressBar(scores.sessionStructure)}  ${scores.sessionStructure}`);
+  console.log();
+  console.log(chalk.dim('\u2500'.repeat(50)));
+  console.log();
+
+  console.log(`   ${chalk.bold('\u2192')} You're ${chalk.bold.white(archetype.name)}`);
+  console.log(`   ${chalk.bold('\u2192')} Tier: ${tierColor(tier)}  ${progressBar(overall)} ${chalk.bold(overall)}`);
+  console.log();
+  console.log(chalk.dim('   Run without --offline for personalized AI-generated insights'));
+  console.log();
+}
+
+/**
+ * Display the claim prompt.
+ */
+export function displayClaimPrompt(claimUrl) {
+  console.log(chalk.dim('\u2500'.repeat(50)));
+  console.log();
+  console.log(`   ${chalk.bold('Claim your profile:')} ${chalk.cyan.underline(claimUrl)}`);
+  console.log();
+  console.log(chalk.dim('   Connect GitHub + LinkedIn to make your profile'));
+  console.log(chalk.dim('   visible to companies hiring AI-native engineers.'));
+  console.log();
+}
+
+/**
+ * Word wrap text to a max width.
+ */
+function wordWrap(text, maxWidth) {
+  const words = text.split(' ');
+  const lines = [];
+  let current = '';
+
+  for (const word of words) {
+    if (current.length + word.length + 1 > maxWidth && current.length > 0) {
+      lines.push(current);
+      current = word;
+    } else {
+      current = current ? current + ' ' + word : word;
+    }
+  }
+  if (current) lines.push(current);
+  return lines;
+}

package/src/index.js

@@ -0,0 +1,154 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { detectTools } from './detect.js';
+import { parseAllProjects } from './parsers/claude-code.js';
+import { computeDecomposition } from './metrics/decomposition.js';
+import { computeDebugCycles } from './metrics/debug-cycles.js';
+import { computeAILeverage } from './metrics/ai-leverage.js';
+import { computeSessionStructure } from './metrics/session-structure.js';
+import { computeOverallScore } from './scorer.js';
+import { displayDetection, displayResults, displayOfflineResults, displayClaimPrompt } from './display.js';
+import { generateProse, askClaim, uploadAndClaim } from './upload.js';
+
+export async function run(options = {}) {
+  console.log();
+  console.log(chalk.bold('   chekk') + chalk.dim(' — see how you prompt'));
+  console.log();
+
+  // Step 1: Detect tools
+  const spinner = ora({ text: 'Scanning for AI coding tools...', indent: 3 }).start();
+  const tools = detectTools();
+
+  if (tools.length === 0) {
+    spinner.fail('No AI coding tools detected');
+    console.log();
+    console.log(chalk.dim('   Chekk currently supports Claude Code.'));
+    console.log(chalk.dim('   Cursor and Codex support coming in V2.'));
+    console.log();
+    process.exit(1);
+  }
+
+  const supported = tools.filter(t => t.status !== 'detected_not_supported');
+  if (supported.length === 0) {
+    spinner.fail('No supported AI tools found');
+    console.log();
+    for (const t of tools) {
+      console.log(chalk.dim(`   Found ${t.tool} — ${t.message}`));
+    }
+    console.log();
+    process.exit(1);
+  }
+
+  spinner.succeed('Found AI coding tools');
+  displayDetection(tools);
+
+  // Step 2: Parse sessions
+  const parseSpinner = ora({ text: 'Parsing session history...', indent: 3 }).start();
+
+  let allSessions = [];
+  for (const tool of supported) {
+    if (tool.tool === 'Claude Code') {
+      const sessions = parseAllProjects(tool.basePath);
+      allSessions.push(...sessions);
+    }
+  }
+
+  if (allSessions.length === 0) {
+    parseSpinner.fail('No sessions found to analyze');
+    console.log();
+    process.exit(1);
+  }
+
+  // Count stats
+  const totalExchanges = allSessions.reduce((sum, s) => sum + s.exchangeCount, 0);
+  const projects = [...new Set(allSessions.map(s => s.project))];
+
+  // Date range
+  const allTimestamps = allSessions
+    .map(s => s.startTime)
+    .filter(Boolean)
+    .map(t => new Date(t))
+    .sort((a, b) => a - b);
+  const dateRange = allTimestamps.length >= 2
+    ? `${allTimestamps[0].toLocaleDateString()} to ${allTimestamps[allTimestamps.length - 1].toLocaleDateString()}`
+    : 'unknown';
+
+  parseSpinner.succeed(
+    `Parsed ${chalk.bold(allSessions.length)} sessions, ${chalk.bold(totalExchanges)} exchanges`
+  );
+  console.log(chalk.dim(`      ${projects.length} projects — ${dateRange}`));
+  console.log();
+
+  // Step 3: Compute metrics
+  const metricsSpinner = ora({ text: 'Analyzing your workflow patterns...', indent: 3 }).start();
+
+  const metrics = {
+    decomposition: computeDecomposition(allSessions),
+    debugCycles: computeDebugCycles(allSessions),
+    aiLeverage: computeAILeverage(allSessions),
+    sessionStructure: computeSessionStructure(allSessions),
+  };
+
+  const result = computeOverallScore(metrics);
+
+  metricsSpinner.succeed('Analysis complete');
+  console.log();
+
+  const sessionStats = {
+    totalSessions: allSessions.length,
+    totalExchanges,
+    projectCount: projects.length,
+    dateRange,
+    tools: supported.map(t => t.tool),
+  };
+
+  // JSON output mode
+  if (options.json) {
+    console.log(JSON.stringify({ metrics, result, sessionStats }, null, 2));
+    return;
+  }
+
+  // Step 4: Generate prose (unless offline)
+  if (options.offline) {
+    displayOfflineResults(result);
+  } else {
+    const proseSpinner = ora({ text: 'Generating your personalized profile...', indent: 3 }).start();
+
+    try {
+      const proseResponse = await generateProse(metrics, result, sessionStats);
+      proseSpinner.succeed('Profile generated');
+      console.log();
+      displayResults(result, proseResponse);
+    } catch (err) {
+      proseSpinner.warn('Could not reach chekk.dev — showing raw scores');
+      console.log();
+      displayOfflineResults(result);
+    }
+  }
+
+  // Step 5: Claim prompt
+  if (options.upload !== false) {
+    try {
+      const wantsClaim = await askClaim();
+      if (wantsClaim) {
+        const claimSpinner = ora({ text: 'Creating your profile...', indent: 3 }).start();
+        try {
+          const claimResult = await uploadAndClaim(metrics, result, sessionStats);
+          claimSpinner.succeed('Profile created');
+          displayClaimPrompt(claimResult.claimUrl || 'https://chekk.dev/claim');
+        } catch (err) {
+          claimSpinner.fail('Could not create profile — try again later');
+          console.log(chalk.dim(`      ${err.message}`));
+          console.log();
+        }
+      } else {
+        console.log();
+        console.log(chalk.dim('   No worries. Run `npx chekk` again anytime to claim your score.'));
+        console.log();
+      }
+    } catch {
+      // stdin not available (piped), skip claim
+      console.log();
+    }
+  }
+}

package/src/metrics/ai-leverage.js

@@ -0,0 +1,124 @@
+/**
+ * AI Leverage
+ *
+ * Measures whether the engineer uses AI for high-level design and architecture
+ * or mostly for boilerplate and simple tasks.
+ *
+ * Signals:
+ * - Architectural/design prompts vs boilerplate/CRUD prompts
+ * - Complexity of requested tasks
+ * - Usage of AI for planning, design review, code review
+ * - Diversity of tool usage (not just "write code" but also explore, analyze, test)
+ */
+
+const architecturalPatterns = /\b(architect|design|refactor|redesign|restructure|system design|data model|schema|api design|interface|abstract|pattern|trade-?off|scalab|approach|strategy|migration|infrastructure)\b/i;
+const planningPatterns = /\b(plan|breakdown|break down|think through|help me think|what('?s| is) the best (way|approach)|how should (i|we)|pros and cons|options for|compare|evaluate|review my|code review|audit)\b/i;
+const exploratoryPatterns = /\b(explain|understand|how does|what does|why does|walk me through|investigate|diagnose|analyze|explore|deep dive|look into)\b/i;
+const boilerplatePatterns = /\b(add a (button|field|column|route|endpoint|page|component)|create a (form|modal|table|list|card)|simple (function|class|component)|CRUD|boilerplate|scaffold|template|generate (a |the )?(basic|simple))\b/i;
+const testingPatterns = /\b(test|spec|unit test|integration test|e2e|coverage|assert|expect|mock|fixture)\b/i;
+
+const highLeverageTools = ['Task', 'WebSearch', 'WebFetch', 'Grep', 'Glob', 'Read'];
+const codingTools = ['Write', 'Edit', 'Bash', 'NotebookEdit'];
+
+export function computeAILeverage(sessions) {
+  if (sessions.length === 0) return { score: 50, details: {} };
+
+  let totalPrompts = 0;
+  let architecturalPrompts = 0;
+  let planningPrompts = 0;
+  let exploratoryPrompts = 0;
+  let boilerplatePrompts = 0;
+  let testingPrompts = 0;
+  let highLeverageToolUses = 0;
+  let codingToolUses = 0;
+  let totalToolUses = 0;
+
+  // Track prompt complexity via length and structure
+  let complexPrompts = 0; // > 200 chars with multiple sentences
+  let trivialPrompts = 0; // < 50 chars, simple commands
+
+  for (const session of sessions) {
+    for (const exchange of session.exchanges) {
+      const prompt = exchange.userPrompt || '';
+      totalPrompts++;
+
+      // Categorize prompt type
+      if (architecturalPatterns.test(prompt)) architecturalPrompts++;
+      if (planningPatterns.test(prompt)) planningPrompts++;
+      if (exploratoryPatterns.test(prompt)) exploratoryPrompts++;
+      if (boilerplatePatterns.test(prompt)) boilerplatePrompts++;
+      if (testingPatterns.test(prompt)) testingPrompts++;
+
+      // Complexity
+      const sentences = prompt.split(/[.!?]+/).filter(s => s.trim().length > 10);
+      if (prompt.length > 200 && sentences.length >= 2) {
+        complexPrompts++;
+      } else if (prompt.length < 50) {
+        trivialPrompts++;
+      }
+
+      // Tool usage from assistant responses
+      for (const tool of exchange.toolCalls) {
+        totalToolUses++;
+        const toolName = tool.tool || '';
+        if (highLeverageTools.some(t => toolName.includes(t))) {
+          highLeverageToolUses++;
+        }
+        if (codingTools.some(t => toolName.includes(t))) {
+          codingToolUses++;
+        }
+      }
+    }
+  }
+
+  // Score components
+
+  // High-level thinking ratio (architectural + planning + exploratory vs total)
+  const highLevelPrompts = architecturalPrompts + planningPrompts + exploratoryPrompts;
+  const highLevelRatio = totalPrompts > 0 ? highLevelPrompts / totalPrompts : 0;
+  const highLevelScore = Math.min(100, highLevelRatio * 250); // 40%+ = 100
+
+  // Boilerplate ratio (lower is better)
+  const boilerplateRatio = totalPrompts > 0 ? boilerplatePrompts / totalPrompts : 0;
+  const boilerplatePenalty = boilerplateRatio * 60;
+
+  // Complexity ratio
+  const complexRatio = totalPrompts > 0 ? complexPrompts / totalPrompts : 0;
+  const complexScore = Math.min(100, complexRatio * 300);
+
+  // Tool diversity - using AI for research/exploration not just coding
+  const researchToolRatio = totalToolUses > 0 ? highLeverageToolUses / totalToolUses : 0.5;
+  const toolDiversityScore = Math.min(100, researchToolRatio * 200);
+
+  // Testing awareness
+  const testingRatio = totalPrompts > 0 ? testingPrompts / totalPrompts : 0;
+  const testingBonus = Math.min(20, testingRatio * 200);
+
+  const score = Math.round(
+    highLevelScore * 0.35 +
+    (100 - boilerplatePenalty) * 0.2 +
+    complexScore * 0.2 +
+    toolDiversityScore * 0.15 +
+    testingBonus * 0.1 +
+    50 * 0  // baseline filler
+  );
+
+  return {
+    score: Math.max(0, Math.min(100, score)),
+    details: {
+      totalPrompts,
+      architecturalPrompts,
+      planningPrompts,
+      exploratoryPrompts,
+      boilerplatePrompts,
+      testingPrompts,
+      highLevelRatio: Math.round(highLevelRatio * 100),
+      complexPromptRatio: Math.round(complexRatio * 100),
+      toolDiversity: {
+        total: totalToolUses,
+        research: highLeverageToolUses,
+        coding: codingToolUses,
+      },
+    },
+  };
+}

package/src/metrics/debug-cycles.js

@@ -0,0 +1,124 @@
+/**
+ * Debug Cycle Efficiency
+ *
+ * Measures how effectively the engineer resolves issues with AI assistance.
+ *
+ * Signals:
+ * - Error/fix loops: user reports error → assistant tries fix → user reports same error
+ * - Number of turns to resolution
+ * - Quality of error context provided (stack traces, specific error messages)
+ * - "it's still broken" vs targeted debug prompts
+ */
+
+const errorPatterns = /\b(error|bug|broken|crash|fail|exception|traceback|stack trace|doesn'?t work|not working|issue|problem|wrong)\b/i;
+const vaguePhrases = /^(it'?s? (?:still )?(?:not working|broken|wrong|failing))|^(fix it|try again|still (?:the same|broken|failing|not working))|^(same (?:error|issue|problem|thing))/i;
+const specificDebugPatterns = /\b(line \d+|TypeError|SyntaxError|ImportError|ReferenceError|ValueError|KeyError|AttributeError|NoneType|undefined is not|cannot read prop|stack trace|traceback|\.py:\d+|\.ts:\d+|\.js:\d+|status (?:code )?\d{3}|HTTP \d{3}|ENOENT|EACCES|CORS|404|500|502|503)\b/i;
+const resolutionPatterns = /\b(works|working|fixed|solved|resolved|perfect|great|thanks|nice|awesome|that did it|looks good|ship it)\b/i;
+
+export function computeDebugCycles(sessions) {
+  if (sessions.length === 0) return { score: 50, details: {} };
+
+  let totalDebugSequences = 0;
+  let totalTurnsToResolve = 0;
+  let vagueReports = 0;
+  let specificReports = 0;
+  let unresolvedSequences = 0;
+  let quickFixes = 0; // resolved in 1-2 turns
+  let longLoops = 0; // > 5 turns to resolve
+
+  for (const session of sessions) {
+    const { exchanges } = session;
+    let inDebugMode = false;
+    let debugTurnCount = 0;
+
+    for (let i = 0; i < exchanges.length; i++) {
+      const prompt = exchanges[i].userPrompt || '';
+
+      if (errorPatterns.test(prompt)) {
+        if (!inDebugMode) {
+          // Starting a new debug sequence
+          inDebugMode = true;
+          debugTurnCount = 1;
+          totalDebugSequences++;
+        } else {
+          debugTurnCount++;
+        }
+
+        // Check quality of error report
+        if (vaguePhrases.test(prompt)) {
+          vagueReports++;
+        }
+        if (specificDebugPatterns.test(prompt) || prompt.length > 200) {
+          specificReports++;
+        }
+      } else if (inDebugMode) {
+        // Check if this exchange resolves the debug
+        if (resolutionPatterns.test(prompt)) {
+          totalTurnsToResolve += debugTurnCount;
+          if (debugTurnCount <= 2) quickFixes++;
+          if (debugTurnCount > 5) longLoops++;
+          inDebugMode = false;
+          debugTurnCount = 0;
+        } else {
+          // Moved on without explicit resolution
+          totalTurnsToResolve += debugTurnCount;
+          unresolvedSequences++;
+          inDebugMode = false;
+          debugTurnCount = 0;
+        }
+      }
+    }
+
+    // Handle session ending mid-debug
+    if (inDebugMode) {
+      totalTurnsToResolve += debugTurnCount;
+      if (debugTurnCount > 5) longLoops++;
+    }
+  }
+
+  const avgTurnsToResolve = totalDebugSequences > 0
+    ? totalTurnsToResolve / totalDebugSequences
+    : 0;
+
+  const totalReports = vagueReports + specificReports;
+  const specificRatio = totalReports > 0 ? specificReports / totalReports : 0.5;
+
+  // Score components
+  // Fewer turns to resolve = better
+  const turnsScore = avgTurnsToResolve === 0 ? 70 :
+                     avgTurnsToResolve <= 2 ? 95 :
+                     avgTurnsToResolve <= 3 ? 85 :
+                     avgTurnsToResolve <= 5 ? 65 :
+                     avgTurnsToResolve <= 8 ? 40 : 20;
+
+  // More specific reports = better
+  const specificScore = specificRatio * 100;
+
+  // Quick fix ratio
+  const quickFixRatio = totalDebugSequences > 0 ? quickFixes / totalDebugSequences : 0.5;
+  const quickFixScore = quickFixRatio * 100;
+
+  // Long loop penalty
+  const longLoopRatio = totalDebugSequences > 0 ? longLoops / totalDebugSequences : 0;
+  const longLoopPenalty = longLoopRatio * 50;
+
+  const score = Math.round(
+    turnsScore * 0.35 +
+    specificScore * 0.25 +
+    quickFixScore * 0.25 +
+    (100 - longLoopPenalty) * 0.15
+  );
+
+  return {
+    score: Math.max(0, Math.min(100, score)),
+    details: {
+      totalDebugSequences,
+      avgTurnsToResolve: Math.round(avgTurnsToResolve * 10) / 10,
+      quickFixes,
+      longLoops,
+      specificReportRatio: Math.round(specificRatio * 100),
+      vagueReports,
+      specificReports,
+    },
+  };
+}

package/src/metrics/decomposition.js

@@ -0,0 +1,98 @@
+/**
+ * Decomposition Quality
+ *
+ * Measures whether the engineer breaks complex tasks into subtasks
+ * or dumps everything in single mega-prompts.
+ *
+ * Signals:
+ * - Multi-step sessions (multiple exchanges building on each other) → higher
+ * - Single mega-prompt sessions → lower
+ * - Prompt length distribution (long single prompts = less decomposition)
+ * - Follow-up prompts that reference or build on previous context
+ */
+
+export function computeDecomposition(sessions) {
+  if (sessions.length === 0) return { score: 50, details: {} };
+
+  let totalExchanges = 0;
+  let multiStepSessions = 0;
+  let singleShotSessions = 0;
+  let avgPromptLength = 0;
+  let promptCount = 0;
+  let longPromptCount = 0; // > 500 chars
+  let shortPromptCount = 0; // < 100 chars
+  let contextualFollowups = 0; // prompts that start with "now", "next", "also", "then", reference prev context
+
+  const followupPatterns = /^(now |next |then |also |and |ok |okay |great |good |perfect |after that|building on|following up|continuing)/i;
+  const refinementPatterns = /^(actually |wait |hmm |instead |change |modify |update |tweak |adjust |fix |but )/i;
+
+  for (const session of sessions) {
+    const { exchanges } = session;
+    totalExchanges += exchanges.length;
+
+    if (exchanges.length >= 4) {
+      multiStepSessions++;
+    } else if (exchanges.length === 1) {
+      singleShotSessions++;
+    }
+
+    for (let i = 0; i < exchanges.length; i++) {
+      const prompt = exchanges[i].userPrompt || '';
+      const len = prompt.length;
+      promptCount++;
+      avgPromptLength += len;
+
+      if (len > 500) longPromptCount++;
+      if (len < 100) shortPromptCount++;
+
+      // Check for contextual followups (not the first prompt in a session)
+      if (i > 0) {
+        if (followupPatterns.test(prompt) || refinementPatterns.test(prompt)) {
+          contextualFollowups++;
+        }
+      }
+    }
+  }
+
+  avgPromptLength = promptCount > 0 ? avgPromptLength / promptCount : 0;
+
+  // Score components (each 0-100)
+  const multiStepRatio = sessions.length > 0 ? multiStepSessions / sessions.length : 0;
+  const multiStepScore = Math.min(100, multiStepRatio * 150); // bonus for > 66%
+
+  const singleShotRatio = sessions.length > 0 ? singleShotSessions / sessions.length : 0;
+  const singleShotPenalty = singleShotRatio * 40; // up to -40
+
+  // Moderate prompt length is good (not too mega, not too terse)
+  const lengthScore = avgPromptLength > 50 && avgPromptLength < 400 ? 80 :
+                      avgPromptLength >= 400 && avgPromptLength < 800 ? 60 :
+                      avgPromptLength >= 800 ? 30 : 50;
+
+  // Contextual followups show iterative thinking
+  const followupRatio = promptCount > 0 ? contextualFollowups / promptCount : 0;
+  const followupScore = Math.min(100, followupRatio * 300);
+
+  const avgExchangesPerSession = sessions.length > 0 ? totalExchanges / sessions.length : 0;
+  const depthScore = Math.min(100, avgExchangesPerSession * 8); // 12+ exchanges = 100
+
+  const score = Math.round(
+    multiStepScore * 0.25 +
+    (100 - singleShotPenalty) * 0.15 +
+    lengthScore * 0.2 +
+    followupScore * 0.2 +
+    depthScore * 0.2
+  );
+
+  return {
+    score: Math.max(0, Math.min(100, score)),
+    details: {
+      totalSessions: sessions.length,
+      multiStepSessions,
+      singleShotSessions,
+      avgExchangesPerSession: Math.round(avgExchangesPerSession * 10) / 10,
+      avgPromptLength: Math.round(avgPromptLength),
+      longPromptRatio: promptCount > 0 ? Math.round(longPromptCount / promptCount * 100) : 0,
+      contextualFollowupRatio: promptCount > 0 ? Math.round(followupRatio * 100) : 0,
+    },
+  };
+}

package/src/metrics/session-structure.js

@@ -0,0 +1,134 @@
+/**
+ * Session Structure / Workflow Quality
+ *
+ * Measures how deliberate and structured the engineer's workflow is.
+ *
+ * Signals:
+ * - Do sessions start with context-setting? (explaining what needs to happen)
+ * - Do they plan before diving into code?
+ * - Is there a review/validation step at the end?
+ * - Session duration distribution (very short = throwaway, very long = unfocused)
+ * - Modification rate of AI output (shows critical review)
+ */
+
+const contextSettingPatterns = /^(i('?m| am) (working on|building|trying to|looking at)|we need to|the goal is|here'?s (the|what)|context:|background:|i have a|there'?s a|i want to|let me explain)/i;
+const planningStartPatterns = /^(let'?s (plan|think|figure|start by)|first,? (let'?s|we should)|before we (start|begin|code)|the plan is|step 1|here'?s (my|the) plan)/i;
+const reviewPatterns = /\b(looks good|ship it|deploy|push it|commit|merge|let'?s go|lgtm|approved|test it|run (the )?tests|build it|does this look|review this|check this)\b/i;
+const refinementPatterns = /\b(actually|wait|hmm|instead|change|modify|tweak|adjust|no,? |not quite|close but|almost|that'?s not)\b/i;
+
+export function computeSessionStructure(sessions) {
+  if (sessions.length === 0) return { score: 50, details: {} };
+
+  let contextSetSessions = 0;
+  let planBeforeCodeSessions = 0;
+  let reviewEndSessions = 0;
+  let refinementCount = 0;
+  let totalExchanges = 0;
+
+  // Duration distribution
+  let shortSessions = 0; // < 5 min
+  let mediumSessions = 0; // 5-60 min
+  let longSessions = 0; // > 60 min
+  let focusedSessions = 0; // 10-45 min (sweet spot)
+
+  // First prompt length distribution (longer first prompts = more context setting)
+  let firstPromptTotalLength = 0;
+
+  for (const session of sessions) {
+    const { exchanges, durationMinutes } = session;
+    if (exchanges.length === 0) continue;
+
+    totalExchanges += exchanges.length;
+
+    // Check if session starts with context
+    const firstPrompt = exchanges[0].userPrompt || '';
+    firstPromptTotalLength += firstPrompt.length;
+
+    if (contextSettingPatterns.test(firstPrompt) || firstPrompt.length > 200) {
+      contextSetSessions++;
+    }
+
+    if (planningStartPatterns.test(firstPrompt)) {
+      planBeforeCodeSessions++;
+    }
+
+    // Check if session ends with review/validation
+    if (exchanges.length >= 2) {
+      const lastPrompt = exchanges[exchanges.length - 1].userPrompt || '';
+      const secondLastPrompt = exchanges.length >= 3 ? exchanges[exchanges.length - 2].userPrompt || '' : '';
+      if (reviewPatterns.test(lastPrompt) || reviewPatterns.test(secondLastPrompt)) {
+        reviewEndSessions++;
+      }
+    }
+
+    // Count refinements (shows critical evaluation)
+    for (let i = 1; i < exchanges.length; i++) {
+      const prompt = exchanges[i].userPrompt || '';
+      if (refinementPatterns.test(prompt)) {
+        refinementCount++;
+      }
+    }
+
+    // Duration buckets
+    if (durationMinutes !== undefined && durationMinutes !== null) {
+      if (durationMinutes < 5) shortSessions++;
+      else if (durationMinutes <= 60) mediumSessions++;
+      else longSessions++;
+
+      if (durationMinutes >= 10 && durationMinutes <= 45) focusedSessions++;
+    }
+  }
+
+  const sessionsWithExchanges = sessions.filter(s => s.exchanges.length > 0).length;
+
+  // Score components
+  const contextRatio = sessionsWithExchanges > 0 ? contextSetSessions / sessionsWithExchanges : 0;
+  const contextScore = Math.min(100, contextRatio * 170);
+
+  const planRatio = sessionsWithExchanges > 0 ? planBeforeCodeSessions / sessionsWithExchanges : 0;
+  const planScore = Math.min(100, planRatio * 300);
+
+  const reviewRatio = sessionsWithExchanges > 0 ? reviewEndSessions / sessionsWithExchanges : 0;
+  const reviewScore = Math.min(100, reviewRatio * 200);
+
+  // Refinement shows critical thinking
+  const refinementRatio = totalExchanges > 0 ? refinementCount / totalExchanges : 0;
+  const refinementScore = Math.min(100, refinementRatio * 400);
+
+  // Duration focus (medium/focused sessions are ideal)
+  const totalWithDuration = shortSessions + mediumSessions + longSessions;
+  const focusedRatio = totalWithDuration > 0 ? focusedSessions / totalWithDuration : 0.5;
+  const focusScore = Math.min(100, focusedRatio * 170);
+
+  // Average first prompt length (longer = more thoughtful setup)
+  const avgFirstPromptLength = sessionsWithExchanges > 0 ? firstPromptTotalLength / sessionsWithExchanges : 0;
+  const firstPromptScore = avgFirstPromptLength > 300 ? 90 :
+                           avgFirstPromptLength > 150 ? 75 :
+                           avgFirstPromptLength > 50 ? 55 : 35;
+
+  const score = Math.round(
+    contextScore * 0.2 +
+    planScore * 0.15 +
+    reviewScore * 0.15 +
+    refinementScore * 0.2 +
+    focusScore * 0.15 +
+    firstPromptScore * 0.15
+  );
+
+  return {
+    score: Math.max(0, Math.min(100, score)),
+    details: {
+      contextSetRatio: Math.round(contextRatio * 100),
+      planBeforeCodeRatio: Math.round(planRatio * 100),
+      reviewEndRatio: Math.round(reviewRatio * 100),
+      refinementRatio: Math.round(refinementRatio * 100),
+      avgFirstPromptLength: Math.round(avgFirstPromptLength),
+      durationDistribution: {
+        short: shortSessions,
+        medium: mediumSessions,
+        long: longSessions,
+        focused: focusedSessions,
+      },
+    },
+  };
+}

package/src/parsers/claude-code.js

@@ -0,0 +1,204 @@
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Parse Claude Code JSONL session files into normalized format.
+ *
+ * Each JSONL line is one of:
+ * - type: "user" → human prompt
+ * - type: "assistant" → AI response (may contain text, thinking, tool_use)
+ * - type: "summary" → session summary (skip)
+ * - type: "file-history-snapshot" → file state (skip)
+ *
+ * We normalize into sessions, each with turns.
+ */
+
+function parseJsonlLine(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+function extractToolCalls(content) {
+  if (!Array.isArray(content)) return [];
+  return content
+    .filter(block => block.type === 'tool_use')
+    .map(block => ({
+      tool: block.name || block.input?.description || 'unknown',
+      input: block.input || {},
+    }));
+}
+
+function extractTextContent(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter(block => block.type === 'text')
+    .map(block => block.text || '')
+    .join('\n');
+}
+
+function extractThinking(content) {
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter(block => block.type === 'thinking')
+    .map(block => block.thinking || '')
+    .join('\n');
+}
+
+function hasToolResults(content) {
+  if (!Array.isArray(content)) return false;
+  return content.some(block => block.type === 'tool_result');
+}
+
+/**
+ * Parse a single JSONL file into a list of turns.
+ */
+function parseSessionFile(filePath) {
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf-8');
+  } catch {
+    return [];
+  }
+
+  const lines = raw.split('\n').filter(l => l.trim());
+  const turns = [];
+
+  for (const line of lines) {
+    const entry = parseJsonlLine(line);
+    if (!entry) continue;
+
+    // Skip non-message types
+    if (entry.type === 'summary' || entry.type === 'file-history-snapshot') continue;
+    if (!entry.message) continue;
+
+    const role = entry.message.role || entry.type;
+    if (role !== 'user' && role !== 'assistant') continue;
+
+    // Skip tool result messages (these are system-injected responses to tool calls)
+    if (role === 'user' && hasToolResults(entry.message.content)) continue;
+
+    const turn = {
+      role,
+      text: extractTextContent(entry.message.content),
+      thinking: role === 'assistant' ? extractThinking(entry.message.content) : '',
+      toolCalls: role === 'assistant' ? extractToolCalls(entry.message.content) : [],
+      timestamp: entry.timestamp || null,
+      uuid: entry.uuid || null,
+      parentUuid: entry.parentUuid || null,
+      model: entry.message.model || null,
+    };
+
+    // Skip empty assistant messages that are just tool call continuations
+    if (role === 'assistant' && !turn.text && turn.toolCalls.length === 0 && !turn.thinking) {
+      continue;
+    }
+
+    turns.push(turn);
+  }
+
+  return turns;
+}
+
+/**
+ * Group consecutive turns into logical conversation exchanges.
+ * A "exchange" is one user prompt followed by all assistant responses until the next user prompt.
+ */
+function groupIntoExchanges(turns) {
+  const exchanges = [];
+  let current = null;
+
+  for (const turn of turns) {
+    if (turn.role === 'user') {
+      if (current) exchanges.push(current);
+      current = {
+        userPrompt: turn.text,
+        userTimestamp: turn.timestamp,
+        assistantResponses: [],
+        toolCalls: [],
+        thinkingContent: [],
+      };
+    } else if (turn.role === 'assistant' && current) {
+      if (turn.text) current.assistantResponses.push(turn.text);
+      if (turn.thinking) current.thinkingContent.push(turn.thinking);
+      current.toolCalls.push(...turn.toolCalls);
+    }
+  }
+
+  if (current) exchanges.push(current);
+  return exchanges;
+}
+
+/**
+ * Parse all Claude Code sessions from a project directory.
+ */
+export function parseProject(projectPath) {
+  const files = readdirSync(projectPath).filter(f =>
+    f.endsWith('.jsonl') && !f.startsWith('agent-')
+  );
+
+  const sessions = [];
+
+  for (const file of files) {
+    const filePath = join(projectPath, file);
+    const stat = statSync(filePath);
+
+    const turns = parseSessionFile(filePath);
+    if (turns.length === 0) continue;
+
+    const exchanges = groupIntoExchanges(turns);
+    if (exchanges.length === 0) continue;
+
+    // Get time range
+    const timestamps = turns
+      .map(t => t.timestamp)
+      .filter(Boolean)
+      .map(t => new Date(t).getTime())
+      .sort();
+
+    sessions.push({
+      id: file.replace('.jsonl', ''),
+      file,
+      exchanges,
+      turnCount: turns.length,
+      exchangeCount: exchanges.length,
+      startTime: timestamps[0] ? new Date(timestamps[0]).toISOString() : null,
+      endTime: timestamps[timestamps.length - 1] ? new Date(timestamps[timestamps.length - 1]).toISOString() : null,
+      durationMinutes: timestamps.length >= 2
+        ? Math.round((timestamps[timestamps.length - 1] - timestamps[0]) / 60000)
+        : 0,
+    });
+  }
+
+  return sessions;
+}
+
+/**
+ * Parse all Claude Code projects.
+ */
+export function parseAllProjects(basePath) {
+  const projects = readdirSync(basePath).filter(f => {
+    try {
+      return statSync(join(basePath, f)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+
+  const allSessions = [];
+
+  for (const project of projects) {
+    const projectPath = join(basePath, project);
+    const sessions = parseProject(projectPath);
+
+    for (const session of sessions) {
+      session.project = project.replace(/-/g, '/').replace(/^\//, '');
+      allSessions.push(session);
+    }
+  }
+
+  return allSessions;
+}

package/src/scorer.js

@@ -0,0 +1,109 @@
+/**
+ * Combine individual metric scores into composite scores and assign archetype.
+ */
+
+const ARCHETYPES = [
+  {
+    id: 'THE_ARCHITECT',
+    name: 'THE ARCHITECT',
+    // High decomposition + high planning + high leverage
+    match: (s) => s.decomposition >= 70 && s.sessionStructure >= 65 && s.aiLeverage >= 65,
+    priority: 1,
+  },
+  {
+    id: 'THE_SURGEON',
+    name: 'THE SURGEON',
+    // High debug efficiency + high leverage + good structure
+    match: (s) => s.debugCycles >= 75 && s.aiLeverage >= 60,
+    priority: 2,
+  },
+  {
+    id: 'THE_BUILDER',
+    name: 'THE BUILDER',
+    // High overall scores, well-rounded
+    match: (s) => {
+      const avg = (s.decomposition + s.debugCycles + s.aiLeverage + s.sessionStructure) / 4;
+      return avg >= 65 && Math.min(s.decomposition, s.debugCycles, s.aiLeverage, s.sessionStructure) >= 55;
+    },
+    priority: 3,
+  },
+  {
+    id: 'THE_EXPLORER',
+    name: 'THE EXPLORER',
+    // High leverage + high decomposition, loves research
+    match: (s) => s.aiLeverage >= 70 && s.decomposition >= 60,
+    priority: 4,
+  },
+  {
+    id: 'THE_SPEEDRUNNER',
+    name: 'THE SPEEDRUNNER',
+    // Quick debug cycles, less structured but efficient
+    match: (s) => s.debugCycles >= 70 && s.sessionStructure < 60,
+    priority: 5,
+  },
+  {
+    id: 'THE_APPRENTICE',
+    name: 'THE APPRENTICE',
+    // Learning patterns - lower scores but shows growth potential
+    match: (s) => {
+      const avg = (s.decomposition + s.debugCycles + s.aiLeverage + s.sessionStructure) / 4;
+      return avg >= 40 && avg < 65;
+    },
+    priority: 6,
+  },
+  {
+    id: 'THE_MAVERICK',
+    name: 'THE MAVERICK',
+    // Unstructured but somehow gets things done - low structure, decent other scores
+    match: (s) => s.sessionStructure < 50 && (s.decomposition >= 55 || s.aiLeverage >= 55),
+    priority: 7,
+  },
+  {
+    id: 'THE_NEWCOMER',
+    name: 'THE NEWCOMER',
+    // Default fallback
+    match: () => true,
+    priority: 99,
+  },
+];
+
+const TIERS = [
+  { name: 'LEGENDARY', min: 90 },
+  { name: 'RARE', min: 75 },
+  { name: 'UNCOMMON', min: 55 },
+  { name: 'COMMON', min: 0 },
+];
+
+export function computeOverallScore(metrics) {
+  const scores = {
+    decomposition: metrics.decomposition.score,
+    debugCycles: metrics.debugCycles.score,
+    aiLeverage: metrics.aiLeverage.score,
+    sessionStructure: metrics.sessionStructure.score,
+  };
+
+  // Weighted average
+  const overall = Math.round(
+    scores.decomposition * 0.25 +
+    scores.debugCycles * 0.25 +
+    scores.aiLeverage * 0.3 +
+    scores.sessionStructure * 0.2
+  );
+
+  // Assign archetype
+  const sortedArchetypes = [...ARCHETYPES].sort((a, b) => a.priority - b.priority);
+  const archetype = sortedArchetypes.find(a => a.match(scores)) || ARCHETYPES[ARCHETYPES.length - 1];
+
+  // Assign tier
+  const tier = TIERS.find(t => overall >= t.min) || TIERS[TIERS.length - 1];
+
+  return {
+    overall,
+    scores,
+    archetype: {
+      id: archetype.id,
+      name: archetype.name,
+    },
+    tier: tier.name,
+  };
+}

package/src/upload.js

@@ -0,0 +1,100 @@
+import { createInterface } from 'readline';
+
+const API_BASE = 'https://chekk-production.up.railway.app/api/v1';
+
+/**
+ * Call the Chekk API to generate personalized prose from metrics.
+ */
+export async function generateProse(metrics, result, sessionStats) {
+  const payload = {
+    metrics: {
+      decomposition: {
+        score: metrics.decomposition.score,
+        details: metrics.decomposition.details,
+      },
+      debugCycles: {
+        score: metrics.debugCycles.score,
+        details: metrics.debugCycles.details,
+      },
+      aiLeverage: {
+        score: metrics.aiLeverage.score,
+        details: metrics.aiLeverage.details,
+      },
+      sessionStructure: {
+        score: metrics.sessionStructure.score,
+        details: metrics.sessionStructure.details,
+      },
+    },
+    result: {
+      overall: result.overall,
+      scores: result.scores,
+      archetype: result.archetype,
+      tier: result.tier,
+    },
+    sessionStats,
+  };
+
+  const response = await fetch(`${API_BASE}/public/cli/analyze`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error(`API returned ${response.status}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Ask user if they want to claim their profile.
+ */
+export function askClaim() {
+  return new Promise((resolve) => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question('   Push your score to chekk.dev? Your raw prompts never leave your machine. (y/n) ', (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase().startsWith('y'));
+    });
+  });
+}
+
+/**
+ * Upload score and get a claim URL.
+ */
+export async function uploadAndClaim(metrics, result, sessionStats, prose) {
+  const payload = {
+    metrics: {
+      decomposition: metrics.decomposition.score,
+      debugCycles: metrics.debugCycles.score,
+      aiLeverage: metrics.aiLeverage.score,
+      sessionStructure: metrics.sessionStructure.score,
+    },
+    result: {
+      overall: result.overall,
+      archetype: result.archetype,
+      tier: result.tier,
+    },
+    prose,
+    sessionStats,
+    tools: sessionStats.tools,
+    claimedAt: new Date().toISOString(),
+  };
+
+  const response = await fetch(`${API_BASE}/public/cli/claim`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Claim API returned ${response.status}`);
+  }
+
+  return response.json();
+}