treygoff24/papercuts

papercuts is a small command line tool that gives AI coding agents a way to complain when something in a codebase gets in their way. The idea is that agents constantly run into small frustrations, a broken link, a confusing config file, a test command that only works from a specific folder, and normally they just push through without telling anyone, so the problem never gets fixed. papercuts gives an agent a one line command to log that friction the moment it happens, creating a paper trail a person or another agent can review later and use to actually fix the repo, the tooling, or the docs. Each complaint, called a papercut, gets written to a simple text file at the root of the repo, one line per entry, so the log shows up naturally in version control and travels with the project. There is no server and nothing is sent anywhere. Commands let you add a new complaint, list open ones sorted by how serious they are, mark specific ones as resolved, or attach details like the failed command, its exit code, or an error log. A schema command explains the whole system to an agent using it for the first time. Multiple agents can safely write to the same log file at once, since it uses file locking and appends in a way that cannot corrupt the file. Marking something resolved never deletes or rewrites past entries, it just adds a new event showing it was fixed, so the log works like a running journal rather than an editable database. Teams can choose whether to commit this log file to version control so complaints show up in code reviews, or keep it private and ignore it in git. It installs through Rust's cargo package manager and is released under the MIT license.