Guía

Instalar

Recomendado para todos los agentes:

npm install -g kankaku
kankaku setup

kankaku instala todo: la CLI, la extensión de pi y la integración de Claude Code.

Requiere Node.js 24 o posterior. kankaku setup abre un asistente para elegir agentes (pi, gentle-shell, Claude Code), un hub (existente, local o ninguno) y las carpetas de proyectos. Después, kankaku abre el panel. Para scripts, kankaku setup --yes acepta los valores predeterminados sin preguntas y kankaku setup --dry-run imprime el plan sin escribir nada. kankaku doctor muestra el estado en modo de solo lectura. Consulta la guía de la CLI.

Solo la extensión de pi:

pi install npm:kankaku-pi

pi install npm:kankaku sigue funcionando para las instalaciones existentes, pero también incorpora las dependencias de la CLI a pi; nunca mantengas ambas fuentes en la misma configuración, o la extensión se cargará dos veces y duplicará cada medición.

También: pi install git:github.com/soyunninja/kankaku (añade @v1.3.0 para fijar la versión actual; las etiquetas v0.9.0 a v0.12.0 no se pueden cargar desde git), o pi install /absolute/path/to/kankaku/packages/pi, sin copiar. Prueba sin instalar: pi -e /absolute/path/to/kankaku/packages/pi. Con gentle-shell, estos mismos comandos de instalación usan gentle-shell install ….

Tu primera sesión

En pi se mide desde el siguiente prompt; en Claude Code ocurre lo mismo después de configurarlo con kankaku setup (consulta «Claude Code» más abajo).

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.

En la TUI de pi, /kankaku abre un panel con marco. El título (>_ kankaku · <Pantalla>) cambia según la pantalla:

• Target: Cliente, proyecto, tarea del hub y etiqueta.
• Report: Resumen, tareas, sesiones, clientes y proyectos; hoy o todo; fijar en el chat.
• Sync: Estado, sincronizar ahora o todo, historial y catálogo.
• Export: CSV o JSON, hoy o todo, escribir archivo.
• Doctor: Subagentes huérfanos o inciertos.
• About: Versiones, directorio, hub y ajustes.
• Navegación: ↑/↓ mover, Enter abrir, Esc/← volver, q salir.

Esc o ← cierra el panel desde la raíz; q lo cierra desde cualquier pantalla. Las filas y las indicaciones del pie solo se pueden pulsar con el ratón en el modo de pantalla completa de pi, no en el modo normal. Los subcomandos siguen funcionando sin cambios y omiten el panel en la TUI. El modo sin interfaz (print/RPC) también usa subcomandos; allí, /kankaku sin argumentos muestra los totales de hoy.

Claude Code

Marca Claude Code en kankaku setup. No necesitas clonar el repositorio ni usar --plugin-dir. El asistente incorpora statusLine (que informa del coste por prompt) y los hooks de los eventos declarados en ~/.claude/settings.json sin alterar otras claves ni hooks. Instala los comandos de usuario en ~/.claude/commands/kankaku/. Repite la configuración si cambia la ruta de instalación, por ejemplo, al cambiar de versión de Node. No inicies también Claude Code con --plugin-dir: los hooks se ejecutarían dos veces y duplicarían los registros.

Cada prompt produce un registro con el mismo formato que pi: tiempo total, espera por una pregunta o permiso, tiempo de trabajo (total menos espera), tokens y coste. El registro identifica al agente que midió (claude-code), el plugin (kankaku-claude), su versión y la versión de Claude Code, incluso si lo sincroniza la CLI. Cliente y proyecto se resuelven primero desde el config.json del proyecto y luego desde las rutas del repositorio en el catálogo del hub guardado en caché; los hooks no usan la red. Un prompt interrumpido termina en su última actividad registrada. El coste es la diferencia entre los totales acumulados de la sesión en dos cierres consecutivos; cada prompt comienza donde terminó el anterior, así que lo gastado entre prompts se asigna al siguiente registro. Los tokens incluyen el trabajo de los subagentes, incluso los gastados entre prompts, que se asignan al siguiente registro. Una ejecución sin interfaz (claude -p) no tiene statusline; su coste se lee del propio registro de sesión de Claude Code cuando termina la sesión.

kankaku lee esos datos del registro de sesión que Claude Code guarda en disco: números de tokens, versión de Claude Code y si la sesión es interactiva o sin interfaz. No lee ningún prompt ni ninguna respuesta, ni envía nada a ningún lugar por ello.

Los números de tokens, y con ellos cache hit, proceden del registro de sesión de Claude Code, un formato interno que no es una interfaz documentada: si una actualización de Claude Code lo cambia, se seguirán escribiendo registros, pero sin tokens (y, en las ejecuciones sin interfaz, sin coste), hasta que kankaku se actualice. El coste por prompt es una parte del total de la sesión obtenido de statusline. El tiempo de los subagentes en segundo plano no se mide por separado; la espera de un permiso termina con el siguiente evento del hook, no con el clic. Todavía no se puede cambiar el cliente ni el proyecto desde Claude Code.

Tus números

/kankaku all        # resumen completo (subcomando en la TUI)
/kankaku tasks      # una línea por tarea
/kankaku sync       # sube lo pendiente al hub
/kankaku export     # csv o json

Las líneas de informe con tokens registrados terminan en cache hit NN%: la proporción de tokens de entrada del prompt servidos desde la caché del proveedor, cacheRead / (input + cacheRead + cacheWrite). Si no hay tokens registrados, se omite el sufijo; no aparece 0%. Por ejemplo: orchestrator: work 41m00s, waiting 0m00s, 1 record(s), $0.82, cache hit 68%. También se aplica a las líneas de tareas, clientes y proyectos de pi. Desde 1.3.0, los registros de Claude Code también incluyen números de tokens, por lo que sus líneas muestran cache hit; los registros escritos con una versión anterior no los tienen.

Conectar el hub (opcional)

¿Quieres verlo primero? Abre https://demo.kankaku.io e inicia sesión con demo@kankaku.io / demokankaku (de solo lectura, con datos ficticios). El hub es de código abierto: github.com/soyunninja/kankaku_hub.

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

¿Aún no tienes hub? kankaku setup puede instalarlo en este equipo: elige «instalar localmente» en el paso Hub o ejecuta kankaku hub install. Consulta la guía de la CLI.

Usa una cuenta de servicio, nunca la tuya. Sin esto, kankaku funciona igual — el cliente queda como texto libre. El catálogo de clientes y proyectos del hub se actualiza al inicio de cada sesión (el selector espera brevemente); /kankaku catalog refresh permite actualizarlo manualmente.

Usa /kankaku task (o /kankaku task pick) para vincular esta sesión con una tarea abierta o en curso del proyecto actual en el hub; las filas de tareas sincronizadas después llevan ese vínculo. /kankaku task clear lo quita. El vínculo solo dura esta sesión: no se guarda en config.json ni se solicita al iniciar la sesión, y /kankaku target pick|clear lo elimina. Los subagentes no lo heredan. Las tareas se crean en el hub, no en kankaku. La asignación se hace solo al crear cada fila: si cambias el responsable en la aplicación web del hub, una sincronización posterior no lo revierte.

En Claude Code, /kankaku:task vincula una tarea del hub a la sesión. Si cambias de hub, kankaku vuelve a subirlo todo: no reutiliza el estado de sincronización del anterior. El agente mostrado en una fila del hub es el que midió el trabajo (pi o Claude Code), no la herramienta que lo sincronizó.

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

La pantalla About del panel muestra todos los ajustes que solo se configuran mediante variables de entorno en modo de solo lectura, junto con las versiones, el valor resuelto de KANKAKU_DIR y la URL del hub.

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.
• kankaku doctor (terminal) y /kankaku:doctor (Claude Code) diagnostican el conjunto de la instalación.