ai-estimation-tracker

AI Estimation Tracker

Plugin pro Claude Code a Cursor. Měří jak přesně AI odhaduje čas implementace.

Zero dependencies. Jen Node.js. Funguje na Windows, macOS, Linux.

Instalace

Claude Code

# 1. Přidej marketplace
/plugin marketplace add DXHeroes/ai-estimation-tracker

# 2. Nainstaluj plugin
/plugin install estimation-tracker@ai-estimation-tracker@latest

Cursor

# Přes marketplace
/add-plugin z URL: github.com/DXHeroes/ai-estimation-tracker

# Nebo ručně — Cursor podporuje Claude Code hooks formát:
# Zkopíruj plugins/estimation-tracker/ do ~/.cursor/plugins/

Po instalaci restartuj Claude Code / Cursor.

Jak to funguje

1. Zadáš prompt
   └─▶ Hook uloží timestamp startu

2. AI vidí Skill → napíše <!-- ESTIMATE: 15m --> na první řádek (odhad lidského času)

3. AI vrátí odpověď
   └─▶ Hook:
       • spočítá skutečný čas (teď - start)
       • parsuje odhad z odpovědi
       • detekuje model a tool
       • pošle do OTEL collectoru
       • uloží lokálně do JSON + log

Proč Skill místo additionalContext?

additionalContext v hook return value funguje jen v Claude Code. Skill (SKILL.md) funguje v obou — agent si ho načte sám, když je relevantní. Instrukce "vždy odhadni čas" tak funguje univerzálně.

Co se trackuje

Atribut	Popis
ai.model	Model (claude-sonnet-4-..., gpt-4o, ...)
ai.tool	Nástroj (claude-code, cursor)
task.estimated_minutes	AI odhad lidského času (normalizovaný na minuty; AI může zadat m/h/d)
task.actual_minutes	Skutečný wall-clock čas v minutách
task.estimation_accuracy	Poměr estimate/actual (1.0 = perfektní)
task.loc_added / loc_removed	Řádky kódu (0 bez gitu)
task.prompt	Prvních 200 znaků promptu

Model se detekuje automaticky:

1. Z transkriptu (JSONL) — nejpřesnější
2. Z hook inputu
3. Z env vars (CLAUDE_MODEL, ANTHROPIC_MODEL)
4. Fallback: "unknown"

Monitoring stack (volitelně)

# Spusť OTEL Collector + Prometheus + Loki + Grafana
docker compose up -d

# Grafana: http://localhost:3000 (admin/admin)

Nastav OTEL endpoint v .claude/settings.json (sdílené pro celý tým):

// .claude/settings.json
{
  "env": {
    "AI_TRACKER_OTEL_ENDPOINT": "http://localhost:4318",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/json"
  }
}

Podporované protokoly (OTEL_EXPORTER_OTLP_PROTOCOL):

• http/json — výchozí, OTLP/HTTP na portu 4318
• grpc — OTLP/gRPC na portu 4317

Bez OTEL collectoru hook tiše selže — data se ukládají lokálně vždy.

CLI statistiky

node stats.js        # posledních 30 dní
node stats.js 7      # posledních 7 dní

═══════════════════════════════════════════════
  AI Estimation Accuracy Report (last 30 days)
═══════════════════════════════════════════════

  Tasks tracked:        42
  Tasks completed:      38
  With AI estimates:    35

  ┌─────────────────────────────────────────┐
  │ Avg AI Estimate:     8.3m
  │ Avg Actual Time:     12.1m
  │ Accuracy Ratio:      0.69x  (1.0 = perfect)
  │ Total LOC Changed:   2847
  ├─────────────────────────────────────────┤
  │ Underestimates:      24  (AI too optimistic)
  │ Overestimates:       6   (AI too pessimistic)
  │ Accurate (±10%):     5
  └─────────────────────────────────────────┘

  Per-model breakdown:
  ─────────────────────────────────────────────────────────────────────
  Model                              Tasks  Avg Est  Avg Actual  Accuracy
  ─────────────────────────────────────────────────────────────────────
  claude-sonnet-4-20250514              18     6.2m       9.8m      0.63x
  claude-opus-4-20250603                12    11.5m      14.2m      0.81x
  gpt-4o                                5     7.8m      13.1m      0.60x

Struktura repa