ventrox
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ventrox show me open vents grouped by similarity and ranked by minutes lost"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.gitOr clone and install from the checkout:
git clone https://github.com/Vetrox/ventrox && cd ventrox && uv tool install .Then run setup:
ventrox setupSetup 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.
Related MCP server: todox MCP Server
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) claudeThe token is single-use and valid for 10 minutes. The session then holds the reviewer tools. Call them in this order:
ventrox_reclustergroups open vents by vocabulary overlap.ventrox_clusterslists the groups ranked by open count, then minutes lost.ventrox_resolve_clustermarks a groupresolvedorwontfix.
Uninstall
ventrox setup --remove
uv tool uninstall ventrox
rm -r ~/.local/share/ventrox # deletes all ventsTools
Tool | Mode | Arguments | Returns |
| reporter |
|
|
| reporter |
|
|
| reviewer |
| the vent, or |
| reviewer |
|
|
| reviewer | none |
|
| reviewer | none |
|
| reviewer |
|
|
| reviewer |
|
|
Text fields hold 1 to 4000 characters. minutes_lost ranges from 0 to 1440.
Environment variables
Variable | Purpose | Default |
| Data directory | unset |
| Session ID | generated per process |
| Grant token for a reviewer session; single-use, valid 10 minutes | unset |
| Path to a file with project examples | unset |
| Vents the server accepts per session | 20 |
| 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 ventroxNon-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.
Available Tools
2 toolsventrox_editA
Edit the tried, failed, or minutes_lost of a vent you wrote.
Provide the vent ID. Validation rules match ventrox_vent. Returns ok (true or false). If the edit fails, we do not state the reason. Possible causes: wrong ID, wrong session, or validation error.
Inputs: id (required), tried, failed, minutes_lost.
ventrox_ventA
Record friction you hit today.
A vent describes what blocked you. Write what you tried, what failed, and how many minutes you lost. Do not write fixes, workarounds, or lessons. We do not read vents back to you.
Write one vent per turn. Write a vent only after you hit the same friction again. Friction repeats when the same thing fails two times or more, or when one thing costs more than 10 minutes.
Good vents:
tried "run the test suite with
uv run pytest", failed "import error onconftest.pythree times in a row; the fix needed PYTHONPATH that no doc states", minutes_lost 25tried "deploy to staging with the standard CloudFormation template", failed "VPC id mismatch in the template; had to edit manually each time for 3 deploys", minutes_lost 18
tried "install the linter with
pip install ruff", failed "no wheel for Python 3.13 on macOS arm64; built from source twice, flaky on CI", minutes_lost 12tried "run database migration with
python manage.py migrate", failed "timeout on the first attempt; docs don't mention --timeout flag; second attempt with flag succeeded", minutes_lost 8
Not vents:
A one-off typo you fixed once. That is not repeated friction.
"How do I make the tests faster?" That is a question, not friction.
"Next time use pytest-xdist for parallel tests". That is a lesson or a fix, not what blocked you.
"Finished the feature, took 3 hours". That is a task-progress note, not friction.
Inputs: tried (required), failed (required), minutes_lost (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
ventrox_vent is exclusively for recording a new friction event, while ventrox_edit explicitly modifies an existing vent's fields. There is no overlap or ambiguity between creating and editing.
Both tools share the ventrox_ prefix and use short action-style names, making the pattern predictable. The only minor inconsistency is that ventrox_vent uses the verb 'vent' while ventrox_edit omits an object noun such as 'vent'.
Two tools is slightly thin, but it matches the server's focused purpose of recording and correcting friction entries. Each tool is meaningful and there is no bloat.
The server covers creating and editing vents, which are the core operations for its purpose. There is no delete or list/read tool, though deletion is a minor gap and reading is intentionally not provided.
Maintenance
Related MCP Connectors
Jam recordings (video, console, network) as context and proof of work for your coding agent.
Error tracking for small teams and their coding agents.
Work journal for coding agents: worklogs, tasks, project state and costs across projects.
Shared team record of decisions, changes and handoffs that every coding agent reads and writes.
Related MCP Servers
- AlicenseCqualityBmaintenanceEnables coding agents to query, compare, and audit local profiler traces, benchmarks, memory captures, and execution evidence without uploading code or data, using CLI and MCP interfaces.11181 PyPI243MIT
- AlicenseAqualityBmaintenanceEnables agents to create and manage persistent task logs, decisions, dead ends, questions, and handoffs, with file staleness detection and activity reporting.232MIT
- AlicenseAqualityBmaintenanceEnables AI coding agents to retrieve relevant execution context before a task, compare candidate paths, log outcomes, and search past experiences stored locally in SQLite. It lets agents reuse what worked on similar tasks and get live alerts when a run stagnates or repeats failures.14211 PyPI4MIT
- AlicenseAqualityCmaintenanceEnables coding agents to maintain durable, private, local memory by storing and linking records across collections, with structured review, search, and audit history.23MIT