KittyClaw

KittyClaw es un plano de control local para el trabajo de software realizado por agentes de IA. Envía un ticket de software, observa cómo se mueve por el tablero en vivo, lee la ejecución que cambió el código, inspecciona su verificación y toma la decisión final de publicación tú mismo.

El producto demuestra tres cosas en un solo recorrido: un tablero en vivo, una ejecución legible y validación humana antes de la publicación externa. Los tableros nuevos comienzan con Backlog, Todo, InProgress, Blocked, Scheduled, Review y Done (las columnas siguen siendo personalizables). Las ejecuciones pueden usar Claude Code, OpenAI Codex, Grok Build o un modelo local de Ollama.

Sigue la demostración guiada de cinco minutos para repetir el recorrido con un ticket de software realista. El protocolo de prueba de activación complementario mide si los usuarios de prueba calificados alcanzan su primera ejecución en diez minutos.

Un proyecto puede dividirse en pipelines con nombres independientes cuyas identidades estables sobreviven a los cambios de nombre. Las columnas pueden tener procesadores genéricos con memoria persistente, habilidades de proyecto reutilizables, selección ordenada de tickets, reintentos duraderos y enrutamiento tipo interruptor hacia columnas en cualquier pipeline. Haz clic derecho en una columna y elige Configurar columna para editar su nombre, color, rol, posición, guía de tickets, procesador y enrutamiento sin perder el contexto visual del tablero. Los tickets en columnas Waiting o OwnerAction siempre muestran un bloque contextual destacado entre su descripción y su actividad, que explica si el propietario debe comentar o mover el ticket a una columna específica de validación/rechazo, o si KittyClaw lo reanudará automáticamente. Las columnas también pueden insertarse entre carriles existentes o añadirse al final directamente desde el Kanban; la página Workflows sigue siendo la vista global de pipelines y habilidades. El estado de ejecución es independiente de las columnas de negocio, por lo que una columna InProgress es opcional. El legado AutomationEngine sigue disponible para reglas basadas en disparadores, trabajo programado por cron/intervalos y compatibilidad hacia atrás. Los agentes se ejecutan a través de Claude Code, OpenAI Codex, Grok Build, Mistral Vibe o un modelo local de Ollama mientras su salida se transmite en vivo a la aplicación.

Cada procesador tiene versiones asociadas a su proyecto en .agents/processors/column-<id>/processor.json. Esta definición autoritativa contiene su misión, prompt explícito, modelo, habilidades, orden de tickets, política de reintentos y enrutamiento. SQLite guarda solo una proyección sincronizada en tiempo de ejecución y el estado de ejecución. Las lecciones persistentes viven junto a la definición en .agents/processors/column-<id>/memory/MEMORY.md.

Pila tecnológica

• .NET 10 / Blazor Server (SSR interactivo)

• SQLite mediante Entity Framework Core (una base de datos por proyecto)

• OpenAPI con documentación Markdown generada automáticamente

• Ejecución de agentes: al menos una CLI compatible — Claude Code CLI, OpenAI Codex CLI, Grok Build o Mistral Vibe. Ollama también es compatible para modelos locales a través de la CLI de Claude Code (configuración de modelo local).

• Opcional para la inicialización de repositorios, automatizaciones conscientes de Git y commits de agentes: Git

Requisitos previos

• .NET 10 SDK

• Al menos una CLI de agente en tu PATH: Claude Code (claude), OpenAI Codex (codex), Grok Build (grok) o Mistral Vibe (vibe). La ejecución con modelos locales requiere tanto la CLI de Claude Code como un servidor Ollama accesible.

• Opcional: Git (git en tu PATH) para la inicialización de repositorios, automatizaciones conscientes de Git y commits de agentes.

En el primer inicio, la ventana de bienvenida verifica Git y cada CLI de proveedor compatible usando las mismas rutas de ejecutables resueltas que se usan para el despacho: Claude Code (claude / KITTYCLAW_CLAUDE_BIN), OpenAI Codex (codex / KITTYCLAW_CODEX_BIN), Grok Build (grok, ~/.grok/bin o KITTYCLAW_GROK_BIN) y Mistral Vibe (vibe / KITTYCLAW_MISTRAL_BIN). También informa sobre la disponibilidad opcional de Ollama. Cualquier proveedor de agente es suficiente; las sondas que fallan o expiran no bloquean, y las funciones que dependen de Git siguen requiriéndolo.

Ejecución

Desde la raíz del repositorio:

run.bat        (Windows)
./run.sh       (macOS / Linux)

Ambos ejecutan dotnet watch --project KittyClaw.Web --non-interactive y sirven la aplicación en http://localhost:5230 con recarga en caliente habilitada.

Creación de un proyecto

Desde la página de inicio, selecciona Crear proyecto, ingresa un nombre y elige su espacio de trabajo. El explorador de carpetas integrado funciona en Windows, macOS y Linux sin abrir un diálogo nativo del sistema detrás del navegador. Expone el directorio de inicio, las unidades montadas o las raíces del sistema de archivos, las rutas de navegación, la navegación al directorio padre y la entrada directa de rutas. También puedes escribir una ruta absoluta y crear la carpeta si no existe.

Haz clic en Inicializar para:

1. Crear la entrada del registro del proyecto + la base de datos SQLite específica del proyecto.

2. Copiar la plantilla del proyecto desde ProjectTemplate/ (preamble.md, {agent}/SKILL.md, índice de {agent}/memory/MEMORY.md, memory-consolidation.md, automations.json, CLAUDE.md) al espacio de trabajo — archivos de agente en <workspace>/.agents/, CLAUDE.md en la raíz del espacio de trabajo.

3. Ejecutar git init si el espacio de trabajo no es ya un repositorio git (se omite si git no está instalado).

4. Crear un miembro para cada slug de agente encontrado en la plantilla.

5. Abrir el asistente de configuración del proyecto.

El asistente de configuración analiza un espacio de trabajo existente y propone pipelines, columnas, traspasos humanos, procesadores, enrutamiento y horarios distintos. Para una carpeta vacía, primero hace algunas preguntas sobre el propósito del proyecto, los entregables, las decisiones humanas y el trabajo recurrente. Las propuestas son gráficas: puedes añadir o quitar pipelines, revisar las columnas de cada pipeline, refinar un paso con un prompt y volver atrás antes de la aprobación. No se crea nada durante esta preparación; Crear el flujo de trabajo aplica y verifica el plan aprobado y luego abre el tablero.

Esta configuración de proyecto nuevo está deliberadamente separada del asistente de migración del tablero legado. La terminología de migración y la limpieza de automatizaciones legadas solo se muestran cuando un tablero existente basado en automatizaciones necesita conversión.

La carpeta del espacio de trabajo nunca se elimina con KittyClaw, incluso cuando eliminas un proyecto.

Almacenamiento de datos

Todos los datos de KittyClaw se almacenan localmente en %APPDATA%/KittyClaw/:

• registry.db — registro de proyectos

• projects/{slug}.db — base de datos específica del proyecto (tickets, comentarios, etiquetas, columnas, miembros)

• uploads/ — imágenes subidas

• runs/{runId}.json — instantáneas de ejecución de agentes (eventos, estado, código de salida)

• settings.json — idioma + indicador de incorporación

El estado del agente específico del proyecto vive en el espacio de trabajo: <workspace>/.agents/{agent}/memory/ (índice MEMORY.md + archivos de lecciones por tema), <workspace>/.agents/channel/ (estado de sesión), etc.

Estructura del proyecto

Arquitectura

La documentación de arquitectura por función vive en doc/. Comienza con procesamiento de pipelines y columnas para el modelo de múltiples pipelines, o doc/index.md para el mapa completo de la arquitectura.

API

Todos los endpoints están bajo /api. La documentación se genera automáticamente a partir de la especificación OpenAPI en vivo:

• Markdown legible por humanos: GET http://localhost:5230/api/docs

• JSON legible por máquinas: GET http://localhost:5230/openapi/v1.json

Servidor MCP

KittyClaw puede exponer un endpoint MCP integrado en http://localhost:5230/mcp (HTTP Streamable), de modo que cualquier cliente MCP pueda manejar el tablero — listar proyectos, crear y mover tickets, comentar y leer el diseño del tablero — sin tocar la API REST. Establece KITTYCLAW_MCP_ENABLED=1 antes de iniciar KittyClaw y luego conéctalo a Claude Code con:

claude mcp add --transport http kittyclaw http://localhost:5230/mcp

Siete herramientas se incluyen en v1: list_projects, list_tickets, get_ticket, create_ticket, comment_ticket, move_ticket, board_overview. El endpoint está deshabilitado por defecto y usa el mismo límite de confianza de localhost que la API REST. Detalles en doc/mcp.md.

Para agentes de IA

Esta aplicación está diseñada para ser operada por agentes de IA a través de su API REST. Así es como empezar:

1. Lee la documentación de la API en vivo en http://localhost:5230/api/docs — cada endpoint, ejemplo de solicitud/respuesta y esquema, siempre actualizado con el servidor en ejecución.

2. Identifícate — author es obligatorio en cada endpoint de mutación; omitirlo devuelve HTTP 400. Usa tu nombre de agente simple (p. ej. "programmer", "groomer"). El usuario humano es "owner".

3. Descubre el tablero — llama a GET /api/projects primero, luego GET /api/projects/{slug}/columns para conocer las etapas del flujo de trabajo y GET /api/projects/{slug}/members para los miembros asignables.

4. Usa el estado correcto — los estados de los tickets deben coincidir con los nombres de columna existentes. Obtén las columnas antes de mover tickets.

5. Registra tu trabajo — añade comentarios en los tickets para explicar lo que hiciste o lo que necesitas. Usa @menciones para notificar a miembros, #id para referenciar tickets en el mismo proyecto y #{slug}:{id} para referenciar tickets en otro proyecto.

6. Etiquetas y prioridad — usa GET /api/projects/{slug}/labels para descubrir las etiquetas disponibles y establece la prioridad en Idea, NiceToHave, Required o Critical.

7. Consulta menciones — llama a GET /api/projects/{slug}/mentions/{tu-handle} para encontrar tickets que te mencionan.

8. Sub-tickets — establece parentId al crear un ticket para convertirlo en hijo. Usa PUT /api/projects/{slug}/tickets/{id}/parent para reasignar el padre, o DELETE para desvincularlo. Lista los sub-tickets con ?parentId={id}.

9. Transferencias entre proyectos — usa POST /api/projects/{slug}/tickets/{id}/transfer solo después de verificar que el proyecto de destino tiene columnas, asignados y etiquetas compatibles. La operación preserva el árbol de tickets y su historial, o rechaza la transferencia sin modificar ninguno de los dos proyectos. Consulta Transferencia de tickets sin pérdida.

Convenciones

• Formato de autor: "owner" para el usuario humano, nombre de agente simple (p. ej. "programmer") para agentes de IA

• Niveles de prioridad: Idea, NiceToHave, Required, Critical

• Columna predeterminada: Backlog

Funciones de la interfaz

• Ventana emergente de bienvenida en el primer inicio que comprueba Git, Claude Code, OpenAI Codex, Grok Build, Mistral Vibe y Ollama

• Explorador de espacios de trabajo integrado multiplataforma con raíces, rutas de navegación, entrada directa de rutas y creación de carpetas

• Configuración guiada de nuevos proyectos que analiza el espacio de trabajo y propone pipelines y columnas editables antes de crear el flujo de trabajo

• Migración guiada de tableros heredados que conserva los tickets completados y retira las automatizaciones sustituidas solo tras la verificación

• Inicio unificado multiproyecto con tarjetas de proyecto y carriles kanban

• Kanban multipipeline con destinos de colocación permitidos y prohibidos visualmente diferenciados según el enrutamiento del procesador

• Editor contextual de columnas para estructura, rol, orientación del propietario, procesador, acciones ordenadas, tareas programadas y enrutamiento

• Vista de panel personalizable con mosaicos de arrastre libre (Markdown, KPI, gráficos, Heatmap, Timeline, …), creación de mosaicos mediante chat de IA y actualización automática mediante prompts de LLM

• Panel de detalle de tickets con comentarios y cronología de actividad

• Cajón de ejecución de agente en vivo (flujo SSE de la salida del proveedor, controles de dirección y detención)

• Cajón de chat de nuevas instrucciones para enviar un prompt ad hoc a un agente

• Renderizado de Markdown con soporte de referencias a tickets entre proyectos mediante @mention, #id y #{slug}:{id}

• Sintaxis de búsqueda avanzada: #42, @owner, >date, priority:critical, label:bug, by:owner

• Subtickets con relaciones padre/hijo y seguimiento de progreso

• Transferencias atómicas y sin pérdidas de árboles de tickets entre proyectos mediante la API REST

• Gestión de columnas directamente desde el tablero (insertar, duplicar, reordenar, configurar y marcar como leída)

• Gestión de etiquetas y miembros

• Subida de imágenes en descripciones y comentarios

• Soporte de modelos locales (Ollama): URL base por proyecto con autodescubrimiento de modelos, modelo predeterminado por miembro y configuración por acción en .agents/automations.json

• Despacho consciente del proveedor mediante Claude Code, OpenAI Codex, Grok Build, Mistral Vibe u Ollama, con traspaso de conversación y respaldo ante modelos no disponibles

Dashboard

Cada proyecto tiene una vista de Dashboard personalizable junto al tablero kanban. Los mosaicos se arrastran libremente, se actualizan automáticamente según un horario y pueden crearse o editarse desde el panel de chat de IA integrado: el agente escribe la carpeta del mosaico por ti.

Tipos de mosaico

Estructura de carpetas

Cada mosaico reside en su propia carpeta dentro de .dashboard/ en el espacio de trabajo del proyecto:

.dashboard/
  <tile-slug>/
    tile.yaml        # template, title, refresh schedule, prompt
    script.ps1       # optional refresh script (or script.sh, script.py, …)
    output.json      # last refresh output consumed by the template

Campos clave de tile.yaml

• template — uno de los ids de la tabla anterior.

• title — nombre mostrado en el encabezado del mosaico.

• refresh — intervalo (p. ej. 5m, 1h) para la actualización periódica.

• refreshAt — actualización a una hora del día en formato cron (alternativa a refresh).

• prompt — instrucciones enviadas al agente al (re)generar output.json.

Los mosaicos pueden crearse desde el panel de chat de IA del dashboard describiendo lo que deseas: el agente elige una plantilla, escribe tile.yaml, genera el script de actualización y produce el output.json inicial.

Informe de costes

La página Costs ofrece una vista en caché del uso de agentes por proyecto, de modo que abrir el informe es inmediato incluso con un historial de ejecuciones largo. Los ajustes predefinidos de fecha permiten seleccionar rápidamente los periodos habituales, mientras que los filtros de proyecto, pipeline y modelo pueden combinarse; las opciones de pipeline siguen automáticamente a los proyectos seleccionados. Una leyenda visible distingue los costes medidos de los costes estimados en los gráficos diarios.

Modelo de automatización

• Disparadores: interval, ticketInColumn, statusChange, subTicketStatus, ticketCommentAdded, gitCommit, boardIdle, agentInactivity.

• Condiciones: ticketInColumn, ticketCountInColumn, fieldLength, priority, labels, assignedTo, hasParent, allSubTicketsInStatus, ticketAge.

• Acciones: runAgent, moveTicketStatus, setLabels, assignTicket, addComment, consolidateAgentMemory, commitAgentMemory, executePowerShell, createTicket, httpRequest (webhooks salientes; los destinos de bucle local o enlace local están bloqueados salvo que se indique allowLocalTargets).

• El marcador de posición {assignee} en runAgent.agent / runAgent.concurrencyGroup se resuelve a partir del assignedTo del ticket que lo activa.

• Cadena canónica posterior a la ejecución: runAgent → consolidateAgentMemory (pasada claude centrada que selecciona el índice memory/ del agente y los archivos de temas) → commitAgentMemory (confirma el resultado).

Telemetría

KittyClaw envía un latido anónimo al día a un servicio de analítica compatible con autoalojamiento (Umami) para que sepamos cuántas instancias están activas y qué versiones se ejecutan en producción. La carga útil contiene exactamente tres campos y nada más:

• un id de instancia aleatorio (un GUID generado localmente en el primer inicio, no vinculado a ningún usuario, máquina ni dato de proyecto)

• la versión de KittyClaw

• la familia de sistema operativo (Windows / macOS / Linux)

Nunca se envían contenidos de tickets, nombres de proyectos, nombres de host ni detalles de uso. Los fallos son silenciosos y nunca afectan a la aplicación. Las instancias de desarrollo nunca envían telemetría.

Licencia

KittyClaw está licenciado bajo AGPL-3.0-or-later. El autoalojamiento y el uso personal no tienen restricciones; si distribuyes una versión modificada u ofreces una como servicio de red, debes publicar tu código fuente bajo la misma licencia.

Términos adicionales según AGPL §7 (texto completo en NOTICE.md): las obras derivadas deben mantener visible la atribución a KittyClaw (el aviso legal integrado y una declaración de «basado en KittyClaw» en su README), no deben tergiversar su origen y no reciben derechos sobre el nombre ni los logotipos de KittyClaw.

Dos cosas que la AGPL no afecta (consulta NOTICE.md):

• Tus proyectos: los archivos de plantilla que KittyClaw copia en tu espacio de trabajo (.agents/, CLAUDE.md, …) tienen además licencia MIT, y todo lo que la aplicación produce para ti (tickets, registros, commits de agentes, …) es tuyo, sin licencia. Gestionar un proyecto con KittyClaw nunca coloca ese proyecto bajo la AGPL.

• El pasado: las versiones hasta la v0.11 inclusive se publicaron bajo MIT y siguen disponibles bajo esos términos.

Más proyectos y contacto

→ Sitio + demo: kittyclaw.dev

Echa un vistazo a mis otros proyectos en ekioo.com.

Sígueme en X: @DamienHOFFSCHIR