Observabilidad de agentes de código, Claude Code primero
Un hook en tu máquina envía cada Evento a un backend Node.js con SQLite, que lo muestra en vivo en un dashboard Angular por WebSocket. Todo corre en local: sin cuenta, sin nube y con control preventivo de costes.
docker compose up
Seis Pilares de Observabilidad para Claude Code
Sin proxy intermedio lento, sin riesgo de fugas de propiedad intelectual y sin facturas sorpresa de telemetría.
Ingesta Normalizada & WebSocket en Vivo
El hook send_event.mjs envía cada Evento por HTTP POST al backend Node.js, que lo guarda en SQLite y lo empuja al dashboard por WebSocket. Esquema de Evento normalizado, pensado para sumar otros Harness.
Observador de Agentes & Subagentes
Comparativa por Tipo de Subagente (Lanzamientos, duración, coste y errores), perfil de cada Tipo y detalle de cada Lanzamiento con su Estado, su tarea y su respuesta.
Eficiencia de Caché de Prompts & Desglose
Cálculo de tasa de acierto de caché, ahorro neto en dólares, sobrecoste de escritura y diagnóstico de reescrituras (caducadas, cambio entre Sonnet y Opus).
Presupuestos & Control de Parada
Límites de Coste estimado por Sesión, por Proyecto y día o globales del día, con aviso en la cabecera y, si lo eliges, parada del agente desde el hook (continue: false). Las Reglas de bloqueo frenan en local rm peligrosos, push --force a main y ficheros sensibles.
Enmascarado de Secretos, PII & Inyecciones
El hook enmascara secretos (claves de API, tokens) y datos personales (email, teléfono, IBAN, tarjeta, documento de identidad) antes de enviar, con marcadores tipados [REDACTED_*]. Avisa además cuando un contenido leído parece dar órdenes al agente (inyección).
Exportación OTLP OpenInference & Tests
Exportación opt-in de cada Turno como traza OTLP con la convención OpenInference (Jaeger, Tempo, Datadog, Langfuse, Phoenix). Detecta también las ejecuciones de tests y recoge tu evaluación (+1/−1, etiquetas y notas).
Arquitectura Ligera: Hook, Backend y Dashboard
Levanta Mandarina con Docker y registra el hook en el settings.json del proyecto que quieras observar. Solo necesitas Node ≥ 20 en tu máquina, sin npm install.
{
"env": { "MANDARINA_PROJECT": "mi-proyecto" },
"hooks": {
"PreToolUse": [{
"matcher": "*",
"hooks": [{
"type": "command",
"command": "node <MANDARINA>/adapters/claude-code/send_event.mjs"
}]
}],
"PostToolUse": [ /* misma entrada */ ],
"Stop": [ /* misma entrada, sin matcher */ ]
}
}Repite la entrada para SessionStart, UserPromptSubmit, PostToolUseFailure, SubagentStart, SubagentStop, SessionEnd, Notification y PermissionRequest. Sustituye <MANDARINA> por la ruta absoluta del repo.
Claude Code lo ejecuta en tu máquina en cada hook. Enmascara secretos, evalúa las Reglas de bloqueo y envía el Evento; si Mandarina está apagado lo descarta y Claude Code sigue como si nada.
Fastify persiste los Eventos en SQLite, completa tokens, coste y Subagentes leyendo en solo lectura los Transcripts de ~/.claude, y los difunde por WebSocket. Nada sale de tu equipo.
Board, Agentes, Subagentes, Skills, MCP, Tests, Bloqueos, Seguridad, Evaluaciones y Presupuestos, en vivo. La exportación OTLP es opcional.
Métricas del Board de un vistazo
Sesiones trabajando y en pausa, tokens de entrada y salida, eficiencia de la caché, coste estimado y lo que queda de la cuota de tu suscripción de Claude (ventana de 5 h y semanal).
El Cockpit Definitivo para Agentes Claude Code
Sigue cada Sesión en vivo: su Estado, Subagentes, herramientas, skills y llamadas MCP, la ventana de contexto, los tokens, la caché y el coste, sin salir de tu equipo.
De la Fase 1 a la producción
Observabilidad local fundacional, esquema de Eventos normalizado, observador de Subagentes y métricas de caché.
- check_circle Ingesta de Eventos normalizados desde Claude Code (otros Harness, más adelante)
- check_circle Observador de Agentes y Subagentes: comparativa por Tipo, duración y coste
- check_circle Métricas de caché de prompts: tasa de acierto, ahorro neto y reescrituras
- check_circle Presupuestos por sesión/proyecto con parada preventiva (continue: false)
- check_circle Enmascarado de secretos y PII, avisos de inyección y Reglas de bloqueo
- check_circle Exportación OTLP OpenInference y evaluación humana (+1/-1)
- check_circle Alerta visual y sonora de Sesiones que esperan y uso de la suscripción
Cabina operativa en tiempo real para desbloquear al desarrollador y supervisar fricciones del harness.
- pending_actions Bandeja de Atención Requerida y notificaciones del sistema para las Sesiones que esperan
- commit Cambios de código por sesión (visor git diff, commits y PRs vinculadas)
- compress Visor de conversación completa y compactaciones de contexto (PreCompact)
- warning Detección heurística de bucles infinitos y fricción en herramientas
- dns Mandarina como servidor MCP de solo lectura para los propios agentes
Gestión activa de configuración del proyecto, editor de reglas de seguridad y evaluación de skills.
- tune Acceso a configuración del proyecto y recomendaciones para CLAUDE.md
- psychology Editor y evaluador de skills (SKILL.md con benchmark de disparo)
- extension Gestor de plugins y marketplaces para hooks de Claude Code
- gavel Editor de reglas de bloqueo con modo auditoría y prueba en seco
El control vive donde el equipo ya colabora, el repositorio: sin SSO en la nube ni paneles multiusuario.
- policy Políticas compartidas en el repo (mandarina.yaml: presupuestos, umbrales de parada y enmascarado de PII)
- rate_review Auditoría de IA en Pull Requests: comentario automático desde CI con coste, caché y riesgos de seguridad
- query_stats Métricas agregadas anónimas: resumen semanal de ahorro y eficiencia, sin código ni datos sensibles
Un modelo modular y abierto en lugar de una orquestación rígida entre agentes de terceros.
- storefront Marketplace local de skills y hooks: instalar, actualizar y probar CLAUDE.md, skills y filtros de seguridad
- lan Mesh local P2P en LAN para compartir aprendizajes de prompts y bucles a evitar, sin servidores en la nube
- api APIs abiertas para CI/CD: herramientas internas consultan el estado de los agentes
Informes de auditoría, orquestación multi-agente y el nivel producción para servidores compartidos.
- assessment Reporting exportable, comparador de sesiones y trazabilidad de criterios de aceptación
- hub Orquestación multi-agente y delegación cruzada (Claude Code <-> Codex)
- play_circle Lanzador headless de tareas con cola, cuotas de concurrencia y HITL en UI
- badge Autenticación multiusuario SSO/OIDC y métricas de resultado por PR/commit
Pon Mandarina en marcha
Sin cuentas en la nube ni tarjetas: Docker para Mandarina y un hook de Claude Code en tu máquina.
docker compose up
- 1Clona el repo y ejecuta docker compose up: backend en 127.0.0.1:4000 y dashboard en 127.0.0.1:4200.
- 2Registra el hook send_event.mjs en el settings.json del proyecto que quieras observar.
- 3Abre el dashboard: el indicador debe decir «En vivo» y tus Sesiones aparecen al enviar un prompt.