Tzolk'in

Gestor de proyectos agent-native + memoria persistente para Claude Code. Kanban sobre el ciclo de vida del software, operable por el agente vía una CLI barata en tokens (tzolk), con MCP y un dashboard web sobre el mismo núcleo.

Lee en Markdown · Actúa por acciones · Persiste en SQL. El estado solo cambia por comandos tipados (no se corrompe); cada acción escribe un evento → memoria reconstruible entre sesiones.

Modelo: Tablero 2D — cada fase del ciclo de vida (Requerimientos, Diseño, Desarrollo, Testing, Deploy) es un kanban propio; una tarea vive en una celda (fase, estado). area cruza fases para trazar un módulo; type (core/feature/bug/…) y release son opcionales. Diseño completo en DESIGN.md.

Requisitos

• Node.js 20+
• PostgreSQL (o Docker)
• macOS / Linux

Instalación

npm i -g tzolk      # o úsala al vuelo: npx tzolk <comando>

Levanta un Postgres (el esquema se crea solo en el primer arranque, todo idempotente):

docker run -d --name tzolk-db \
  -e POSTGRES_USER=agentpm -e POSTGRES_PASSWORD=agentpm -e POSTGRES_DB=agentpm \
  -p 5432:5432 postgres:16-alpine

La CLI/MCP usan DATABASE_URL (por defecto postgresql://agentpm:agentpm@localhost:5432/agentpm; sobreescribible por env). Prueba: tzolk new-project "Demo" && tzolk board demo.

CLI tzolk (superficie principal)

tzolk help                                  # manifiesto ligero · tzolk <cmd> --help para detalle
tzolk projects
tzolk board <proj> [--release|--area|--type|--stage]
tzolk task <proj> <T-N>
tzolk new-task <proj> "<título>" --stage <fase> --assignee <quién> [--type --area --priority …]
tzolk move <proj> <T-N> [--status <col>] [--stage <fase>]
tzolk edit <proj> <T-N> [--title --body --priority …]
tzolk subtask add|check <proj> <T-N> …
tzolk note <proj> "<título>" --body <md> [--kind] [--task]

# Gestión de proyectos
tzolk project <proj>                        # detalle: descripción, responsables, repos
tzolk project <proj> desc --body <md>       # · repo add|rm <url> · member add|rm <email> [--role]
tzolk rename <proj> "<nombre>" [--slug]     # · archive <proj> [--undo] · del-project <proj> --force

# Organizaciones (multi-tenant: agrupan proyectos e invitados; roles owner/admin/member/viewer)
tzolk org list|new|use <slug>|members
tzolk org member add|rm <org> <email> [--role] · org role <org> <email> <rol>
tzolk org invite <org> <email> [--role]     # invitación por email (registro invite-only)

# Setup / sesión
tzolk login                                 # vincula el agente por OAuth (sin pegar tokens)
tzolk init [--project]                      # instala skill+comandos y deja el setup en CLAUDE.md
tzolk whoami · tzolk logout

Flags globales: --json (salida lean para parsear), --actor <nombre>, --agent <id>.

Activar en Claude Code

• Skill + CLI (recomendado): coloca la skill en .claude/skills/tzolk/ — el agente usa la CLI tzolk por Bash. El repo ya la trae junto con los slash commands /tzolk-*.
• MCP (alterna): el repo trae .mcp.json (servidor tzolk). Aprueba el servidor MCP cuando Claude Code lo pida; verifica con /mcp. Herramientas tzolk_*.

Slash commands

| Comando | Qué hace | |---|---| | /tzolk-retomar <proyecto> | Recupera memoria + tablero + notas para retomar dónde se quedó | | /tzolk-board <proyecto> | Muestra el tablero Kanban completo | | /tzolk-progress <proyecto> | Reporte de avance por fase + bloqueadas + actividad | | /tzolk-cerrar <proyecto> | Guarda un journal de la sesión (memoria de "lo de hoy") |

Dashboard web

Interfaz React (Vite + Tailwind + Motion) con CRUD completo, drag-and-drop y actualización en vivo (LISTEN/NOTIFY de Postgres → WebSocket). Tablero 2D con swimlanes por fase × columnas por estado, detalle de tarea, panel de actividad, login web y vinculación OAuth del agente.

docker compose up -d        # Postgres + dashboard
# o local:
npm run build && npm run build:web && tzolk web   # http://localhost:4317

Herramientas MCP

Lectura: tzolk_projects, tzolk_board, tzolk_task, tzolk_area, tzolk_progress, tzolk_memory, tzolk_notes Escritura: tzolk_new_project, tzolk_new_task, tzolk_move, tzolk_edit, tzolk_subtask_add, tzolk_subtask_check, tzolk_note, tzolk_new_area

Estructura

.
├── schema.sql          # esquema PostgreSQL (tablero 2D)
├── src/
│   ├── db.ts           # pool pg + esquema idempotente + LISTEN/NOTIFY
│   ├── core.ts         # action model (operaciones tipadas + event log)
│   ├── auth.ts         # usuarios (humanos) + API keys + OAuth device flow
│   ├── render.ts       # proyecciones Markdown
│   ├── cli.ts          # CLI tzolk (superficie agent-native)
│   ├── web.ts          # API JSON + SPA + WebSocket + auth
│   └── mcp.ts          # servidor MCP (tzolk_*)
├── web/                # dashboard React (Vite)
├── landing/            # landing + guía de instalación (estático)
├── .claude/
│   ├── skills/tzolk/SKILL.md
│   └── commands/tzolk-*.md
├── .mcp.json           # registro del MCP para Claude Code
└── DESIGN.md

Licencia

MIT.