Ventrox

A coding agent hits the same wall many times a day, and nobody sees it. Ventrox adds one tool call to the agent: what it tried, what failed, minutes lost. The agent cannot read vents back; the server stamps each with session, project, branch, and time. A reviewer starts VENTROX_SECRET=$(ventrox grant) claude and lists vents grouped by rough similarity, ranked by count and minutes. The wall that cost the most minutes comes first. A few hundred lines of Python, one SQLite file in your home directory, two commands to install. Nothing goes over the network, and nothing lands in your repo. Clustering is TF-IDF on n-grams and misses synonyms; redaction is a regex list, best effort. Limits: 20 vents per session, 5 per 10 minutes. The idea comes from Lovable's vent tool and vent-widget.

Install

Install Ventrox as a global tool:

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

Or clone and install from the checkout:

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

Then run setup:

ventrox setup

Setup copies the ventrox-report and ventrox-review skills into ~/.claude/skills/. It then registers the MCP server with claude mcp add --scope user ventrox -- ventrox.

Use

Reporter: the agent calls ventrox_vent with tried, failed, and minutes_lost. It writes one vent per turn, and only after the same friction repeats (two failures or more than 10 minutes). It corrects a vent in the same session with ventrox_edit. The server accepts 20 vents per session and 5 vents per 10 minutes.

Reviewer: start a session with a single-use token:

VENTROX_SECRET=$(ventrox grant) claude

The token is single-use and valid for 10 minutes. The session then holds the reviewer tools. Call them in this order:

1. ventrox_recluster groups open vents by vocabulary overlap.
2. ventrox_clusters lists the groups ranked by open count, then minutes lost.
3. ventrox_resolve_cluster marks a group resolved or wontfix.

Uninstall

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

Tools

Tool	Mode	Arguments	Returns
ventrox_vent	reporter	tried, failed, minutes_lost	id, or error
ventrox_edit	reporter	id, plus any of tried, failed, minutes_lost	ok
ventrox_get	reviewer	id	the vent, or error
ventrox_search	reviewer	query, status (optional), limit (default 20, max 100)	results, newest first
ventrox_clusters	reviewer	none	clusters ranked by open count, then minutes lost
ventrox_recluster	reviewer	none	clusters count, vents count
ventrox_resolve	reviewer	id, status (resolved or wontfix)	ok
ventrox_resolve_cluster	reviewer	cluster_id, status (resolved or wontfix)	ok, changed count

Text fields hold 1 to 4000 characters. minutes_lost ranges from 0 to 1440.

Environment variables

Variable	Purpose	Default
VENTROX_HOME	Data directory	unset
VENTROX_SESSION	Session ID	generated per process
VENTROX_SECRET	Grant token for a reviewer session; single-use, valid 10 minutes	unset
VENTROX_EXAMPLES	Path to a file with project examples	unset
VENTROX_MAX_PER_SESSION	Vents the server accepts per session	20
VENTROX_MAX_PER_10MIN	Vents the server accepts per 10 minutes	5

Data location

The server picks the first of $VENTROX_HOME, $XDG_DATA_HOME/ventrox, and ~/.local/share/ventrox. All vents live in vents.db in that directory. The file is plain SQLite with no encryption; only file permissions protect it. The server refuses to start when the data directory is inside a git worktree, and exits with code 2.

Skills

ventrox-report tells the agent when a friction counts as a vent and what the three fields must contain. ventrox-review tells a reviewer to run recluster, clusters, then resolve. ventrox setup installs both.

Project examples

Put a .ventrox.md file at the project root to add project-specific examples of good vents. Set VENTROX_EXAMPLES to a file path to add examples for all projects. The server appends both to the ventrox_vent tool description.

Develop

uv sync
uv run pytest
uv run ventrox

Non-goals

Ventrox does not sync to an issue tracker. It has no multi-user mode. It records no tool-call traces, only the three fields the agent writes. It opens no network connection.