ai-usage-mcp

{"type": "text"}# Panel de uso de IA

Panel de métricas de uso de IA en el trabajo, centrado en tokens exactos (facturados), recopilados automáticamente mediante hooks durante la sesión — no ejecutas ningún recopilador, y no hay ningún servidor que mantener en funcionamiento.

Tres capas independientes:

1. Recopilación (mediante hooks) — los hooks de fin de turno escriben el uso exacto directamente en el archivo SQLite local (lib/db.mjs). Sin demonio, sin HTTP.

2. Almacenamiento — un único archivo SQLite (metrics.db) mediante el node:sqlite integrado de Node (sin dependencia nativa, sin paso de compilación). WAL + busy_timeout permiten que los escritores de hooks concurrentes y el lector MCP lo compartan de forma segura.

3. Consulta/análisis — un servidor MCP de solo lectura (stdio, iniciado bajo demanda por el cliente) que Claude y Cursor consumen para generar gráficos (artefactos / lienzo).

El contrato de eventos (src/types.ts) une las tres capas. Los tokens son campos de primera clase.

Cómo llega el token exacto, automáticamente

Se ejecuta 100% local en tu máquina — los hooks son procesos node de corta duración que abren el archivo SQLite, escriben los eventos del turno y salen. Nada escucha en un puerto.

⚠️ Por qué Cursor necesita una clave de API. El recuento de tokens facturados de Cursor no existe en la máquina: el hook de Cursor no recibe tokens, y la base de datos local solo tiene estimaciones de contexto. El número exacto solo existe en el lado del servidor (API de administración, plan Team/Business). El hook automatiza esa obtención — tú no ejecutas nada — pero sin la clave de administrador solo puedes ver actividad, no los tokens.

Configuración

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 expone cada herramienta como un comando que puedes invocar por nombre (ai-usage-claude-hook, ai-usage-cursor-hook, ai-usage-mcp, ai-usage-stats, …), por lo que nada a continuación codifica una ruta absoluta a este repositorio. Cada comando resuelve su propia ubicación, por lo que funciona desde cualquier directorio. (¿Prefieres no enlazarlo globalmente? Ejecútalos desde el repositorio con npx ai-usage-<nombre>, o recurre a node ./hooks/<archivo>.mjs con una ruta.)

No hay ningún servicio que iniciar. Los hooks escriben directamente en la base de datos y el servidor MCP se inicia bajo demanda por tu cliente. La base de datos por defecto es metrics.db en la raíz del repositorio; establece IA_USAGE_DASHBOARD_DB_PATH solo si la mantienes en otro lugar:

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

1. Habilitar el hook de Claude Code

Registra el hook en ~/.claude/settings.json:

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

Listo — a partir de entonces, cada turno de Claude Code escribe el uso exacto por sí mismo. El hook es silencioso y nunca bloquea a Claude Code; si una escritura falla, simplemente reintenta en el siguiente turno.

2. Habilitar el hook de Cursor

Crea ~/.cursor/hooks.json (o <proyecto>/.cursor/hooks.json) — consulta el ejemplo en hooks/cursor-hooks.example.json:

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

Para los tokens exactos de Cursor, exporta también la clave de administrador (Panel de Cursor → Configuración → Claves de API de administración de Cursor):

export CURSOR_API_KEY=<cursor-admin-key>

3. Registrar el MCP de solo lectura (Claude / Cursor)

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

Para Cursor, el repositorio ya incluye .cursor/mcp.json (ejecuta npm run mcp desde el repositorio — sin necesidad de ruta).

En el cliente: "usa la herramienta token_usage (período 30d, agrupar por modelo) y haz un gráfico de barras" → artefacto/lienzo.

Herramientas de consulta (MCP)

Métricas capturadas por evento

• message (Claude Code y Cursor): tokens exactos, model, y en meta: stop_reason, latency_ms (tiempo de turno), n_tools, tools, web_search/web_fetch, gitBranch.

• tool_use: uno por herramienta llamada (alimenta top_tools/tool_stats).

• error: uno por tool_result con error (denominador = tool_use → tasa de errores).

• productivity (Cursor, diario): líneas añadidas/aceptadas, pestañas mostradas/aceptadas, aplicaciones.

Enlace de tarea (Jira/incidencia) por sesión

Cada sesión de IA está vinculada a una tarea, para medir el esfuerzo de IA por incidencia. La resolución ocurre automáticamente al inicio de la sesión, en orden de precisión:

1. .dash-task — archivo en la raíz del repositorio con el ID (anulación explícita).

2. Rama de Git — un ID estilo Jira en el nombre de la rama (feature/PROJ-123-... → PROJ-123).

3. Mensaje del usuario — un ID mencionado, o el marcador explícito #task PROJ-123 (puedes corregirlo en cualquier momento).

4. Si ninguno de los anteriores resuelve con precisión → el hook SessionStart inyecta contexto indicando a Claude que pregunte al usuario por el ID antes de comenzar (mejor esfuerzo — un hook SessionStart no puede bloquear, por lo que el modelo puede omitir la pregunta). Independientemente de si pregunta, la respuesta se captura por sí sola mediante el hook UserPromptSubmit, por lo que las formas garantizadas de establecer la tarea son .dash-task, el nombre de la rama o #task PROJ-123.

Hooks involucrados (registrados en ~/.claude/settings.json):

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

El patrón de ID es configurable mediante DASH_TASK_PATTERN (expresión regular). El valor predeterminado es estilo Jira (PROJ-123). task_id se convierte en un campo de primera clase en cada evento; consúltalo con by_task o token_usage group_by=task_id.

Comando de barra /dash_stats

Consulta las estadísticas de una tarea directamente desde Claude Code:

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

Devuelve tokens (entrada/salida/caché), mensajes, llamadas a herramientas + tasa de errores, latencia p50/p95, desglose por modelo y herramientas principales — todo para esa incidencia.

Componentes: el comando ai-usage-stats (scripts/task-stats.mjs — resuelve la tarea y lee la base de datos SQLite local directamente mediante taskStats() en lib/db.mjs) + el comando en ~/.claude/commands/dash_stats.md. Ejecútalo como ai-usage-stats DEMO-100 (o npm run stats -- DEMO-100 desde el repositorio). Apúntalo a una base de datos no predeterminada con IA_USAGE_DASHBOARD_DB_PATH. La tarea activa es el estado de tarea más reciente de la sesión.

Relleno de historial (opcional, se ejecuta una vez)

Los hooks capturan a partir de ahora. Para importar TODO el historial existente una sola vez:

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

Ambos son idempotentes (deduplicación por ext_id) — ejecutarlos de nuevo no duplica.

Próximos pasos

• Costo de Claude Code (tokens × tabla de precios por modelo).

• Paneles fijos (HTML) más allá de los artefactos bajo demanda.

• Migrar SQLite → Postgres (intercambiar solo lib/db.mjs).

• Recopilación multi-máquina — si la base de datos necesita vivir fuera del equipo, reintroducir un punto de ingesta ligero delante de insertEvents() (hoy se ejecuta para un solo usuario en la máquina, directamente a archivo).