Ventrox

코딩 에이전트는 하루에도 여러 번 같은 벽에 부딪히지만, 아무도 그 사실을 보지 못한다. Ventrox는 에이전트에 도구 호출 하나를 추가한다: 시도한 것, 실패한 것, 낭비된 시간. 에이전트는 벤트를 다시 읽을 수 없다; 서버는 각 벤트에 세션, 프로젝트, 브랜치, 시간을 기록한다. 리뷰어는 VENTROX_SECRET=$(ventrox grant) claude로 세션을 시작하고, 유사도 기준으로 그룹화된 벤트 목록을 개수와 시간 순으로 정렬해 확인한다. 가장 많은 시간을 낭비하게 한 벽이 먼저 나온다. 몇 백 줄의 Python, 홈 디렉터리의 SQLite 파일 하나, 설치 명령 두 개. 네트워크로 전송되는 것은 없고, 저장소에 남는 것도 없다. 클러스터링은 n-gram에 대한 TF-IDF이며 동의어는 놓친다; 편집(redaction)은 정규식 목록으로, 최선의 노력이다. 제한: 세션당 벤트 20개, 10분당 5개. 아이디어는 Lovable의 vent 도구와 vent-widget에서 나왔다.

설치

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/에 복사한다. 그런 다음 claude mcp add --scope user ventrox -- ventrox로 MCP 서버를 등록한다.

Related MCP server: mcp-chest-memory

사용

리포터: 에이전트는 tried, failed, minutes_lost와 함께 ventrox_vent를 호출한다. 턴당 벤트 하나를 작성하며, 동일한 마찰이 반복된 후에만(실패 2회 이상 또는 10분 초과) 작성한다. 같은 세션에서 ventrox_edit으로 벤트를 수정한다. 서버는 세션당 20개, 10분당 5개의 벤트를 허용한다.

리뷰어: 일회용 토큰으로 세션을 시작:

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

도구

텍스트 필드는 14000자. minutes_lost는 01440 범위.

환경 변수

데이터 위치

서버는 $VENTROX_HOME, $XDG_DATA_HOME/ventrox, ~/.local/share/ventrox 중 첫 번째를 선택한다. 모든 벤트는 해당 디렉터리의 vents.db에 저장된다. 파일은 암호화되지 않은 일반 SQLite이며, 파일 권한만이 보호한다. 데이터 디렉터리가 git 워크트리 안에 있으면 서버는 시작을 거부하고 코드 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는 이슈 트래커에 동기화하지 않는다. 다중 사용자 모드가 없다. 도구 호출 추적을 기록하지 않으며, 에이전트가 작성한 세 필드만 기록한다. 네트워크 연결을 열지 않는다.