← All posts

One paragraph in CLAUDE.md gives every Claude Code session a papercuts log

A retro of my Claude Code setup had to dig through 369 MB of session logs. Now each session writes down what slowed it, in one shared file.

A retro of my Claude Code setup had to dig through 369 MB of session logs to find what had been slowing sessions down. So I added this to the global ~/.claude/CLAUDE.md, which every session in every project reads:

### Papercuts

When you lose time to a tooling or environment problem (hook misfire, MCP error, wrong command, missing permission), append one line to ~/.claude/papercuts.md: `date · project · symptom · fix`. Read it first when tooling fails mysteriously. Project facts go to memory, not here.

A papercuts log is one shared file where each session writes down the tooling problem that cost it time, as one line: date, project, symptom, fix.

The first day’s lines, with the project name changed:

2026-11-10 · shop · cd-prefixed Bash blocked by bash-cd-guard · use absolute paths / git -C
2026-11-10 · shop · LSP findReferences empty under vendor/ · gitignored paths dropped; use Grep

The LSP line is the problem from the LSP-to-MCP post. The cd line is the problem a hook of its own went after; that hook now refuses instead of rewriting. The same afternoon a session in a different project added a line without being asked: its helper scripts in /tmp had been wiped between sessions, and the line says how to rebuild them.

  • Keep the last sentence. Without it the file fills with project gotchas that belong in that project’s memory, and nobody reads a long log.
  • It under-reports. The file had four lines after day one, while a scan of my older session logs counted over a hundred repeated hook rejections. A session writes down what cost it time, not what it has learned to step around, so treat the file as leads for the next retro and not as a count.

Written by Vishwas Bhatnagar

Technical Architect. Adobe Commerce, marketplaces and AI-assisted engineering.

More about me →

More