AI Usage Dash

Панель метрик использования AI на работе, с фокусом на точные (оплачиваемые) токены, собираемые автоматически через хуки во время сессии — вам не нужно запускать никакой сборщик, и не нужно держать запущенным сервер.

Три независимых слоя:

1. Сбор (через хуки) — хуки конца хода записывают точное использование напрямую в локальный файл SQLite (lib/db.mjs). Никакого демона, никакого HTTP.

2. Хранение — один файл SQLite (metrics.db) через встроенный node:sqlite из Node (без нативных зависимостей, без шага сборки). WAL + busy_timeout позволяют конкурентным писателям-хукам и MCP-читателю безопасно работать с ним.

3. Запрос/анализ — read-only MCP-сервер (stdio, запускается по требованию клиентом), который потребляют Claude и Cursor для построения графиков (артефакты / canvas).

Контракт событий (src/types.ts) связывает три слоя вместе. Токены — поля первого класса.

Как точный токен появляется автоматически

Работает на 100% локально на вашей машине — хуки — это короткоживущие процессы node, которые открывают файл SQLite, записывают события хода и завершаются. Ничего не слушает порт.

⚠️ Почему Cursor нужен API-ключ. Оплачиваемое количество токенов Cursor не существует на машине: хук Cursor не получает токены, а в локальной БД есть только оценки контекста. Точное число существует только на стороне сервера (Admin API, тариф Team/Business). Хук автоматизирует этот запрос — вам по-прежнему ничего не нужно запускать — но без админ-ключа вы сможете видеть только активность, а не токены.

Установка

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 предоставляет каждый инструмент как команду, которую можно вызывать по имени (ai-usage-claude-hook, ai-usage-cursor-hook, ai-usage-mcp, ai-usage-stats, …), поэтому нигде ниже не захардкожен абсолютный путь к этому репозиторию. Каждая команда сама определяет своё расположение, поэтому работает из любой директории. (Не хотите глобальную ссылку? Запускайте их из репозитория через npx ai-usage-<name>, или используйте node ./hooks/<file>.mjs с путём.)

Нет сервиса, который нужно запускать. Хуки пишут в БД напрямую, а MCP-сервер запускается по требованию вашим клиентом. БД по умолчанию находится в metrics.db в корне репозитория; установите IA_USAGE_DASHBOARD_DB_PATH, только если храните её в другом месте:

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

1. Включите хук Claude Code

Зарегистрируйте хук в ~/.claude/settings.json:

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

Готово — с этого момента каждый ход Claude Code сам записывает точное использование. Хук молчалив и никогда не блокирует Claude Code; если запись когда-либо не удастся, он просто повторит попытку в следующем ходе.

2. Включите хук Cursor

Создайте ~/.cursor/hooks.json (или <project>/.cursor/hooks.json) — см. пример в hooks/cursor-hooks.example.json:

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

Для точных токенов Cursor также экспортируйте админ-ключ (Cursor Dashboard → Settings → Cursor Admin API Keys):

export CURSOR_API_KEY=<cursor-admin-key>

3. Зарегистрируйте read-only MCP (Claude / Cursor)

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

Для Cursor в репозитории уже есть .cursor/mcp.json (запускает npm run mcp из репозитория — путь не нужен).

В клиенте: "используй инструмент token_usage (период 30д, group_by model) и построй столбчатую диаграмму" → артефакт/canvas.

Инструменты запросов (MCP)

Метрики, собираемые для каждого события

• message (Claude Code и Cursor): точные токены, model, и в meta: stop_reason, latency_ms (время хода), n_tools, tools, web_search/web_fetch, gitBranch.

• tool_use: по одному на каждый вызванный инструмент (питает top_tools/tool_stats).

• error: по одному на tool_result с ошибкой (знаменатель = tool_use → доля ошибок).

• productivity (Cursor, ежедневно): добавленные/принятые строки, показанные/принятые вкладки, применения.

Связь задачи (Jira/тикета) с сессией

Каждая AI-сессия связана с задачей, чтобы измерять AI-усилия по тикету. Определение происходит автоматически в начале сессии, в порядке точности:

1. .dash-task — файл в корне репозитория с ID (явное переопределение).

2. Git-ветка — ID в стиле Jira в имени ветки (feature/PROJ-123-... → PROJ-123).

3. Промпт пользователя — упомянутый ID или явный маркер #task PROJ-123 (можно исправить в любое время).

4. Если ни один из вышеперечисленных не даёт точного результата → хук SessionStart внедряет контекст, инструктирующий Claude спросить пользователя об ID перед началом (best-effort — хук SessionStart не может блокировать, поэтому модель может пропустить вопрос). Независимо от того, задаёт ли он вопрос, ответ перехватывается отдельно хуком UserPromptSubmit, поэтому гарантированные способы задать задачу — это .dash-task, имя ветки или #task PROJ-123.

Задействованные хуки (зарегистрированы в ~/.claude/settings.json):

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

Шаблон ID настраивается через DASH_TASK_PATTERN (регулярное выражение). По умолчанию — стиль Jira (PROJ-123). task_id становится полем первого класса для каждого события; запрашивайте его через by_task или token_usage group_by=task_id.

Слэш-команда /dash_stats

Запрос статистики задачи прямо из Claude Code:

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

Возвращает токены (вход/выход/кэш), сообщения, вызовы инструментов + долю ошибок, p50/p95 задержку, разбивку по моделям и топ инструментов — всё для этого тикета.

Компоненты: команда ai-usage-stats (scripts/task-stats.mjs — определяет задачу и читает локальную БД SQLite напрямую через taskStats() в lib/db.mjs) + команда в ~/.claude/commands/dash_stats.md. Запускайте как ai-usage-stats DEMO-100 (или npm run stats -- DEMO-100 из репозитория). Укажите нестандартную БД через IA_USAGE_DASHBOARD_DB_PATH. Активная задача — это самое последнее состояние задачи в сессии.

Обратное заполнение истории (опционально, запускается один раз)

Хуки собирают данные с этого момента. Чтобы импортировать ВСЮ существующую историю один раз:

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

Обе команды идемпотентны (дедупликация по ext_id) — повторный запуск не создаёт дубликатов.

Следующие шаги

• Стоимость Claude Code (токены × таблица цен по моделям).

• Фиксированные дашборды (HTML) помимо артефактов по запросу.

• Миграция SQLite → Postgres (заменить только lib/db.mjs).

• Сбор с нескольких машин — если БД когда-либо понадобится разместить вне машины, добавьте тонкий ingest-эндпоинт перед insertEvents() (сейчас он работает однопользовательски на машине, напрямую в файл).