为什么值得关注

它填补了AI代理通常忽略的静默摩擦捕获空白，将其转化为改进仓库、工具和文档的可操作数据。

适合谁使用

AI代理开发者
仓库维护者
使用AI编码助手的团队
DevOps工程师

典型使用场景

在代理工作期间提交死胡同工具调用或失效链接
审查代理投诉记录以发现反复出现的问题
附加证据（失败命令、stderr）用于调试
集成到CI/CD中以跟踪代理报告的问题

项目优势

简单的CLI，采用代理优先合约（JSON输出、结构化错误）
并发安全且确定性，适合多代理可靠使用
永不重写历史，保留事件日志
支持团队模式（提交或私有），与git集成

使用前须知

尽力而为的数据清洗，不适用于高度敏感数据
依赖代理主动提交投诉（需要主动采用）
除列出外无内置分析或聚合功能

README 快速开始

papercuts

A tiny CLI that gives AI agents a complaint box.

Agents hit friction constantly — dead-end tool calls, broken links, missing helpers, footgun configs — and silently push through without telling anyone. The signal evaporates. papercuts gives an agent a one-line way to file the complaint at the moment it happens, and gives you (or another agent) a way to review the backlog and fix the actual problems in your repo, your tooling, your docs.

$ papercuts add "yarn web:test with a root-relative path finds no files; the workspace test cwd is apps/web" --tag tooling
{"ok":true,"data":{"changed":true,"record":{"kind":"cut","id":"pc_9f2c41d0a8b3","ts":"2026-07-09T21:14:03.412Z","agent":"claude-code","text":"yarn web:test with a root-relative path finds no files; the workspace test cwd is apps/web","tags":["tooling"],"severity":"minor",...}},"meta":{"contract":1,"file":"/repo/.papercuts.jsonl","agent_source":"detected"}}

The idea comes from a tool Steve Ruiz built for his own repos: once agents had a place to complain, they immediately surfaced real workflow defects — quoting bugs, wrong test working directories, YAML footguns — that they'd been eating silently for months.

Install

cargo install papercuts

How it works

Papercuts live in an append-only JSONL file — by default .papercuts.jsonl at your repo root, so every complaint shows up in git diff and travels with the repo. No server, no sync, no telemetry. The file is the product.

papercuts add "text"            # file a papercut (also: papercuts log, or pipe stdin to add -)
papercuts list                  # open papercuts, severity-first then newest, JSON envelope
papercuts list --format md      # human review digest
papercuts resolve pc_9f2c        # mark one fixed (unique ID prefix ok)
papercuts resolve pc_9f2c pc_a81e # resolve several atomically
papercuts add "tool failed" --cmd 'tool --flag' --exit 1 --stderr-file /tmp/stderr
papercuts add "bad response" --evidence 'request_id=abc123'
papercuts schema                # full machine contract — agents self-orient with this
papercuts doctor                # validate the log file

Agent-first contract: stdout is data only; one JSON envelope per command; structured errors on stderr with stable codes, documented exit codes, and a paste-ready suggested_fix. `papercut

项目描述

A tiny CLI that gives AI agents a complaint box — log the papercuts they hit during work

papercuts

为什么值得关注

适合谁使用

典型使用场景

项目优势

使用前须知

README 快速开始

papercuts

Install

How it works

项目描述

相关仓库与替代方案

tty7

reims-vgpu

memguard-rs