Guía

En esta página

Instalar
Primera sesión
Tus números
Conectar el hub
Subagentes
Configuración
Bueno saberlo

Instalar

pi install npm:kankaku

También: pi install git:github.com/soyunninja/kankaku (añade @v0.4.6 para fijar versión), o pi install /ruta/local sin copiar. Probar sin instalar: pi -e /ruta/local.

Tu primera sesión

No actives nada — kankaku mide desde el siguiente prompt. Si tienes un hub, al abrir un proyecto nuevo te pregunta el cliente y el proyecto; puedes saltarlo, y si dices que sí a recordarlo, no vuelve a preguntar.

Tus números

/kankaku            # resumen de hoy
/kankaku tasks      # una línea por tarea
/kankaku sync       # sube lo pendiente al hub
/kankaku export     # csv o json

Conectar el hub (opcional)

export KANKAKU_PB_URL="https://tu-hub.example"
export KANKAKU_PB_EMAIL="service@tu-hub.example"
export KANKAKU_PB_PASSWORD="…"

Usa una cuenta de servicio, nunca la tuya. Sin esto, kankaku funciona igual — el cliente queda como texto libre.

Con Engram. Si el hub tiene Engram configurado, cada sesión llega con su objetivo y un resumen de lo hecho, junto al tiempo y el coste. Se activa con KANKAKU_ENGRAM_URL en el servidor del hub. Sin Engram, el hub se ve exactamente igual.

Subagentes y gentle-ai

kankaku no necesita gentle-ai. Lo esencial sale de los eventos de pi: trabajo frente a espera, tokens, coste, modelo, recuperación ante caídas y sincronización con el hub.

Donde sí importa el mecanismo es en los subagentes:

gentle-pi y pi-subagents marcan a sus hijos. kankaku los une a su orquestador con certeza, coste incluido.
El ejemplo de subagentes de pi no marca nada. kankaku lo une por ascendencia de procesos, comprobando la identidad del proceso.
Otro mecanismo: decláralo con KANKAKU_SUBAGENT_TOOLS y KANKAKU_SUBAGENT_CHILD_ENV. Si no, un hijo detectado queda como incierto: su tiempo se reporta aparte y nunca se cuenta como tarea nueva.

La etiqueta review viene preparada para gentle-ai review. Si no lo usas, no aparece. Se cambia con KANKAKU_SEGMENTS.

Configuración

Variable	Por defecto	Significado
`KANKAKU_DIR`	`.kankaku`	Directorio para el log de trabajo (`worklog.jsonl`) y los checkpoints de recuperación ante fallos, relativo al cwd del proyecto salvo que sea una ruta absoluta.
`KANKAKU_INTERACTIVE_TOOLS`	`ask_user_question,ask_user_choice`	Lista de nombres de herramientas, separados por comas, cuya ejecución cuenta como tiempo de espera.
`KANKAKU_SEGMENTS`	`review=bash:\bgentle-ai review\b`	Reglas «tag=tool:regex» separadas por «;» para segmentos etiquetados (por defecto, la única regla «review»).
`KANKAKU_CLIENT`	`(unset)`	Cliente de facturación por defecto para este proyecto; menor precedencia que «/kankaku client», mayor que el «config.json» del proyecto.
`KANKAKU_ROLE`	`(unset)`	Fuerza el rol («orchestrator»/«subagent») solo para una invocación — nunca lo exportes globalmente: `KANKAKU_ROLE=orchestrator pi …`.
`KANKAKU_PB_URL`	`(unset)`	URL del hub PocketBase. Debe ser HTTPS salvo que apunte a localhost/127.0.0.1/::1.
`KANKAKU_PB_EMAIL`	`(unset)`	Email de la cuenta de servicio del hub.
`KANKAKU_PB_PASSWORD`	`(unset)`	Contraseña de la cuenta de servicio del hub.
`KANKAKU_MACHINE`	`OS hostname`	Nombre de esta máquina, adjunto a cada registro como «machine» una vez configurado el hub.
`KANKAKU_SYNC_PROMPT`	`none`	Privacidad del prompt al sincronizar: «none» (omitido), «truncated» (primeros 120 caracteres) o «full».
`KANKAKU_SYNC_WINDOW_HOURS`	`24`	Horas hacia atrás desde la marca de agua que se reevalúan en cada sincronización, para capturar subagentes que terminan tarde.
`KANKAKU_SYNC_RECORDS`	`1 (enabled)`	«0» desactiva la subida de «work_records» (detalle bruto); «task_entries» siempre se sube.
`KANKAKU_SYNC_AUTO`	`1 (enabled)`	«0» desactiva la sincronización automática en «session_start»/«agent_settled»; «/kankaku sync» sigue funcionando.
`KANKAKU_SYNC_MIN_INTERVAL_MINUTES`	`5`	Minutos mínimos entre sincronizaciones automáticas; «0» desactiva el límite. Nunca afecta a una sincronización manual.

Bueno saberlo

El prompt nunca sale de tu máquina salvo que lo actives.
Un subagente en paralelo no duplica el tiempo.
Un corte no borra nada — queda marcado como interrumpido.
kankaku estima el coste; nunca factura.
/kankaku doctor diagnostica sin tocar la red.

Medida	Qué es
tiempo de trabajo	lo que trabajó de verdad
tiempo de espera	lo que te esperó a ti
wall-clock time	el total, de principio a fin