Persistencia simple: Archivos Markdown y YAML legibles
Sin dependencias cloud: Todo funciona offline
Kanban liviano: TASKS.md con estados (Inbox, Next, Active, Blocked, Waiting, Done)
Bitácora por sesiones: LOG.md y archivos de sesión detallados
Changelog: Registro de cambios relevantes
CLI intuitiva: Comandos para iniciar, pausar y documentar trabajo

Stack

Python 3.11+
Typer - CLI
PyYAML - Metadatos
Jinja2 - Plantillas
Pydantic - Modelos

Instalación

Requisitos Previos

Python 3.11 o superior
pip (gestor de paquetes Python)

Método 1: Instalación con pip

# Clonar el repositorio
git clone <url-del-repositorio>
cd tracker

# Instalar en modo desarrollo
pip install -e .

# Verificar instalación
tracker --help

Método 2: Usando uv (recomendado)

# Instalar con uv
uv pip install -e .

# O desde el código fuente
uv pip install -e .

Verificar Instalación

tracker --help

Deberías ver la lista de comandos disponibles.

Desinstalación

pip uninstall tracker

Comandos

Comando	Descripción
`tracker init-project <slug>`	Crear nuevo proyecto
`tracker list`	Listar todos los proyectos
`tracker show <slug>`	Ver detalles de un proyecto
`tracker start <slug>`	Iniciar sesión de trabajo
`tracker note <text>`	Agregar nota a la sesión activa
`tracker stop <slug>`	Finalizar sesión y generar resumen
`tracker change <slug>`	Agregar entrada al changelog
`tracker next <slug>`	Sugerir próximos pasos
`tracker review`	Vista general de todos los proyectos

Estructura de un Proyecto

projects/<slug>/
├── README.md           # Documentación principal
├── LOG.md              # Bitácora de sesiones (append-only)
├── CHANGELOG.md        # Registro de cambios
├── TASKS.md            # Kanban liviano
├── sessions/           # Sesiones detalladas
├── docs/               # Documentación técnica
├── assets/             # Recursos
└── meta/
    └── project.yaml    # Metadatos

Flujo de Uso

# 1. Crear proyecto
tracker init-project mi-proyecto --name "Mi Proyecto" --type code

# 2. Iniciar sesión
tracker start mi-proyecto --objective "Implementar feature X"

# 3. Agregar notas durante el trabajo
tracker note "Implementé la función base" --type work
tracker note "Decidí usar PostgreSQL en vez de SQLite" --type decision

# 4. Finalizar sesión
tracker stop mi-proyecto

# 5. Ver estado
tracker show mi-proyecto
tracker list

Tipos de Nota

work - Trabajo realizado
change - Cambio realizado
blocker - Bloqueo encontrado
decision - Decisión tomada
idea - Idea o pensamiento
reference - Referencia o link

Estados de Proyecto

inbox - Recibido/revisar
next - Próximo a trabajar
active - En desarrollo activo
blocked - Bloqueado
waiting - En espera
done - Completado
archived - Archivado

Tipos de Proyecto

code - Desarrollo de software
homelab - Infraestructura personal
automation - Automatización
agent - Agentes/IA
research - Investigación
misc - Misceláneo

Proyecto Demo

Ver examples/demo-project/ para un proyecto de ejemplo completo.

Tests

pytest tests/ -v

Desarrollo

# Estructura del paquete
tracker/
├── cli/        # Comandos CLI
├── models/     # Modelos de datos
├── services/   # Lógica de negocio
├── storage/    # Persistencia archivos
├── utils/      # Utilidades
└── templates/  # Plantillas

Licencia

MIT