Metadata-Version: 2.4
Name: onesensei
Version: 0.2.3
Summary: Monitor local y privado de tu uso de IA (Claude Code y más). 100% local, solo lectura.
Project-URL: Homepage, https://github.com/OneTerminal-co/sensei
Author: Yulian Zapata
License: Proprietary
License-File: LICENSE
Keywords: claude-code,cost,dashboard,local,privacy,telemetry
Requires-Python: >=3.9
Provides-Extra: pro
Requires-Dist: cryptography>=42; extra == 'pro'
Provides-Extra: voice
Requires-Dist: piper-tts>=1.4; extra == 'voice'
Description-Content-Type: text/markdown

# 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.*

```bash
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`:

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

```json
"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:

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

### Atribución por cliente

```json
"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

```json
"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):

```json
"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

```bash
# Portable — sin instalación permanente:
uvx onesensei

# O permanente:
pip install sensei
sensei
```

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

```bash
sensei morning
```

Instalarlo como job diario en Mac:

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

O con crontab:

```bash
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

- [x] **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`
