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