onesensei 0.6.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.

Construyes con agentes de IA todos los días. Claude Code, opencode, Kiro, varios modelos, decenas de sesiones, varios clientes. Pero al final del mes tienes 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 pides, 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, sin instalar nada
uvx onesensei morning  # tu briefing diario
uvx onesensei doctor   # ver qué puede leer Sensei

# instalado permanentemente (pip install onesensei), es el mismo binario `sensei`:
sensei morning
sensei doctor

---

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 Chat	VS Code ext.	Sesiones de chat, turns, modelo por defecto	suscripción
GitHub Copilot CLI	Terminal	Sesiones y turns (sin tokens/modelo — no lo expone en disco)	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). Copilot Chat lee workspaceStorage/*/GitHub.copilot-chat/transcripts/*.jsonl de VS Code (Code, Code - Insiders, VSCodium, Code - OSS — incluye instalaciones Snap y Flatpak en Linux). Copilot CLI lee ~/.copilot/session-store.db (SQLite) — ambas superficies se combinan en una sola fuente "copilot", cada sesión etiquetada por extra.surface (vscode/cli).

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 puedes 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
• GitHub Copilot: sin presets (billing siempre suscripción) — solo enable/disable, plan mensual opcional y override de ruta de la extensión VS Code. El CLI (~/.copilot) se auto-detecta siempre, sin campo de configuración propio.

---

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 }
  }
}

¿Usas Bedrock? Reemplaza 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 ti.

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 inviertes)

  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)

  Kata → recomendaciones de emergencia cuando el gasto
                aprieta (CLI ya instalada y sin usar, proyección
                sobre presupuesto, modelo local como respaldo).
                Sidebar ⚠ · feature Pro

  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 pagas Claude (API / Pro / Max de Anthropic — decide cómo se calculan tus costos, no confundir con el tier Pro de Sensei) 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 start	Levantar el dashboard en background, sin bloquear la terminal
sensei stop	Parar el server que corre en background
sensei status	Ver si hay un server corriendo, en qué puerto y desde cuándo
sensei setup	Setup guiado en terminal (para SSH/headless; el del dashboard es el principal)
sensei doctor	Verificar entorno: rutas detectadas (Claude Code, opencode, Copilot VS Code, Copilot CLI), fuentes, precios
sensei scan	Imprimir payload JSON completo y salir
sensei export [--output archivo.csv]	Exportar todas las sesiones en CSV (stdout por defecto)
sensei insights [--json]	Score de madurez y sus reglas — texto o JSON
sensei costo [--by-work-item] [--export carpeta] [--merge "carpeta/*.json"]	Costo agrupado por work item (rama git / nombre de proyecto). --export guarda el agregado de este dev; --merge suma varios exports ya generados (mutuamente excluyentes)
sensei roi	Scatter ROI en ASCII — deshabilitado por defecto, activar con features.roi_ascii.enabled: true en ~/.sensei/config.json
sensei profile [show|update]	Developer Memory: perfil inferido del stack/tipo de trabajo (show imprime, update recalcula y escribe ~/.sensei/profile/) — Pro, ver abajo
sensei statusline	Costo de la sesión activa para el statusLine de Claude Code (pensado para invocarse desde ~/.claude/settings.json, no a mano)
sensei morning [--speak]	Reporte terminal + snapshot en ~/.sensei/reports/ (--speak lo lee en voz alta con TTS nativo)
sensei install-morning	Instalar job diario a las 7am (launchd en Mac, crontab en Linux, Task Scheduler en Windows)
sensei install-daemon	Instalar el dashboard como servicio persistente — arranca solo en cada login (launchd en Mac, Task Scheduler en Windows)
sensei uninstall-daemon	Desinstalar el servicio persistente
sensei dojo connect --url <url> --token <token>	Conectar con un Dojo usando un token de activación de seat — desbloquea features Pro
sensei dojo status	Ver el estado de la licencia Pro actual
sensei dojo disconnect	Desconectar y volver a Basic
sensei --port 5000	Cambiar puerto
sensei --host 0.0.0.0	Cambiar host (el server igual valida Host contra loopback)
sensei --no-browser	No abrir el navegador
sensei --claude-path <ruta>	Override de la ruta de Claude Code (default ~/.claude)

---

Sensei Basic vs Pro

Sensei funciona completo sin nada más: cost engine, sensei export, copiloto en vivo, autopsia de sesión, contexto repetido y weekly diff son Basic, sin licencia, sin Dojo.

El corte es dato crudo vs. interpretación: todo lo que mide es Basic; todo lo que interpreta o recomienda — simulador de model-mix (Whatif), scatter de ROI, banda de referencia de cache, Developer Memory/Profile (sensei profile) y las recomendaciones de Kata — requiere una licencia Pro emitida por un Dojo. Sin licencia, esas vistas aparecen visibles pero bloqueadas en el dashboard, y sensei profile imprime el mensaje de cómo conectarte en vez de degradar en silencio.

El Coach base sí se ve en Basic. Los insights heurísticos del Coach (modelo caro que domina el gasto, proyecto concentrado, sesiones largas, presupuesto p90, eficiencia de cache) son locales, baratos y explicables por diseño — se calculan y muestran sin licencia, porque HONEST NUMBERS no depende de Pro. Lo único que queda detrás de Pro dentro del Coach es la categoría Kata y la capa narrativa con IA (los botones "¿Por qué?" / "¿Cómo lo hago?"). Sin licencia, el panel Coach muestra sus insights base más un aviso chico de upsell, nunca una pantalla tapada.

sensei dojo connect --url http://localhost:8088 --token <token-del-seat>
sensei dojo status
sensei dojo disconnect

La licencia es por seat (un token por dev), se firma con Ed25519 (Sensei solo guarda la clave pública del Dojo, nunca una privada), tiene TTL de 48h y se refresca sola. La feature Pro opcional requiere pip install "onesensei[pro]" (extra cryptography, no viene por defecto en ZERO DEPS) — sin ella, toda feature Pro degrada a bloqueada, nunca rompe.

---

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

(Pro — requiere sensei dojo connect, ver Sensei Basic vs Pro)

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

(Pro — requiere sensei dojo connect. El scatter ASCII de sensei roi es aparte: no depende de licencia, solo del feature flag roi_ascii.)

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 — úsalo 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 tú lo confirmas.

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