Ventrox

编码代理每天都会无数次撞上同一堵墙，却没有人看到。 Ventrox 为代理增加一个工具调用：它尝试了什么、什么失败了、损失了多少分钟。 代理无法回读 vents；服务器为每条 vent 盖上会话、项目、分支和时间的戳。 审查者运行 VENTROX_SECRET=$(ventrox grant) claude，然后按粗略相似度分组列出 vents，按数量和分钟数排序。 损失分钟数最多的那堵墙排在最前面。 几百行 Python，主目录中的一个 SQLite 文件，两条命令即可安装。 不会通过网络传输任何内容，也不会落入你的仓库。 聚类是对 n-gram 做 TF-IDF，会漏掉同义词；脱敏是一个正则列表，尽力而为。 限制：每个会话 20 条 vents，每 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。 它每轮只写一条 vent，并且只有在同样的摩擦重复出现后（两次失败或超过 10 分钟）才写。 它可以在同一会话中用 ventrox_edit 修正一条 vent。 服务器接受每个会话 20 条 vents，每 10 分钟 5 条。

审查者：用一次性令牌启动会话：

VENTROX_SECRET=$(ventrox grant) claude

该令牌是一次性的，有效期为 10 分钟。 会话随后持有审查者工具。按以下顺序调用它们：

1. ventrox_recluster 按词汇重叠对未关闭的 vents 分组。

2. ventrox_clusters 列出分组，按未关闭数量排序，然后是损失分钟数。

3. ventrox_resolve_cluster 将一组标记为 resolved 或 wontfix。

卸载

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

工具

文本字段长度为 1 到 4000 个字符。minutes_lost 的范围是 0 到 1440。

环境变量

数据位置

服务器按顺序选择 $VENTROX_HOME、$XDG_DATA_HOME/ventrox 和 ~/.local/share/ventrox 中的第一个。 所有 vents 都存放在该目录下的 vents.db 中。 该文件是纯 SQLite，没有加密；只有文件权限保护它。 当数据目录位于 git 工作树内时，服务器拒绝启动，并以退出码 2 退出。

技能

ventrox-report 告诉代理什么情况下一次摩擦算作一条 vent，以及三个字段必须包含什么。 ventrox-review 告诉审查者依次运行 recluster、clusters，然后 resolve。 ventrox setup 安装两者。

项目示例

在项目根目录放置一个 .ventrox.md 文件，以添加项目特定的优质 vent 示例。 将 VENTROX_EXAMPLES 设置为文件路径，以对所有项目添加示例。 服务器会将两者追加到 ventrox_vent 工具描述中。

开发

uv sync
uv run pytest
uv run ventrox

非目标

Ventrox 不同步到问题跟踪器。 它没有多用户模式。 它不记录工具调用轨迹，只记录代理写入的三个字段。 它不打开任何网络连接。