Understanding CULP

CULP changes two ordinary things: how source files get written, and where Glob and Grep answers come from. Both changes are invisible until something goes wrong, and both produce messages that are easy to misread.

A write either succeeds as real source, or does not happen

When Claude writes compact source, the plugin's PreToolUse hook decodes it before the mutation runs and hands the real source back as the tool's arguments. So a file never contains compact syntax, not even briefly, and not to any linter or language server that reads it a moment later.

The consequence that matters: a decode that fails blocks the write. Nothing lands on disk, and the tool call comes back with a named reason.

The four messages

A receipt. CULP applied python->thing.py (18 lines, syntax valid, id 9f6e8007). The write happened and the file holds decoded source. The receipt never contains the generated code, so Claude has not seen the file it just wrote: it has to read it before editing it, whatever the tool result says about that not being necessary.

A refusal. CULP decode failed for thing.py: decode_error: .... The mutation was blocked and nothing was written. Either fix the compact expression or write ordinary source for that file.

A verification warning. CULP warning: thing.py still contains compact CULP source after this tool call. The decode was overridden by something else. In practice this means another plugin's PreToolUse hook answered last and its answer won, because updatedInput does not compose. Rewrite the file with ordinary source.

A search answer. A Glob or Grep result that arrives flagged as an error but reads like a normal answer. It is a normal answer. Blocking the native tool requires a deny decision, and Claude Code delivers every deny with an error flag, so the wording says in words that the search actually ran.

Ordinary source is never touched

Content that is not compact passes straight through and never goes near the network. Two separate gates decide that: one tuned for recall, which decides whether to call the decoder at all, and one tuned for precision, which decides whether a failure is allowed to block the write. A broken CULP credential therefore cannot stop you editing files normally.

When the plan or the credential is the problem

A session that starts on a free plan is told so, once, and the paid surfaces simply are not used. A session whose device credential is locally unusable is also told so, before the first mutation rather than after it, because a refused write costs a turn.

Run culp doctor for the diagnosis. It is the only command that makes a network call to answer, and an unreachable API is reported as unknown rather than as a failure.