stats
Show validation run statistics and rule violation trends.
Overview
The stats command displays a history of validation runs stored in the statistics directory, along with a breakdown of the most frequently violated rules. It can also export the full history as JSON or clear all stored data.
Statistics are recorded automatically by karandash validate when persistence is enabled in configuration.
Synopsis
karandash stats [--limit <n>] [--rule <id>] [--json] [--clear] [--stats-dir <dir>]
karandash stats --diagnostics <path>... [--format text|markdown]
karandash stats --audit --corpus <dir> [--bot <name>]... [--cutoff <date>] [--holdout-project <p>] [--seed <n>] [--llm-judge [--llm-judge-max-calls <n>]] [--out <file>]
Options
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--limit |
-n |
Int |
20 |
Number of recent runs to display |
--rule |
-r |
String |
-- | Filter to a specific rule ID |
--json |
-- | flag | false |
Export full statistics history as JSON |
--clear |
-- | flag | false |
Delete all stored statistics |
--diagnostics |
-- | String (repeatable) |
-- | Weekly digest over diagnostic.json files instead of local statistics: a file, a directory (walked for *.json) or dir/pattern*.json |
--format |
-- | text, markdown |
text |
Output of --diagnostics |
--stats-dir |
-- | String |
ai.statistics.dir, else .karandash/stats |
Directory where statistics are stored. Relative to the current working directory, not your home directory - each project keeps its own history. |
--audit |
-- | flag | false |
Audit a frozen review-history corpus (tools/audit/fetch_gitlab_corpus.py) instead of local statistics |
--corpus |
-- | String |
-- | --audit: corpus directory (<dir>/<project>/<iid>.json) |
--out |
-- | String |
stdout | --audit: write the JSON report here instead of stdout |
--cutoff |
-- | YYYY-MM-DD |
-- | --audit: MRs created before this date tune, the rest test |
--holdout-project |
-- | String |
-- | --audit: project kept out of the tune and test splits (full path or one path segment) |
--bot |
-- | String (repeatable) |
-- | --audit: bot username |
--seed |
-- | Int |
0 |
--audit: bootstrap seed |
--llm-judge |
-- | flag | false |
--audit: ask the configured AI provider about replies the keyword classifier leaves unknown |
--llm-judge-max-calls |
-- | Int (>= 1) |
500 |
--audit --llm-judge: model call cap |
Usage Examples
# Show the last 20 runs as a table
karandash stats
# Show the last 50 runs
karandash stats --limit 50
# Filter by rule
karandash stats --rule title-format
# Export full history as JSON
karandash stats --json > history.json
# Clear all statistics
karandash stats --clear
# Use a non-default stats directory
karandash stats --stats-dir /var/karandash/stats
Output
Run History (20 shown):
# Timestamp MR ID Total Errors Warnings Info
----------------------------------------------------------------------
1 2026-03-15 14:22 mr-42 3 1 2 0
2 2026-03-14 09:11 mr-41 0 0 0 0
...
Top violations by rule:
title-format 12 finding(s) across 8 run(s)
commit-messages 7 finding(s) across 5 run(s)
size-limits 4 finding(s) across 3 run(s)
See Also
- calibrate - get threshold adjustment recommendations from statistics
- test-rule - replay a rule against the stored history
Weekly digest
--diagnostics reads the diagnostic.json files that validate --diagnostic <path> writes and prints one table:
| Metric | Read from |
|---|---|
| Red runs | summary.finding_summary.passed |
| AI availability | runs with an AI rule (rules[].model, cost_usd or an AI_* skip category) that have no AI rule in error or skipped as AI_PROVIDER_ERROR / AI_RATE_LIMITED |
| Fix rate / persistence | merge requests (context.mr_url, else mr_iid) with two or more runs: findings of the first run gone by the last (findings[]); files from releases without findings are left out |
| Dead rules | rules configured or run (context.rule_ids, rules[]) that never produced a finding |
| AI cost per MR | sum of rules[].cost_usd over merge requests with an AI rule |
| Cache hit | summary.cache hits over hits plus misses; rules from cache from rules[].from_cache |
| Duration | p50 and p95 of summary.total_duration_ms |
| False positives | optional feedback.falsePositives |
A file that is not a diagnostic report is skipped with a warning on stderr.
tools/digest/collect-diagnostics.sh downloads the diagnostics/diagnostic.json artifacts of the changes-validation jobs of the last N days through glab api (read-only) and runs the digest:
tools/digest/collect-diagnostics.sh -p group/app-android -p group/app-ios -d 7 -f markdown