Skip to content
AI CraftsmanSUPERPOWERS

Metrics & Analytics

SQLite-backed quality metrics: violations, corrections, session history, and 7-day trends.

Last updated: Edit on GitHub

Overview

AI Craftsman Superpowers tracks quality data across sessions using a local SQLite database at ~/.claude/craftsman-metrics.db. The correction learning system records violations, when Claude corrects them, and session summaries.

Privacy first

All metrics are stored locally. Nothing is sent to external servers. File paths are stored as-is but only used for trend analysis: no code content is stored.

Viewing Metrics

/craftsman:metrics

Sample output:

╔══════════════════════════════════════════════════════╗
║        AI Craftsman Quality Dashboard                ║
╠══════════════════════════════════════════════════════╣
║  Sessions this week: 12    Violations: 47            ║
║  Corrections: 31           Correction rate: 66%      ║
╠══════════════════════════════════════════════════════╣
║  7-Day Trend                                         ║
║  Mon ████████████  18 violations                     ║
║  Tue ██████████    15 violations                     ║
║  Wed ████████      12 violations  ↓ -20%             ║
║  Thu ██████        9 violations                      ║
║  Fri ████          6 violations                      ║
╠══════════════════════════════════════════════════════╣
║  Top Rules Triggered                                 ║
║  PHP001 (final_classes)      18 times                ║
║  TS001 (no_any)              12 times                ║
║  PHP004 (strict_types)        8 times                ║
║  PHP002 (private_constructor) 6 times                ║
╠══════════════════════════════════════════════════════╣
║  Recent Sessions                                     ║
║  2026-03-29 14:32  8 violations, 6 corrected         ║
║  2026-03-29 10:15  5 violations, 4 corrected         ║
║  2026-03-28 16:45  12 violations, 9 corrected        ║
╚══════════════════════════════════════════════════════╝

Database Schema

-- Sessions table
CREATE TABLE sessions (
    id          TEXT PRIMARY KEY,    -- Session UUID
    started_at  INTEGER NOT NULL,    -- Unix timestamp
    ended_at    INTEGER,             -- NULL if still active
    pack        TEXT,                -- Active pack name
    violations  INTEGER DEFAULT 0,
    corrections INTEGER DEFAULT 0
);

-- Violations table
CREATE TABLE violations (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id  TEXT NOT NULL,
    timestamp   INTEGER NOT NULL,
    rule_id     TEXT NOT NULL,       -- e.g., "PHP001"
    severity    TEXT NOT NULL,       -- "block" | "warn"
    file_path   TEXT NOT NULL,
    line_number INTEGER,
    corrected   INTEGER DEFAULT 0,   -- 1 if Claude corrected it
    FOREIGN KEY (session_id) REFERENCES sessions(id)
);

-- Corrections table (correction learning)
CREATE TABLE corrections (
    id            INTEGER PRIMARY KEY AUTOINCREMENT,
    violation_id  INTEGER NOT NULL,
    session_id    TEXT NOT NULL,
    corrected_at  INTEGER NOT NULL,
    rule_id       TEXT NOT NULL,
    FOREIGN KEY (violation_id) REFERENCES violations(id)
);

SQL Queries (Direct Access)

You can query the database directly with SQLite:

# Open the database
sqlite3 ~/.claude/craftsman-metrics.db

# Violations in the last 7 days
SELECT rule_id, COUNT(*) as count
FROM violations
WHERE timestamp > strftime('%s', 'now', '-7 days')
GROUP BY rule_id
ORDER BY count DESC;

# Correction rate by rule
SELECT
  rule_id,
  COUNT(*) as total,
  SUM(corrected) as corrected,
  ROUND(100.0 * SUM(corrected) / COUNT(*), 1) as rate
FROM violations
WHERE timestamp > strftime('%s', 'now', '-30 days')
GROUP BY rule_id
ORDER BY rate ASC;  -- Lowest correction rate first (hardest rules)

# Session summary for today
SELECT
  id,
  datetime(started_at, 'unixepoch', 'localtime') as started,
  violations,
  corrections
FROM sessions
WHERE date(started_at, 'unixepoch', 'localtime') = date('now', 'localtime')
ORDER BY started_at DESC;

Parameterized queries

The metrics-query.py helper ensures all database writes use parameterized queries (preventing SQL injection from file paths). Never write raw shell string interpolation to the database.

Correction Learning System

The correction learning system tracks when Claude successfully fixes a violation it created. This data powers the 30-day trend analysis:

  1. Violation recorded: Claude writes code that triggers PHP001
  2. Correction recorded: Claude rewrites the code to be final
  3. Trend tracked: Over time, the correction rate for PHP001 increases
  4. Learning validated: High correction rate = Claude is learning this rule
# Check correction rate trend (lower violation count = improvement)
/craftsman:metrics --trend 30

Resetting Metrics

# Reset all metrics (irreversible)
rm ~/.claude/craftsman-metrics.db

# Reset only current week
sqlite3 ~/.claude/craftsman-metrics.db \
  "DELETE FROM violations WHERE timestamp > strftime('%s', 'now', '-7 days')"

Metrics in CI

CI runs also record metrics, but to a separate file to avoid polluting local data:

# CI metrics location
~/.claude/craftsman-metrics-ci.db

# Or set custom path
CRAFTSMAN_METRICS_DB=/tmp/ci-metrics.db bash ci/craftsman-ci.sh