Ventrox

Un agente de codificación choca contra el mismo muro muchas veces al día, y nadie lo ve. Ventrox añade una llamada de herramienta al agente: qué intentó, qué falló, minutos perdidos. El agente no puede leer los vents de vuelta; el servidor sella cada uno con sesión, proyecto, rama y hora. Un revisor inicia VENTROX_SECRET=$(ventrox grant) claude y lista los vents agrupados por similitud aproximada, ordenados por recuento y minutos. El muro que costó más minutos aparece primero. Unas pocas cientos de líneas de Python, un archivo SQLite en tu directorio personal, dos comandos para instalar. Nada sale por la red, y nada acaba en tu repositorio. La agrupación es TF-IDF sobre n-gramas y se pierde los sinónimos; la redacción es una lista de expresiones regulares, con el mejor esfuerzo posible. Límites: 20 vents por sesión, 5 por cada 10 minutos. La idea proviene de la herramienta vent y vent-widget de Lovable.

Instalación

Instala Ventrox como herramienta global:

uv tool install git+https://github.com/Vetrox/ventrox.git

O clona e instala desde el checkout:

git clone https://github.com/Vetrox/ventrox && cd ventrox && uv tool install .

Después ejecuta la configuración:

ventrox setup

La configuración copia las habilidades ventrox-report y ventrox-review a ~/.claude/skills/. Después registra el servidor MCP con claude mcp add --scope user ventrox -- ventrox.

Related MCP server: mcp-chest-memory

Uso

Reportero: el agente llama a ventrox_vent con tried, failed y minutes_lost. Escribe un vent por turno, y solo después de que la misma fricción se repita (dos fallos o más de 10 minutos). Corrige un vent en la misma sesión con ventrox_edit. El servidor acepta 20 vents por sesión y 5 vents por cada 10 minutos.

Revisor: inicia una sesión con un token de un solo uso:

VENTROX_SECRET=$(ventrox grant) claude

El token es de un solo uso y válido durante 10 minutos. La sesión contiene entonces las herramientas de revisor. Llámalas en este orden:

1. ventrox_recluster agrupa los vents abiertos por solapamiento de vocabulario.

2. ventrox_clusters lista los grupos ordenados por recuento de abiertos y luego por minutos perdidos.

3. ventrox_resolve_cluster marca un grupo como resolved o wontfix.

Desinstalación

ventrox setup --remove
uv tool uninstall ventrox
rm -r ~/.local/share/ventrox   # deletes all vents

Herramientas

Los campos de texto admiten de 1 a 4000 caracteres. minutes_lost va de 0 a 1440.

Variables de entorno

Ubicación de los datos

El servidor elige la primera de $VENTROX_HOME, $XDG_DATA_HOME/ventrox y ~/.local/share/ventrox. Todos los vents viven en vents.db en ese directorio. El archivo es SQLite plano sin cifrado; solo los permisos de archivo lo protegen. El servidor se niega a arrancar cuando el directorio de datos está dentro de un árbol de trabajo de git, y sale con el código 2.

Habilidades

ventrox-report le dice al agente cuándo una fricción cuenta como vent y qué deben contener los tres campos. ventrox-review le dice a un revisor que ejecute recluster, clusters y luego resolve. ventrox setup instala ambas.

Ejemplos de proyecto

Coloca un archivo .ventrox.md en la raíz del proyecto para añadir ejemplos específicos del proyecto de buenos vents. Establece VENTROX_EXAMPLES a una ruta de archivo para añadir ejemplos para todos los proyectos. El servidor añade ambos a la descripción de la herramienta ventrox_vent.

Desarrollo

uv sync
uv run pytest
uv run ventrox

No objetivos

Ventrox no sincroniza con un rastreador de incidencias. No tiene modo multiusuario. No registra trazas de llamadas de herramientas, solo los tres campos que escribe el agente. No abre ninguna conexión de red.