Opus 5 is unreadable. Here's my fix (not another CLAUDE.md addition).

Opus 5 is unreadable, especially in its recaps of all the work it did, and it is quickly becoming one of the most hated models of all time. Most people suggest adding conciseness instructions to your system prompt or CLAUDE.md, but that only works for a little bit, then the model is back to being unreadable.

So don't put it in CLAUDE.md. Enforce conciseness just-in-time. Let me explain.

I created a stop hook which fires the moment Claude decides it's done.

It refuses the stop, then feeds a conciseness prompt just in time to the model.

Mine says: "Type a clean recap. Keep it short, light, and plain — a few sentences of what changed and what it means, not a report. Write for someone who has not read the code: no file paths, no function or variable names, no line numbers, no code blocks, and assume nothing about what they already know of the internals. Skip the caveats and next-steps unless something is genuinely broken or unfinished. If they want the detail, they will ask."

Two things that make it survivable:

Loop guard: I added logic to make sure the stop hook won't fire over and over and cause an infinite loop.

Gates: A recap on every turn is worse than no recap. Mine only fires if the model is Opus 5, the turn actually wrote code, and it ran at least 6 tool calls.

This is extremely cheap to run too (since you just pay for the input of your recap request message and the output of the condensed response).

The best part about this is that you can configure it however you like in your setup. Hooks are one of the most powerful yet underutilized features in Claude Code.

Get the full hook: https://github.com/rcolman6/clean-recap/