pi-papercuts

Agent complaint box for Pi/OMP: file friction into an append-only .papercuts.jsonl, then keep working.

Packages

Package details

extension

Install pi-papercuts from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-papercuts
Package
pi-papercuts
Version
0.3.3
Published
Sep 4, 2026
Downloads
442/mo · 54/wk
Author
adityavg13
License
MIT
Types
extension
Size
47.7 KB
Dependencies
0 dependencies · 3 peers
Pi manifest JSON
{
  "extensions": [
    "./index.js"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-papercuts

npm license node pi-package

Agent files one-line friction notes into .papercuts.jsonl and keeps working. Review the backlog later.

Port of treygoff24/papercuts (MIT) for Pi and OMP. Pure Node · Node 22+.

pi install npm:pi-papercuts
omp install npm:pi-papercuts

Use

papercuts({ action: "add", text: "what broke + what would have prevented it", tags: ["tooling"], severity: "major" })
papercuts({ action: "list" })
papercuts({ action: "list", format: "md" })
papercuts({ action: "resolve", ids: ["pc_9f2c"], note: "fixed" })
papercuts({ action: "doctor" })
papercuts({ action: "schema" })
papercuts({ action: "prune" })
Action What it does
add File a cut (text required). Optional tags, severity. Evidence is free-note or cmd/exit/stderr, not both. Alias log → add.
list Open cuts by default. Filters: status, agent, tag, severity, limit, format (json | md).
resolve Mark ids resolved (pc_ + ≥4 hex). Append-only.
prune Archive resolved cuts; keep the working log lean.
doctor Validate the log.
schema Machine contract for agents.

Severity: minor (default), major, blocker. Ids are content-addressed; duplicate adds are no-ops.

Interactive hosts show a compact themed call/result row — expand for full text, tags, and log path.

Storage

  1. file param
  2. PAPERCUTS_FILE
  3. nearest .git → <root>/.papercuts.jsonl
  4. else ~/.papercuts/log.jsonl
echo .papercuts.jsonl >> .gitignore

Optional: PAPERCUTS_AGENT, PAPERCUTS_NOW (tests).

With pi-deferred-context-engine, pin papercuts if you want it always active.

Path / clone

pi install ./packages/pi-papercuts
omp install ./packages/pi-papercuts

Gotchas

  • Does not auto-detect failures — the agent must call it (habit / AGENTS.md).
  • Not a secret store. Size caps only; resolve does not erase cut text.
  • Outside git, log goes under home unless PAPERCUTS_FILE is set.
  • Log path must be a normal file (not a directory, FIFO, or device).

More: residual risks.

License

MIT · AdityaVG13/pi-stack