Ventrox

Кодинг-агент много раз в день упирается в одну и ту же стену, и никто этого не видит. Ventrox добавляет агенту один вызов инструмента: что он пробовал, что не сработало, сколько минут потеряно. Агент не может читать венты обратно; сервер помечает каждый из них сессией, проектом, веткой и временем. Ревьюер запускает VENTROX_SECRET=$(ventrox grant) claude и получает список вентов, сгруппированных по приблизительному сходству, отсортированных по количеству и минутам. Стена, стоившая больше всего минут, идёт первой. Несколько сотен строк Python, один файл SQLite в вашем домашнем каталоге, две команды для установки. Ничего не уходит по сети, и ничего не попадает в ваш репозиторий. Кластеризация — это TF-IDF на n-граммах, и она не видит синонимов; редактирование — это список регулярных выражений, best effort. Лимиты: 20 вентов на сессию, 5 за 10 минут. Идея взята из vent tool и vent-widget от Lovable.

Установка

Установите Ventrox как глобальный инструмент:

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

Или склонируйте и установите из клонированного репозитория:

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

Затем запустите настройку:

ventrox setup

Настройка копирует навыки ventrox-report и ventrox-review в ~/.claude/skills/. Затем она регистрирует MCP-сервер командой claude mcp add --scope user ventrox -- ventrox.

Related MCP server: mcp-chest-memory

Использование

Репортёр: агент вызывает ventrox_vent с аргументами tried, failed и minutes_lost. Он пишет один вент за ход, и только после того, как одно и то же трение повторяется (два сбоя или более 10 минут). Он исправляет вент в той же сессии с помощью ventrox_edit. Сервер принимает 20 вентов на сессию и 5 вентов за 10 минут.

Ревьюер: запустите сессию с одноразовым токеном:

VENTROX_SECRET=$(ventrox grant) claude

Токен одноразовый и действует 10 минут. Затем в сессии доступны инструменты ревьюера. Вызывайте их в таком порядке:

1. ventrox_recluster группирует открытые венты по пересечению словаря.

2. ventrox_clusters выводит группы, отсортированные по количеству открытых, затем по потерянным минутам.

3. ventrox_resolve_cluster помечает группу как resolved или wontfix.

Удаление

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

Инструменты

Текстовые поля содержат от 1 до 4000 символов. minutes_lost принимает значения от 0 до 1440.

Переменные окружения

Расположение данных

Сервер выбирает первый из $VENTROX_HOME, $XDG_DATA_HOME/ventrox и ~/.local/share/ventrox. Все венты хранятся в vents.db в этом каталоге. Файл — это обычный SQLite без шифрования; его защищают только права доступа к файлу. Сервер отказывается запускаться, если каталог данных находится внутри git-worktree, и завершается с кодом 2.

Навыки

ventrox-report объясняет агенту, когда трение считается вентом и что должны содержать три поля. ventrox-review говорит ревьюеру запустить recluster, затем clusters, затем resolve. ventrox setup устанавливает оба.

Примеры проектов

Поместите файл .ventrox.md в корень проекта, чтобы добавить примеры хороших вентов для конкретного проекта. Задайте VENTROX_EXAMPLES как путь к файлу, чтобы добавить примеры для всех проектов. Сервер добавляет оба к описанию инструмента ventrox_vent.

Разработка

uv sync
uv run pytest
uv run ventrox

Не-цели

Ventrox не синхронизируется с трекером задач. У него нет многопользовательского режима. Он не записывает трассировки вызовов инструментов, только три поля, которые пишет агент. Он не открывает сетевых соединений.