onesensei 0.3.0

Monitor local y privado de tu uso de IA (Claude Code y más). 100% local, solo lectura.

Sensei

El que observa, entiende y enseña.

Construís con agentes de IA todos los días. Claude Code, opencode, Kiro, varios modelos, decenas de sesiones, varios clientes. Pero al final del mes tenés una pregunta que nadie responde: ¿cuánto costó todo eso y valió la pena?

Sensei observa tu trabajo. En silencio, localmente, sin enviar nada a ningún lado. Cada mañana te entrega un reporte. Cada vez que lo pedís, te dice exactamente a dónde fue tu plata y qué patrones detectó. Y cuando te ve hacer lo mismo por novena vez, dice: eso deberías convertirlo en un skill.

uvx onesensei       # abrir el dashboard
sensei morning      # tu briefing diario
sensei doctor       # ver qué puede leer Sensei

---

La historia

6:47 AM. Antes de que abras la laptop, Sensei ya estuvo trabajando.

Leyó todas las sesiones de ayer — Claude Code, opencode, Kiro IDE y Kiro CLI. Calculó el costo exacto: $100/mes de tu plan Claude Max, 2.6B tokens usados, 1.8 credits de Kiro. Miró qué modelo usaste para qué, notó que gastaste el 82% del presupuesto en Opus para tareas que Sonnet resuelve igual de bien, y estimó cuánto te cuesta eso por mes. Revisó tus repos git por cambios sin commitear y sacó la próxima acción de cada STATUS.md. Detectó que arrancaste cinco sesiones de presales esta semana con contexto casi idéntico — el mismo brief del cliente, tipeado desde cero cada vez.

A las 7:00 AM imprimió esto en tu terminal:

════════════════════════════════════════════════
  Sensei · Reporte matutino — 2026-06-30
════════════════════════════════════════════════
  Gasto total     : $100.00/mes (Claude Max)
  Tokens          : 2.6B (suscripción)
  Valor mercado   : $37.5k est.
  Kiro CLI        : 1.8 credits

  ⚡ 2 insights:
    🔴 Opus está haciendo trabajo que Sonnet puede hacer
       $0 adicional pero sí costo de oportunidad
    🔵 5 sesiones largas sin checkpoint

  💡 2 skills para crear:
    · client-bootstrap (alta)
    · eks-triage (alta)
════════════════════════════════════════════════

---

Qué hace Sensei

┌─────────────────────────────────────────────────────────┐
│  Sensei · tres capas                                    │
│                                                         │
│  OBSERVAR    lee tus archivos locales (Claude Code,     │
│              opencode, Kiro IDE, Kiro CLI, git)         │
│              — nunca los escribe                        │
│                                                         │
│  ENTENDER    costo exacto por sesión, por modelo,       │
│              por cliente. Suscripción vs API exacto.    │
│              Proxy de ROI. Cache hit. Tendencia 30d.    │
│                                                         │
│  ENSEÑAR     Reglas del Coach: cuándo cambiar de        │
│              modelo, cuándo hacer checkpoint, qué        │
│              convertir en skill. Evidencia incluida.    │
└─────────────────────────────────────────────────────────┘

---

Fuentes

Herramienta	Superficie	Qué captura	Unidad
Claude Code	CLI	Tokens por sesión/modelo (con desglose input/output/cache), caché, costo exacto	USD (API o suscripción)
opencode	CLI	Sesiones SQLite, modelo usado, tokens con desglose	USD o suscripción
Kiro IDE	VS Code ext.	Tokens por workspace, costo por sesión	USD
Kiro CLI	Terminal	Credits consumidos por turn	credits
GitHub Copilot	VS Code	Sesiones de chat, turns, modelo	suscripción
git	repos	Rama, dirty flag, STATUS.md	—

Kiro IDE lee de ~/Library/Application Support/Kiro/User/globalStorage/kiro.kiroagent/. Kiro CLI lee de ~/.kiro/sessions/cli/. opencode lee de ~/.local/share/opencode/opencode.db (SQLite).

Claude Desktop (Cowork y sesiones despachadas): cuando Claude Code corre embebido en la app de escritorio (terminal integrada o sub-agentes de Cowork), el transcript completo se escribe en la misma ruta que la CLI (~/.claude/projects/) y Sensei lo cuenta con costo exacto. Cuando un sub-agente no llega a persistir ese transcript completo, Sensei recupera un resumen parcial de ~/.claude/usage-data/session-meta/ (solo tokens input/output, sin cache, tarifa _default) y lo muestra separado y marcado como estimado — nunca sumado al costo exacto.

Límite conocido: esto solo cubre el motor de Claude Code. Las conversaciones de Chat y Design (canvas/artifacts) de Claude Desktop que no invocan ese motor no dejan ningún archivo local con conteo de tokens — ese dato vive del lado de Anthropic, no en disco. Como Sensei es LOCAL ONLY / READ ONLY, no hay forma honesta de reconstruir ese costo sin inventarlo, así que esas sesiones no aparecen en absoluto.

---

Facturación por modelo

Sensei entiende que dentro de una misma herramienta podés tener modelos con distinto esquema de pago. Se configura en la UI de Settings (/settings) o directamente en ~/.sensei/config.json:

"sources": {
  "claude_code": {
    "model_billing": { "_default": "subscription" },
    "subscriptions": [
      { "name": "Claude Max", "monthly_usd": 100, "covers": ["*"] }
    ]
  },
  "opencode": {
    "model_billing": { "_default": "free" }
  },
  "kiro": {
    "model_billing": { "kiro/cli": "credits", "_default": "api" }
  }
}

Tipos de facturación:

Tipo	Qué hace Sensei
api	Costo exacto = tokens × tarifa. Se suma al total USD.
subscription	Costo = $0 adicional (cubierto por el plan). Se muestra el monthly_usd del plan.
free	Costo = $0. Los tokens se cuentan pero no se cobran.
credits	Unidad propia (Kiro CLI). No se mezcla con USD.

Presets en la UI de Settings — un clic para configurar:

• Claude Code: API key · Claude Pro $20/mes · Claude Max $100/mes · Claude Max $200/mes · Personalizado
• opencode: API key · Modelos locales (gratis) · Plan mensual · Personalizado
• Kiro: Solo IDE por token · Solo IDE plan mensual · Solo CLI credits · CLI+IDE · Personalizado

---

Configuración

Editá ~/.sensei/config.json o usá /settings en el dashboard:

Precios (costo exacto, no estimado)

"pricing": {
  "models": {
    "claude-opus-4-8":   { "input": 15.00, "output": 75.00,
                           "cache_read": 1.50, "cache_write": 18.75 },
    "claude-sonnet-4-6": { "input": 3.00,  "output": 15.00,
                           "cache_read": 0.30, "cache_write": 3.75 },
    "claude-haiku-4-5":  { "input": 0.80,  "output": 4.00,
                           "cache_read": 0.08, "cache_write": 1.00 }
  }
}

¿Usás Bedrock? Reemplazá estos valores con tus tarifas de Bedrock. Sensei calcula tokens × tarifa — nunca estima.

Alias de modelos

Si opencode o Kiro usan nombres internos distintos al modelo real:

"model_pricing_alias": {
  "big-pickle": "claude-sonnet-4-6"
}

Atribución por cliente

"clients": {
  "map": {
    "acme-prd-*":       "Client A",
    "bancoomeva-cards": "Client A",
    "freelance-*":      "Client B",
    "my-brain":         "Personal"
  }
}

Soporta comodines prefix-*. Los proyectos sin match quedan como "Sin asignar".

Objetivos

"goals": {
  "monthly_budget_usd": 300,
  "target_score": 80,
  "client_budgets": { "Client A": 200 }
}

Editables en /settings. Con presupuesto configurado, el tab Costos muestra el gasto API real del mes, la proyección lineal a fin de mes (etiquetada como inferida) y un semáforo; con target_score, el Coach muestra la barra de progreso; client_budgets agrega semáforo por cliente. sensei morning incluye todo en el bloque 🎯 Objetivos.

---

Cerrar el loop: de detectar a escribir

Sensei no solo diagnostica — cierra el ciclo con números medidos:

1. Detectar — el Coach mide contexto repetido de verdad: agrupa sesiones de un mismo proyecto cuya apertura es idéntica (hash exacto del primer mensaje) y te dice cuántos tokens re-enviaste. El grafo del Perfil marca nodos con oportunidad (proyecto con sesiones repetidas → CLAUDE.md; framework recurrente → skill).
2. Cuantificar — el Simulador de model-mix (tab Costos) recalcula tu desglose real de tokens bajo otra tarifa: aritmética exacta, no estimación. La autopsia de sesión (botón "¿Por qué?" en el Coach) desglosa una sesión cara por tipo de token — p.ej. "45% del costo fue cache read".
3. Generar — CLAUDE.md / skill sugerido por el CLI de IA local (con fallback a reglas si no hay CLI).
4. Escribir — el botón "Aplicar…" guarda el archivo generado, con doble restricción del server: solo dentro de tu HOME y solo archivos llamados CLAUDE.md o SKILL.md. Siempre confirmado por vos.

Además: export CSV de todas las sesiones (botón en Costos o GET /api/export.csv) con la base de cada costo declarada por fila (api / plan / credits), burn rate real (tokens/min medidos del tail de los transcripts activos — sin actividad muestra 0.0, nunca un número inventado) y trayectoria del score (serie de tus snapshots matutinos reales).

---

En vivo: el costo mientras estás gastando

Todo lo anterior mira hacia atrás. El copiloto en vivo actúa en el momento:

sensei statusline — el costo de tu sesión activa de Claude Code, en tu prompt, en cada turno:

⛩ $2.41 · 187k tok · sonnet-4-6 · ≈$0.08/turno

Agregá a ~/.claude/settings.json (Sensei no toca ese archivo — es tuyo):

"statusLine": { "type": "command", "command": "sensei statusline" }

Lectura incremental: guarda un cursor por sesión en ~/.sensei/cache/live/ y solo lee los bytes nuevos — ~40ms por invocación aunque el transcript pese cientos de MB. El ⚠ aparece al pasar 200k tokens (el umbral del coach: de ahí en más cada turno cuesta más sin ganar precisión).

/live (◉ en la nav del dashboard) — las sesiones activas de los últimos 30 minutos (Claude Code + opencode) con costo acumulado, ≈ costo del próximo turno (= el último observado, etiquetado como inferido) y barra de progreso hacia el umbral de cierre. Refresco cada 5s.

---

Vistas del dashboard

  [Resumen] [Tendencia] [ROI] [Skills] [Proyectos] [Costos] [Coach] [Perfil]

  Resumen     → cards por herramienta (plan/API/credits/tokens),
                anillo de burn rate, gasto total, cache hit,
                ROI, sesiones activas, IA subsidiada

  Tendencia   → gráfico de área 14/30d por herramienta:
                costo USD + tokens, créditos Kiro CLI aparte

  ROI         → scatter por sesión
                sage=replicar · sky=ok · gold=neutral · rose=revisar

  Skills      → ranking de uso con gráfico de barras

  Proyectos   → rama git + flag dirty + próxima acción
                ordenados por costo (donde más invertís)

  Costos      → presupuesto con proyección, barras por cliente
                (con semáforo por presupuesto) + por herramienta
                + por modelo, simulador de model-mix, export CSV

  Coach       → score de madurez con trayectoria y objetivo,
                insights con evidencia (badges nueva/recurrente),
                autopsia de sesiones caras, contexto repetido
                medido, sugerencias de skills con "Aplicar…"
                "Sin datos = sin insight" (nunca fabrica)

  Perfil      → mapa de actividad, burn por hora, distribución
                de tamaño de sesiones, tendencia de modelos

---

Instalación

# Portable — sin instalación permanente:
uvx onesensei

# O permanente:
pip install onesensei
sensei

Plataformas soportadas: macOS (Apple Silicon) y Windows. Linux y macOS Intel todavía no tienen wheel — pip install/uvx van a fallar ahí hasta que se agreguen (ver CHANGELOG).

La primera vez, el dashboard abre con un wizard de bienvenida de 3 pasos: qué fuentes detectó en tu máquina (con conteo real de sesiones), cómo pagás Claude (API / Pro / Max — decide cómo se calculan tus costos) y objetivos opcionales. "Omitir" usa los defaults y no vuelve a aparecer. Para setups por SSH o scripts existe la variante de terminal: sensei setup.

---

Comandos

Comando	Qué hace
sensei	Abrir dashboard en http://127.0.0.1:4317 (con wizard de bienvenida la primera vez)
sensei setup	Setup guiado en terminal (para SSH/headless; el del dashboard es el principal)
sensei statusline	Costo de la sesión activa para el statusLine de Claude Code
sensei doctor	Verificar entorno: rutas, fuentes, precios
sensei scan	Imprimir payload JSON completo y salir
sensei morning	Reporte terminal + snapshot en ~/.sensei/reports/
sensei install-morning	Instalar job diario a las 7am vía launchd (Mac)
sensei --port 5000	Cambiar puerto
sensei --no-browser	No abrir el navegador

---

Reporte matutino

sensei morning

Instalarlo como job diario en Mac:

sensei install-morning
# Corre todos los días a las 7:00 AM
# Logs: ~/.sensei/morning.log

O con crontab:

crontab -e
0 7 * * * sensei morning >> ~/.sensei/morning.log 2>&1

---

Reglas del Coach

El Coach detecta patrones como uso dominante de un modelo caro, cache hit bajo, concentración de gasto en un proyecto o sesiones largas recurrentes — cada regla se dispara solo con evidencia real y exacta, nunca especulación. Sin datos → sin insight. Fuente marcada como "regla" (heurística), sin IA generativa.

---

ROI

Cada sesión recibe un puntaje de valor (0-100) a partir de señales observables — actividad de git, profundidad de la sesión, indicios de output real — y se cruza contra el costo en USD para ubicarla en un cuadrante: replicar (alto valor, bajo costo), vigilar (alto valor, alto costo), neutral (bajo valor, bajo costo) o revisar (alto costo, bajo valor).

El valor es un proxy basado en señales observables. No es verdad absoluta — usalo como brújula, no como veredicto.

---

Las tres reglas que Sensei nunca rompe

1. SOLO LOCAL      el servidor escucha en 127.0.0.1 únicamente.
                   Nada sale de tu máquina.

2. SOLO LECTURA    Sensei nunca escribe tus archivos por su cuenta.
                   Única excepción, acotada y explícita: el botón
                   "Aplicar…" escribe CLAUDE.md/SKILL.md dentro de
                   tu HOME, solo cuando vos lo confirmás.

3. NÚMEROS HONESTOS  costo = tokens × tarifa, exacto.
                     Suscripción = plan declarado, no estimado.
                     Credits de Kiro CLI nunca se mezclan con USD.
                     El ROI siempre se etiqueta como proxy.

---

Roadmap

• Capa AI del Coach — narrativas vía CLI de IA local (Claude Code/opencode), 100% local, con fallback a reglas
• Paridad opencode — contexto repetido, autopsia y burn hoy son solo Claude Code
• Plugin VS Code — panel WebView dentro del editor
• Collector Bedrock — leer directamente desde logs de CloudWatch
• Multi-máquina — sincronizar ~/.sensei/reports/ vía iCloud/Dropbox
• Pesos ROI personalizados — scoring configurable en ~/.sensei/config.json