humanize (hmz)

¿Qué hace humanize (hmz)?

humanize (hmz, https://github.com/humanfia/humanize, docs https://docs.humanfia.ai/humanize/) ejecuta CLIs de agentes de código (claude, codex, agy, …) dentro de flujos: bucles que deciden quién trabaja, quién revisa y cuándo se detiene la ejecución. Es una herramienta uv de PyPI (uv tool install hmz, ~/.local/bin/hmz); hmz update la actualiza. hmz sin argumentos abre una TUI para el directorio actual, hmz exec ejecuta un flujo sin interfaz, hmz web sirve todas las ejecuciones de cada espacio de trabajo en un navegador. Escrito contra la versión 0.2.2; esta alfa cambia a menudo, así que confía en hmz exec --help sobre este archivo.

Valores predeterminados del usuario (edítalos para tu configuración)

Configuración	Predeterminado
Flujo	rlar: Claude implementa, Codex revisa
Actor	claude/claude-opus-5-5:high
Revisor	codex/gpt-6.1-sol:high (a veces :ultra)
Presupuesto	budget.duration=1d, sin límite de costo ni tokens

Úsalos a menos que el usuario indique lo contrario, o que el espacio de trabajo tenga valores guardados (más abajo). No preguntes sobre el presupuesto.

hmz exec -f rlar \
  -a actor=claude/claude-opus-5-5:high \
  -a reviewer=codex/gpt-6.1-sol:high \
  -p budget.duration=1d \
  --json "$(cat "$TASK")" > "$LOG" 2>&1

Flujo de trabajo

1. Pre-vuelo.
   • Busca el directorio en ~/.hmz/settings.yaml bajo workspaces:. Si tiene una entrada, prefiere su flujo, agentes, entornos y presupuesto sobre los valores predeterminados.
   • Verifica que cada modelo y esfuerzo que pases exista en ~/.hmz/models/<cli>.json. hmz no valida las especificaciones de antemano: una mala falla solo en el primer turno que la use, así que un modelo de revisor incorrecto en rlar aparece después de todo el primer turno del actor.
   • Revisa git status. Los agentes de hmz se ejecutan con aprobaciones omitidas. Si el repositorio tiene trabajo sin confirmar que no creaste, o puede cambiar sistemas en vivo (infraestructura, scripts de despliegue, credenciales), indícalo y sugiere un git worktree antes de comenzar.
2. Escribe el archivo de tarea (próxima sección) en el bloc de notas y muéstralo al usuario si la tarea no es trivial o se dio de forma vaga.
3. Ejecuta en segundo plano con run_in_background y --json redirigido a un registro en el bloc de notas. Las ejecuciones duran horas o días. Reporta el comando, el archivo de tarea, la ruta del registro y cómo monitorearlo: hmz en ese directorio abre la TUI en la ejecución, o hmz web.
4. Lee el resultado (ver Resultados), luego revisa el diff del repositorio y ejecuta las comprobaciones del proyecto tú mismo antes de darlo por terminado. El "hecho" del revisor es evidencia, no prueba.
5. Detención. Detén la tarea en segundo plano que iniciaste. Nunca uses pkill hmz a secas, ya que el usuario suele tener otras ejecuciones en curso. Inspecciona pgrep -af hmz y detén solo tu PID.
6. Reanudación. --resume con el mismo -f en el mismo directorio (limitaciones a continuación).

Escribir la tarea

El actor solo ve la tarea, y en rlar el revisor juzga el repositorio contra ella, así que las tareas vagas generan rondas de revisión interminables o un "hecho" prematuro. Incluye:

• Objetivo: el resultado en una o dos oraciones, no los pasos.
• Leer primero: los archivos, especificaciones o documentos que definen el trabajo (por ejemplo, un cambio en OpenSpec, un issue, una nota de diseño), para que el agente no los redescubra.
• Hecho cuando: criterios de aceptación concretos que el revisor pueda comprobar: comandos que deben pasar, comportamiento que debe cumplirse, números a alcanzar.
• Fuera del alcance: qué no tocar, y cualquier acción que necesite a un humano (despliegues, subidas, eliminaciones, servicios de pago, cambios en sistemas en vivo).
• Convenciones: política de commits (confirmar o dejar sin confirmar, estilo del mensaje), dónde poner registros y artefactos.

Escríbelo en un archivo y pasa "$(cat "$TASK")", o dile al agente que lea el archivo primero. Una tarea que comience con - va después de --.

Forma del comando

hmz exec -f FLUJO -a ROL=ESPEC[,...] [-e ROL=ESPEC[,...]] -p CLAVE=VALOR[,...] [opcs] tarea

• -f: un nombre de flujo. Los integrados son simples (rlar); los del usuario son @usuario/NOMBRE (de ~/.hmz/flows/NOMBRE/) y los del proyecto @local/NOMBRE. También una ruta que comienza con ., / o ~, git+URL#subdir, o NOMBRE:OTRO para otro flujo en el mismo módulo. Un nombre simple se resuelve primero al más cercano, así que un flujo de usuario puede sobrescribir uno integrado.
• -a: ROL=CLI[@PROVEEDOR]/MODELO[:ESFUERZO], uno por rol de agente que define el flujo. Repite la bandera o sepáralos con comas.
• -e: ROL=BACKEND[@PROVEEDOR][/DIRECTORIO_TRABAJO] para flujos con roles de entorno. PROVEEDOR es un runtime guardado en la configuración o, solo para ssh, un host entre corchetes: caja=ssh@[usuario@host:22]/ruta/abs. Sin proveedor, es esta máquina.
• -p: parámetros del flujo, interpretados como el tipo del parámetro o como JSON. Todos los flujos excepto chat necesitan un presupuesto: budget.duration (1d, 2h30m, PT1H), budget.cost (USD), budget.output_tokens. budget.graceful=true permite que el último turno termine (o budget.graceful.<límite> para un límite específico).
• --json: eventos NDJSON a stdout. Úsalo cuando necesites leer el resultado.
• --resume: retoma la ejecución más reciente de este flujo aquí, si el flujo se puede reanudar (ralph_loop y continue_loop no pueden). Reanudar rlar entrega al actor recién iniciado solo la última revisión, no la sesión anterior del actor.
• --backup NOMBRE: respalda la épica en un destino de respaldo guardado en la configuración (none lo desactiva).
• --profile-flow / --profile-environment: agrega muestreo al seguimiento de la ejecución. Úsalos solo al diagnosticar una ejecución lenta.
• Un turno fallido termina la ejecución en todos los flujos de bucle integrados, así que no cuentes con que el bucle lo reintente.

Elegir un flujo

Flujo	Roles	Úsalo cuando
rlar	actor, reviewer	Predeterminado. Trabajo que necesita una verificación separada. El actor trabaja en una sesión, un revisor nuevo verifica el repositorio contra las afirmaciones del actor en cada ronda, y termina cuando el revisor dice que está hecho.
chat	assistant	Un agente, una sola intervención, sin bucle ni presupuesto. Preguntas y ediciones pequeñas.
goal	worker	Una sesión de /goal <tarea> que se ejecuta hasta que el modelo dice que se cumplió. Trabajo autoverificado con criterios claros.
continue_loop	agent	Envía la tarea una vez, luego sigue enviando "continúa". Trabajos largos en un solo contexto.
ralph_loop	agent	Sesión nueva cada ronda con la misma tarea. El progreso vive en el repositorio, no en el contexto.
stateful_ralph	agent	Una sesión, la tarea se reenvía cada ronda.
flame_chase	first_chaser, second_chaser	Dos agentes se turnan en sesiones nuevas.

Los flujos de usuario viven en ~/.hmz/flows/<nombre>/__init__.py. Enuméralos con ls ~/.hmz/flows/ y lee el docstring para roles y parámetros antes de usar uno. Para obtener el contrato completo de cualquier flujo: ~/.local/share/uv/tools/hmz/bin/python -c "import hmz.flows.builtin.rlar as m; print(m.__doc__)".

Resultados

• Cada ejecución es una épica en ~/.hmz/epics/<directorio-actual-con-barras-como-guiones>/<marca-de-tiempo>/, y epic.jsonl contiene los eventos de resumen: began (flujo, tarea), opened (cada sesión de agente), usage (costo, tokens_salida, segundos) y ended con un campo how: done cuando se cumplió la condición de parada del flujo, stopped en caso contrario (pueden existir otros valores).
• El registro --json tiene el flujo completo de eventos, incluidos errores como HarnessUnrecoverable cuando un turno falla. Lee su final para saber por qué terminó la ejecución.
• Reporta el resultado, el costo y la duración de usage, y tu propia verificación del diff.

Notas de configuración

• Los runtimes guardados indican dónde se ejecuta el CLI del agente con harness: (affinity: es el nombre antiguo y aún se lee). Un runtime en otra máquina sin harness configurado no recurre a ejecutar el CLI aquí, así que establece harness: local cuando el host remoto no tenga el CLI.
• Las preguntas secundarias /btw a la épica solo funcionan una vez que la configuración btw nombra un agente (Configuración › General).
• Las páginas de ejecución de hmz web están bajo #/epics/.