# 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:

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

Or clone and install from the checkout:

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

Then run setup:

```bash
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:

```bash
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

```bash
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

```bash
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.