Ventrox

Ein Coding-Agent stößt mehrmals täglich auf dieselbe Wand, und niemand sieht es. Ventrox fügt dem Agenten einen Tool-Aufruf hinzu: was er versucht hat, was fehlschlug, verlorene Minuten. Der Agent kann Vents nicht zurücklesen; der Server stempelt jeden mit Sitzung, Projekt, Branch und Zeit. Ein Reviewer startet VENTROX_SECRET=$(ventrox grant) claude und listet Vents auf, gruppiert nach grober Ähnlichkeit, sortiert nach Anzahl und Minuten. Die Wand, die die meisten Minuten gekostet hat, steht zuerst. Ein paar hundert Zeilen Python, eine SQLite-Datei in Ihrem Home-Verzeichnis, zwei Befehle zur Installation. Nichts geht über das Netzwerk, und nichts landet in Ihrem Repository. Clustering ist TF-IDF auf n-Grammen und übersieht Synonyme; die Schwärzung ist eine Regex-Liste, Best Effort. Limits: 20 Vents pro Sitzung, 5 pro 10 Minuten. Die Idee stammt aus dem vent tool und vent-widget von Lovable.

Installation

Ventrox als globales Tool installieren:

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

Oder aus dem Checkout klonen und installieren:

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

Dann das Setup ausführen:

ventrox setup

Das Setup kopiert die Skills ventrox-report und ventrox-review nach ~/.claude/skills/. Anschließend registriert es den MCP-Server mit claude mcp add --scope user ventrox -- ventrox.

Related MCP server: mcp-chest-memory

Verwendung

Reporter: Der Agent ruft ventrox_vent mit tried, failed und minutes_lost auf. Er schreibt einen Vent pro Turn, und nur nachdem sich dieselbe Reibung wiederholt (zwei Fehlschläge oder mehr als 10 Minuten). Er korrigiert einen Vent in derselben Sitzung mit ventrox_edit. Der Server akzeptiert 20 Vents pro Sitzung und 5 Vents pro 10 Minuten.

Reviewer: Starten Sie eine Sitzung mit einem Einmal-Token:

VENTROX_SECRET=$(ventrox grant) claude

Das Token ist einmal verwendbar und 10 Minuten gültig. Die Sitzung enthält dann die Reviewer-Tools. Rufen Sie sie in dieser Reihenfolge auf:

1. ventrox_recluster gruppiert offene Vents nach Wortschatz-Überschneidung.

2. ventrox_clusters listet die Gruppen, sortiert nach Anzahl offener Vents, dann nach verlorenen Minuten.

3. ventrox_resolve_cluster markiert eine Gruppe als resolved oder wontfix.

Deinstallation

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

Tools

Textfelder enthalten 1 bis 4000 Zeichen. minutes_lost reicht von 0 bis 1440.

Umgebungsvariablen

Datenspeicherort

Der Server wählt den ersten der Pfade $VENTROX_HOME, $XDG_DATA_HOME/ventrox und ~/.local/share/ventrox. Alle Vents liegen in vents.db in diesem Verzeichnis. Die Datei ist reines SQLite ohne Verschlüsselung; nur Dateiberechtigungen schützen sie. Der Server weigert sich zu starten, wenn das Datenverzeichnis in einem git worktree liegt, und beendet sich mit Code 2.

Skills

ventrox-report sagt dem Agenten, wann eine Reibung als Vent zählt und was die drei Felder enthalten müssen. ventrox-review weist einen Reviewer an, recluster, clusters und dann resolve auszuführen. ventrox setup installiert beide.

Projektbeispiele

Legen Sie eine .ventrox.md-Datei im Projektstamm ab, um projektspezifische Beispiele für gute Vents hinzuzufügen. Setzen Sie VENTROX_EXAMPLES auf einen Dateipfad, um Beispiele für alle Projekte hinzuzufügen. Der Server hängt beide an die Tool-Beschreibung von ventrox_vent an.

Entwickeln

uv sync
uv run pytest
uv run ventrox

Nicht-Ziele

Ventrox synchronisiert nicht mit einem Issue-Tracker. Es hat keinen Mehrbenutzermodus. Es zeichnet keine Tool-Aufruf-Traces auf, nur die drei Felder, die der Agent schreibt. Es öffnet keine Netzwerkverbindung.