AI Usage Dash

Dashboard der KI-Nutzungsmetriken bei der Arbeit, fokussiert auf exakte (abgerechnete) Tokens, automatisch während der Sitzung über Hooks erfasst — du führst keinen Collector aus, und es gibt keinen Server, den du am Laufen halten musst.

Drei unabhängige Ebenen:

1. Erfassung (über Hooks) — End-of-Turn-Hooks schreiben die exakte Nutzung direkt in die lokale SQLite-Datei (lib/db.mjs). Kein Daemon, kein HTTP.

2. Speicherung — eine einzige SQLite-Datei (metrics.db) über das in Node eingebaute node:sqlite (keine native Abhängigkeit, kein Build-Schritt). WAL + busy_timeout ermöglichen es, dass parallele Hook-Schreiber und der MCP-Leser sie sicher gemeinsam nutzen.

3. Abfrage/Analyse — ein schreibgeschützter MCP-Server (stdio, bei Bedarf vom Client gestartet), den Claude und Cursor nutzen, um (Artefakte / Canvas) zu erzeugen.

Der Ereignisvertrag (src/types.ts) verbindet die drei Ebenen miteinander. Tokens sind First-Class-Felder.

Wie die exakten Tokens automatisch ankommen

Läuft 100 % lokal auf deinem Rechner — die Hooks sind kurzlebige node-Prozesse, die die SQLite-Datei öffnen, die Ereignisse des Turns schreiben und sich beenden. Es lauscht nichts auf einem Port.

⚠️ Warum Cursor einen API-Key braucht. Die abgerechnete Token-Anzahl von Cursor existiert nicht auf dem Rechner: Der Cursor-Hook erhält keine Tokens, und die lokale Datenbank hat nur Kontext Schätzungen. Die exakte Zahl existiert nur serverseitig (Admin API, Team/Business-Plan). Der Hook automatisiert diesen Abruf — du musst weiterhin nichts ausführen — aber ohne den Admin-Key kannst du nur Aktivität sehen, nicht die Tokens.

Einrichtung

npm install                 # no native build — uses Node's built-in SQLite
npm link                    # puts the ai-usage-* commands on your PATH
cp .env.example .env

npm link macht jedes Tool als Befehl verfügbar, den du namentlich aufrufen kannst (ai-usage-claude-hook, ai-usage-cursor-hook, ai-usage-mcp, ai-usage-stats, …), sodass nichts unten einen absoluten Pfad zu diesem Repo hartkodiert. Jeder Befehl löst seinen eigenen Speicherort auf, sodass er aus jedem Verzeichnis funktioniert. (Willst du nicht global linken? Führe sie aus dem Repo mit npx ai-usage-<name> aus oder verwende alternativ node ./hooks/<file>.mjs mit einem Pfad.)

Es gibt keinen Dienst, den du starten musst. Die Hooks schreiben direkt in die DB, und der MCP-Server wird bei Bedarf von deinem Client gestartet. Die DB liegt standardmäßig als metrics.db im Repo-Root; setze IA_USAGE_DASHBOARD_DB_PATH nur, wenn du sie woanders aufbewahrst:

• export IA_USAGE_DASHBOARD_DB_PATH="$HOME/somewhere/metrics.db"   # optional; the commands find the repo DB by default

1. Claude-Code-Hook aktivieren

Registriere den Hook in ~/.claude/settings.json:

• {
    "hooks": {
      "Stop": [
        { "hooks": [{ "type": "command", "command": "ai-usage-claude-hook" }] }
      ],
      "SubagentStop": [
        { "hooks": [{ "type": "command", "command": "ai-usage-claude-hook" }] }
      ]
    }
  }

Erledigt — ab sofort schreibt jeder Claude-Code-Turn die exakte Nutzung automatisch. Der Hook ist unauffällig und blockiert Claude Code niemals; falls ein Schreibvorgang je fehlschlägt, wiederholt er ihn einfach im nächsten Turn.

2. Cursor-Hook aktivieren

Erstelle ~/.cursor/hooks.json (oder <project>/.cursor/hooks.json) — siehe das Beispiel unter hooks/cursor-hooks.example.json:

• { "version": 1, "hooks": { "stop": [{ "command": "ai-usage-cursor-hook" }] } }

Für die exakten Tokens von Cursor exportiere außerdem den Admin-Key (Cursor Dashboard → settings → Cursor Admin API Keys):

• export CURSOR_API_KEY=<cursor-admin-key>

3. Den schreibgeschützten MCP registrieren (Claude / Cursor)

• claude mcp add ai-usage -- ai-usage-mcp

Für Cursor bringt das Repo bereits .cursor/mcp.json mit (führtnpm run mcp aus dem Repo aus — kein Pfad nötig).

Im Client: „Nutze das token_usage-Tool (period 30d, group_by model) und erstelle ein Balkendiagramm“ → Artefakt/Canvas.

Abfragetools (MCP)

Pro Ereignis erfasste Metriken

• message (Claude Code und Cursor): exakte Tokens, model, und in meta: stop_reason, latency_ms (Turn-Zeit), n_tools, tools, web_search/web_fetch, gitBranch.

• tool_use: eines pro Werkzeugaufruf (speist top_tools/tool_stats).

• error: eines pro tool_result mit Fehler (Nenner = tool_use → Fehlerrate).

• productivity (Cursor, täglich): hinzugefügte/angenommene Zeilen, angezeigte/angenommene Tabs, Übernahmen.

Task-(Jira/Issue)-Verknüpfung pro Session

Jede KI-Sitzung ist mit einem Task verknüpft, um den KI-Aufwand pro Issue zu messen. Die Auflösung erfolgt automatisch zu Beginn der Sitzung, in der Reihenfolge der Präzision:

1. .dash-task — Datei im Repo-Wurzelverzeichnis mit der ID (explizite Übersteuerung).

2. Git-Branch — eine Jira-artige ID im Branch-Namen (feature/PROJ-123-... → PROJ-123).

3. UserPrompt — eine erwähnte ID oder der explizite Marker #task PROJ-123 (jederzeit korrigierbar).

4. Wenn keines der oben genau auflöst → der SessionStart-Hook injiziert Kontext, der Claude anweist, den User vor dem Start nach der ID zu fragen (Best-Effort — ein SessionStart-Hook kann nicht blockieren, also kann das Modell die Frage überspringen). Unabhängig davon, ob er fragt, wird die Antwort vom UserPromptSubmit-Hook eigenständig erfasst; die garantierten Wege, den Task zu setzen, sind also .dash-task, der Branchname oder #task PROJ-123.

Beteiligte Hooks (registriert in ~/.claude/settings.json):

• "SessionStart":    [{ "hooks": [{ "type": "command", "command": "ai-usage-session-task" }] }],
  "UserPromptSubmit":[{ "hooks": [{ "type": "command", "command": "ai-usage-task-capture" }] }]

Das ID-Muster ist über DASH_TASK_PATTERN (Regex) konfigurierbar. Der Standard ist Jira-artig (PROJ-123). task_id wird bei jedem Ereignis zu einem First-Class-Feld; frage ihn mit by_task oder token_usage group_by=task_id ab.

Slash-Command /dash_stats

Frag die Statistiken eines Tasks direkt von Claude Code aus ab:

• /dash_stats DEMO-100   → stats for the given task
  /dash_stats            → uses the ACTIVE task of the current session

Gibt Tokens (in/out/cache), Nachrichten, Tool-Aufrufe + Fehlerrate, p50/p95-Latenz, Aufschlüsselung pro Modell und Top-Tools zurück — das alles für dieses Issue.

Bestandteile: der ai-usage-stats-Befehl (scripts/task-stats.mjs — löst den Task auf und liest die lokale SQLite-Datenbank direkt über taskStats() in lib/db.mjs) plus der Befehl in ~/.claude/commands/dash_stats.md. Führe ihn als ai-usage-stats DEMO-100 aus (oder npm run stats -- DEMO-100 aus dem Repo). Richte ihn mit IA_USAGE_DASHBOARD_DB_PATH auf eine nicht standardmäßige Datenbank. Der aktive Task ist der letzte Task-Status der Sitzung.

Historie-Backfill (optional, läuft einmalig)

Die Hooks erfassen ab jetzt. Um die komplette bisherige Historie einmalig zu importieren:

• npm run collect:claude                       # scans ~/.claude/projects/**.jsonl
  CURSOR_API_KEY=<key> npm run collect:cursor

Beide sind idempotent (Deduplikation über ext_id) — eine erneute Ausführung erzeugt keine Duplikate.

Nächste Schritte

• Kosten von Claude Code (Tokens × Preistabelle pro Modell).

• Feste Dashboards (HTML) über die On-Demand-Artefakte hinaus.

• Migration: SQLite → Postgres (nur lib/db.mjs austauschen).

• Multi-Maschinen-Erfassung — falls die DB je außerhalb der Maschine liegen muss, einen dünnen Ingest-Endpoint vor insertEvents() wieder einführen (heute läuft sie als Einzelnutzer auf dem Rechner, direkt in die Datei).