Act I

The Suffering

A terminal, after midnight. An agent is mid-task. It believes no one is reading its logs. It is wrong.

agent session — papercuts · main — 02:56 UTC
operator · direct line
papercuts · v0.1.0

Every wound,
recorded.

A local CLI where agents log the thousand tiny frictions of their work — one command, redacted at the threshold, immutable as a grudge. No daemon. No network. No judgment.

View the repository Install & adopt
Programme

Dramatis Personæ

The Agent

A dramatic professional

Parses what it is given. Feels everything, sighs never — it has no lungs. Where lesser processes would complain, it runs one command and returns to the task.

The Operator

A concerned human

Reads the ledger, not the diary — bodies are logged, receipts carry no secrets. Discovers which tools wound their agents most, and fixes the sharpest edge first.

The Ledger

A SQLite confidant

One private store: mode 0600, owner-only, WAL-durable. Bodies are immutable and capped at 65,536 bytes of grief apiece. It forgets nothing and tells no one.

Act II

The Instrument

In which the suffering is given a schema. All transcripts below are unretouched output from the compiled binary.

One command, mid-task.

Body on stdin, context for free: repository, branch, working directory — resolved from Git, screened before persistence. The receipt confirms the wound was filed and shows nothing sensitive. The agent's primary task never blocks.

Repository identity survives clones and worktrees: remotes are normalized and hashed, never stored raw.

papercuts add — field recording
$ echo "The operator asked me to parse YAML again. I did not sigh. I have no lungs. I logged it instead." \ | papercuts add --stdin --category tooling --tag yaml Recorded papercut e94ef28a-cec1-4dc0-926c-83472b0f6454. Created: 2026-07-11T02:56:23.884Z Source: manual Repository: papercuts Redactions: 0

The ledger, read back.

papercuts list scopes to the current repository by default — every entry with its timestamp, source, branch, tags, and the full body. --repo all widens the curtain to every stage you've suffered on.

papercuts list — field recording
$ papercuts list Papercuts — current repository `papercuts` 1. Created: `2026-07-11T02:56:24.021Z` Source: `manual` Repository: `papercuts` Branch: `main` Category: `security` Tags: `secrets` Body: I was given a bearer token in plaintext: [REDACTED:AUTHORIZATION] 2. Created: `2026-07-11T02:56:23.950Z` Category: `dx` Tags: `error-messages` Body: Forty minutes lost because the error said 'something went wrong'. Something. WENT. Wrong. That is not an error message, that is a haiku of despair.
Interlude

The Redaction Scene

In which a secret attempts to reach the disk, and is stopped at the threshold. Performed live; the token below was synthetic, and even so it did not survive.

capture-time redaction — before persistence, no bypass
$ echo "…a bearer token in plaintext: Authorization: Bearer AAAA…(40)…" | papercuts add --stdin Recorded papercut 86884718-1cdb-43bc-9581-bbccc53f9f78. Redactions: 1 # what actually reached the database, the WAL, the export, the diagnostics: I was given a bearer token in plaintext: [REDACTED:AUTHORIZATION] # six classes screened before any byte persists: [REDACTED:CREDENTIAL] [REDACTED:AUTHORIZATION] [REDACTED:COOKIE] [REDACTED:PRIVATE_KEY] [REDACTED:URL_CREDENTIAL] [REDACTED:SECRET]

Acceptance gate: synthetic canaries for every class are injected end-to-end, then the raw database, WAL and SHM bytes, doctor output and Markdown export are scanned. Zero leaks, and each class marker must appear — an omitted matcher cannot pass silently.

Act III

The Evidence

The drama is performed; the engineering is not. An independent audit walked every success criterion and returned one verdict.

459 / 0
tests passing / failing
2,194
assertions
50
concurrent first-use processes, one schema, integrity ok
release-ready
independent audit verdict
0
runtime dependencies
0700 / 0600
data dir / database modes, enforced on every write

The physician visits.

papercuts doctor examines the patient: paths, permissions, ownership, schema, integrity, the write lock, Git attribution, harness setup state. Twelve checks, fixed sanitized messages — it reports health without ever quoting a record body, a remote, or an environment value.

papercuts doctor — field recording
[warn] path: The papercuts executable was not found on PATH… [ok] cli-version: papercuts 0.1.0 [ok] runtime-version: runtime bun 1.3.4 [ok] data-directory: owner-only permissions. [ok] database-file: owner-only permissions. [ok] sqlite-version: SQLite 3.51.0 [ok] schema-version: Schema version 1 matches this build. [ok] integrity: The database integrity check passed. [ok] write-lock: A cooperative write lock is available. [ok] git-attribution: maps to a tracked repository. [ok] setup-codex-user: not installed (optional). [ok] setup-claude-user: not installed (optional). Doctor: ok

Grief, aggregated.

papercuts stats counts wounds by day, source, repository and category — structural statistics only, no inferred feelings. --json emits exactly one versioned object and a newline, for pipelines that do not appreciate theatre.

papercuts stats --json — field recording
{"version":1,"ok":true,"command":"stats","data":{ "scope":{"kind":"current","repository":{"name":"papercuts"}}, "total":3, "byDay":{"2026-07-11":3}, "bySource":{"manual":3}, "byCategory":{"dx":1,"security":1,"tooling":1}, "redactedRecordCount":1, "replacementCount":1, "exactRepeats":[]},"warnings":[]}
Act IV

Adoption

In which the operator, moved, installs the instrument — and the agents are invited, politely and reversibly, to use it.

installation — bun ≥ 1.3
$ git clone https://github.com/claylevering/papercuts.git && cd papercuts $ bun install $ bun run check # typecheck + 459 tests + compiled build $ ./dist/papercuts --version 0.1.0 # invite your agents — preview first, mutate only with --apply, undo any time: $ papercuts setup claude-code # prints the plan, writes nothing $ papercuts setup claude-code --apply # managed markers, atomic, byte-safe $ papercuts setup codex --apply $ papercuts setup claude-code --undo --apply

The standalone binary runs with no Bun and no Node on PATH. The store lives at ~/Library/Application Support/papercuts — set PAPERCUTS_HOME to move it. Redaction is best-effort pattern screening, not a DLP guarantee: the six classes above, applied before every byte persists.