CLI

Instalar

npm install -g kankaku
kankaku setup

Si vienes de kankaku-tui

Ambos paquetes proporcionan el comando kankaku, por lo que instalar el nuevo sobre el anterior falla con EEXIST. Haz el cambio en este orden:

npm uninstall -g kankaku-tui
npm install -g kankaku
kankaku setup

Vuelve a ejecutar kankaku setup porque los hooks, la línea de estado y los comandos de Claude Code apuntan a la ruta del paquete instalado, que ha cambiado.

Requiere Node.js 24 o posterior. El hub local descrito más abajo funciona en macOS y Linux.

Configuración inicial

En una terminal, kankaku setup abre un asistente de pantalla completa: Agents, Hub, Roots, Review, Apply y Done. La lista de agentes indica si cada uno está configurado y su ruta; al desmarcar uno configurado se elimina kankaku de ese agente. Codex y OpenCode aparecen deshabilitados: todavía no tienen adaptador (o no están instalados). Puedes usar un hub existente (URL, correo, contraseña oculta y comprobación de salud), instalar uno localmente u omitirlo. «Instalar localmente» pide el correo y la contraseña del propietario y un puerto, rellenado con el primero que esté libre. Introduce carpetas raíz separadas por comas; se buscan proyectos hasta cinco niveles de profundidad y una carpeta con .kankaku/worklog.jsonl es un proyecto. Review muestra cada archivo que cambiará; Done abre el panel.

kankaku setup --yes acepta los valores predeterminados sin preguntas; kankaku setup --dry-run imprime el plan sin escribir nada. Se crea un <file>.bak antes del primer cambio en cada archivo. Se puede repetir la configuración. kankaku doctor muestra un informe de solo lectura.

Comandos

Pantallas

• Dashboard: trabajo, espera, coste, tareas y cache hit de hoy; últimos siete días; proyectos y su proporción; tarjeta del hub. c actualiza el catálogo, s sincroniza todo, S hace una sincronización completa y r recarga. h inicia o detiene el hub local desde su tarjeta.
• Tasks: tabla y detalle (prompt, cliente, proyecto, tarea del hub, tiempos total/de trabajo/de espera, coste, cache hit y subagentes). a alterna hoy/todo. m mueve la tarea seleccionada a otro cliente, proyecto y tarea del hub; M mueve todas las tareas de la vista que estén sin asignar en el hub.
• Catalog: clientes, proyectos y número de tareas abiertas; antigüedad de la caché e indicador de datos desactualizados.
• Sync: una tarjeta por proyecto; s sincroniza ese proyecto, f lo resincroniza por completo y S sincroniza todos.

1–4 cambian de pantalla, q sale, las flechas mueven la selección, Enter abre y Esc vuelve.

Reasignar tareas

• En Tasks, m mueve la tarea seleccionada y M mueve las tareas elegibles de la vista actual. Ambos abren un selector: primero el cliente, luego uno de sus proyectos y después una tarea de ese proyecto que no esté terminada; muestra la asignación actual → nueva para revisarla y el resultado por fila.
• M nunca modifica una fila que ya tenga asignado un cliente real en el hub. Si una tarea aún no está en el hub, se omite con el aviso «sync first».
• No se puede elegir una combinación de cliente, proyecto y tarea incoherente: se rechaza antes de enviar nada. Si no se puede actualizar el catálogo, el selector no se abre.
• La sincronización asigna solo al crear una fila y nunca revierte una reasignación. El registro local de trabajo no se reescribe: los informes locales conservan la asignación original y el hub tiene la corregida.

Temas

Usa --theme gentleman-sexy (predeterminado), --theme gentleman-cute o --theme gentle, o establece KANKAKU_TUI_THEME.

Hub local

kankaku hub install [--port N] [--owner-email E] descarga PocketBase para el sistema y la CPU desde el paquete npm kankaku-hub, verifica su SHA256, lo instala en ~/.kankaku/hub/, crea cuentas de superusuario, propietario y servicio y deja el hub en marcha. En una terminal pregunta el correo o la contraseña que falten (esta última oculta); sin interacción, proporciona tanto --owner-email como --owner-password. Repetirlo no modifica lo ya instalado. El puerto predeterminado es 8090. Si está ocupado, la instalación se detiene e indica uno libre para pasarlo con --port; nunca elige otro por sí sola. Una instalación existente conserva su puerto. La instalación local solo funciona en macOS y Linux.

Instalar un hub local no cambia el destino de sincronización de este equipo si está configurado para otro hub. Si ~/.kankaku/credentials.json apunta a otro hub, queda intacto; usa kankaku hub use para cambiar al local (con una copia de seguridad). kankaku hub status muestra sync: local hub, sync: <url> o sync: not configured.

kankaku hub start | stop | status | upgrade | logs [-n N] controla el hub. upgrade copia un nuevo app/<version>/, descarga PocketBase solo si cambia su versión, reinicia y nunca toca pb_data.

Configuración

~/.kankaku/tui.json guarda {"roots": [...]} y ~/.kankaku/credentials.json guarda {url,email,password}. Las variables de entorno prevalecen campo por campo: KANKAKU_PB_URL, KANKAKU_PB_EMAIL, KANKAKU_PB_PASSWORD. Otros ajustes: KANKAKU_SYNC_WINDOW_HOURS, KANKAKU_SYNC_PROMPT, KANKAKU_SYNC_RECORDS, KANKAKU_MACHINE, KANKAKU_TUI_THEME. Sin credenciales, el catálogo y el estado de sincronización muestran una nota y salen con código 0; la actualización del catálogo y los comandos de sincronización muestran un error y salen con código 1.