DEV Community: Marcin Dudek

Hooks That Won't Let the AI Shoot Me in the Foot

Marcin Dudek — Mon, 06 Jul 2026 10:06:43 +0000

Originally published on https://marcindudek.dev/blog/claude-code-guardrails-pretooluse/

TL;DR

A bash tool is a pair of scissors. The agent will run rm -rf in the wrong place, or pipe a script off the internet into your shell, if a plausible task points that way. It has no skin in the game.
PreToolUse fires after the agent picks a tool and before the tool runs. My script sees the command while it's still just a string.
The guardrails are deny-by-pattern: block the handful of shapes I never want unattended, wave everything else through. Default is allow.
The veto is exit 2. Whatever I print to stderr goes back to the agent as the reason, so it reroutes instead of getting stuck.
Pattern-matching catches the known-bad shapes; real isolation needs a sandbox. Every rule here is a scar from something that already broke once.

Giving an agent a bash tool is handing it a pair of scissors and saying "go, run". Most of the time it runs fine. Then one day it doesn't, because the model has no idea that rm -rf in the wrong directory ends your afternoon, or that piping a script straight off the internet into your shell is how you get owned. It'll do either one without blinking if a plausible task leads there. It isn't reckless. It just has nothing at stake and no memory of the last time something like this bit you.

This is part 2 of my series on Claude Code hooks. Part 1 was about context rot, the slow kind of damage where a session quietly degrades over an hour. This one is the fast kind: a single command that wrecks something in a second. The layer that catches it is PreToolUse.

What PreToolUse actually is

PreToolUse runs in the gap between the agent deciding to call a tool and the tool actually running. For a bash command, that gap is where my script gets to read the exact command while it's still just text. Claude Code passes it the tool name and the tool input on stdin:

{
  "tool_name": "Bash",
  "tool_input": { "command": "rm -rf /tmp/build" }
}

One job: decide whether this runs. The bluntest answer is the exit code. exit 2 kills the call, and whatever the hook writes to stderr is handed back to the agent as the reason it was blocked. That last part matters more than it sounds, and I'll come back to it.

# hook on PreToolUse
data = json.load(sys.stdin)
cmd  = data.get("tool_input", {}).get("command", "")

if RISKY_PATTERN.search(cmd):
    print("Blocked: use the safe wrapper instead", file=sys.stderr)
    sys.exit(2)   # exit 2 = veto; stderr is fed back to the agent

sys.exit(0)       # no objection; normal permission flow continues

A command from the agent hits the PreToolUse hook. If it matches a risky pattern it is denied with exit 2 and the reason is fed back to the agent, which reroutes. If it matches nothing, it runs.

Agent calls Bash
rm -rf /tmp/build

PreToolUse hook
risky pattern?

hit

miss

DENY · exit 2
stderr reason returns to the agent

ALLOW
command runs

agent reads the reason, reroutes

One command through a deny-hook: a match is vetoed with exit 2 and the reason is fed back so the agent reroutes; everything else just runs.

There's a structured form too, for when you want more than a yes or no. Print a permissionDecision of deny, allow, or ask, with a reason attached:

print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "deny",
        "permissionDecisionReason": "Use the password manager, not a plaintext key.",
    }
}))

For a plain block, exit 2 and one honest stderr line is the whole hook. I only reach for the JSON form when I want ask, so a borderline command bounces to me for a yes or no instead of getting a flat refusal.

Why deny-by-pattern

Every guard I run is a denylist, never an allowlist. Trying to enumerate every safe command is a game you lose. The set is effectively infinite, it changes daily, and you spend your life unblocking yourself. So I do the inverse. I write down the few shapes I never want running unattended, match against those, and let everything else through untouched. The default is yes; the hook only ever opens its mouth to say no.

What makes this work is an asymmetry in the cost of being wrong. When the hook blocks something it shouldn't have, the price is one retry and a mildly confused agent. When it misses something it should have caught, the price is a deleted directory, a leaked key, or a server I have to go hunting for. Those two mistakes are not the same size. A short denylist that errs in the cheap direction beats a long allowlist that errs in the expensive one, every time.

An allowlist of safe commands is infinite and you fight it daily. A denylist of dangerous shapes is short, specific, and grows only when something bites you. Be wrong in the direction that costs a retry, not the one that costs an afternoon.

Guard 1: secrets in plaintext

The first one watches for secrets heading into plaintext. The moment a command looks like it's about to bake an API key, a password, or a token straight into a file, the hook stops it and tells the agent to stash the value in a password manager and read it back at runtime instead.

This guard is boring, which is exactly the point. A key pasted into a tracked file is harmless right up until it gets committed, and then it lives in git history forever. You can rotate the key. You can't un-leak it. Blocking the write costs nothing. Scrubbing a secret out of history after the fact costs a bad afternoon and a quiet jolt of panic when you realise how long it was sitting there.

Guard 2: filesystem discipline

The next guard has nothing to do with danger, just mess. Agents scatter temp files everywhere: a throwaway script here, a screenshot there, a downloaded PDF dropped in whatever directory they happened to be standing in. Give that a week and you can't tell the junk from anything that matters.

So a hook quietly catches those temp writes and points them at one per-project scratch directory. The agent thinks it wrote to a temp path; it actually landed somewhere I can wipe in a single command. Small thing. It's the difference between tidying up and doing archaeology.

Guard 3: the risky shapes (every one is a scar)

The third group is the interesting one, because I didn't design it. Every rule in it is a scar, a command shape that once did something I never asked for:

Raw SSH straight to a box, when there's a safe wrapper that should be used instead, so a fat-fingered hostname can't fire a command at the wrong server.
Processes that open a listening port and never get cleaned up, quietly stacking into a little graveyard of orphaned servers humming in the background.
Writes that look like they're about to clobber something that matters, where the path or the redirect just smells wrong.

Each one started as "huh, that shouldn't have happened" and ended as a line in a deny-hook so it can't happen the same way twice. The list isn't finished and never will be. It covers the mistakes I've made so far, which is a smaller and more honest claim than calling it done.

Where this stops working

Worth being straight about the limits. Matching patterns on a command string only goes so far. An agent that genuinely wanted to get around a regex could reword its way past it, and a hook can't catch what it never sees. If I needed real isolation I'd run the whole thing in a container or a throwaway VM and stop trusting the host at all.

But that was never the threat I had. The thing I'm defending against is a helpful agent, moving fast, with no memory of my past mistakes. For that, a cheap layer that catches the known-bad shapes covers most of the risk for almost none of the effort. And it buys me something I didn't expect when I started: the rails are what let me hand over more rope. I'll leave a session grinding on a long task unattended precisely because I know the few things that would actually hurt are already blocked. The guardrails don't slow the agent down. They're what make it safe to let it go faster.

Copy the pattern, not my list

Don't copy my rules. Your disasters won't be mine. Copy the shape:

Read the JSON on stdin, pull out tool_input.command.
Match it against the one risky pattern this hook cares about.
On a hit, exit 2 with a stderr message that says what to do instead, not just "no".
Otherwise exit 0 and get out of the way.

Two things decide whether you keep a hook or rip it out in a week. The stderr message has to reroute the agent, not just stop it. "Blocked, use the safe wrapper instead" gets read and acted on; a bare "denied" just makes the agent try the identical thing again and burn a turn. And keep each hook small and single-purpose, one concern per file. A mega-hook stuffed with every pattern you've ever written is its own hazard, because the day it has a bug it fails closed for everything at once.

Series: Claude Code hooks (5 parts)

Context rot + handoff - how I stop sessions from rotting
Guardrails - hooks that won't let the AI shoot me in the foot (you're here)
Quality gates - forcing the agent to verify before it says "done"
The prompt layer - a local LLM that reads my prompt before it hits Claude
The ambient layer - the hooks you stop noticing

All five parts are now live.

Get what I write next in your inbox

Five posts on Claude Code hooks, now complete. Drop your email and I'll send whatever I write next. Just new posts, nothing else.

Email address

Takeaway

None of this came from a threat model. It accreted, one scar at a time, each small disaster turned into a rule so it can't land twice. That's the real reason it lives in a hook instead of my head: the hook remembers across every session, so I only have to learn each lesson once. Hand the agent the scissors. Just put a guard on the blade first.

The Hook That Won't Let the Agent Say "Done"

Marcin Dudek — Mon, 06 Jul 2026 10:06:42 +0000

Originally published on https://marcindudek.dev/blog/claude-code-quality-gates-stop-hook/

TL;DR

An AI agent says "done" the way it says everything else: confident, fluent, and often without having checked. The word is cheap to produce and expensive to trust.
A line in the prompt asking it to verify is a request. A hook on Stop is enforcement. The hook runs in the harness and the model gets no vote.
The Stop hook can't read the model's intent, so it reads evidence instead: it checks the session transcript, or a small proof file the agent has to write, before it's allowed to end its turn.
stop_hook_active is the escape hatch. Without it, a gate that can never be satisfied loops forever. The hook stands down after forcing one continuation.
A second gate on PostToolUse grades the code the agent just wrote and feeds the verdict back. That one only injects an opinion; the edit already ran. Only the Stop hook guards the exit.

"Done." "It works." "Perfect, all tests pass." Those are the most expensive words an AI agent will ever say to you, because most of the time it hasn't checked. It pattern-matched its way to a confident sentence and stopped. The code might be fine. It might also be broken in a way that costs you an hour to find, precisely because you trusted the word "done" and moved on to the next thing.

This is part 3 of my series on Claude Code hooks. Part 1 was about context rot, the slow decay of a session that's been running too long. Part 2 was guardrails, catching one dangerous command before it runs. This one is about the gap between an agent saying it finished and the work actually being finished. The hook that closes that gap fires on Stop.

A prompt asks. A hook enforces.

I used to handle this with a line in the system prompt. Something like "always run the tests before you report success, and if you can't test, say so." It helps. It's also the first thing to evaporate when the context gets long or the task gets hard. A prompt is a request. The model is free to forget it, reinterpret it, or quietly decide this particular case is the exception. Under pressure it usually does exactly that.

A hook works at a different layer. It runs in the harness, not inside the model, so the model doesn't get a vote. When the agent tries to end its turn, my code runs first and decides whether that's allowed. That's the whole reason this lives in a hook instead of a hopeful paragraph of good intentions.

What the Stop hook sees

The Stop hook fires the moment the agent decides it's done talking. Claude Code hands it a small JSON blob on stdin:

{
  "hook_event_name": "Stop",
  "transcript_path": "/path/to/session.jsonl",
  "stop_hook_active": false
}

Two fields carry the weight. transcript_path points at the full session log, so the hook can look back at what actually happened in the turn. stop_hook_active tells me whether I've already forced a continuation once. I'll come back to that one, because it's what keeps this whole thing from turning into an infinite loop.

The decision is top-level. To keep the agent working, the hook prints a block:

{
  "decision": "block",
  "reason": "No test run found this session. Run the suite and report the result before you stop."
}

This is one of the spots where it's easy to invent a field that doesn't exist. The Stop decision sits at the top level of the JSON. Other hooks tuck their output inside a hookSpecificOutput object; this one does not. That reason string goes straight back to the agent as its next instruction. If you'd rather not assemble JSON, exit 2 with a single line on stderr does the same job. Either way the session doesn't end. The agent reads the reason and keeps going.

How the hook knows the work was verified

The interesting question is how a shell script decides whether anything was actually checked. It can't see the model's intent. So it goes looking for evidence instead. Two mechanisms, and you only need one:

Scan the transcript. transcript_path is right there in the input. The hook reads back through the session for a tool call that ran the test suite, or the linter, or the build, and checks whether it passed. No such call anywhere in the turn, no exit.
Demand a marker. Simpler and more honest: the agent has to write a small proof file before it's allowed to stop. It writes down the command it ran and the result it got. The hook checks that the file exists and is fresh. If the agent never ran anything, there's nothing to write, and the gate stays shut.

I lean on the marker. Grepping a transcript for "did a test really pass here" gets fuzzy fast, and fuzzy is the enemy of a gate. A file that says "ran X, got Y" is a thing I can check in one line and trust.

The agent tries to stop. The Stop hook checks for proof of a test run. With no proof it blocks with decision block and the reason returns to the agent, which runs the suite and tries again. With proof present, the session ends.

Agent says done
"tests pass"

Stop hook
proof of a test?

none

found

BLOCK · keep going
reason returns to the agent

ALLOW
session ends

agent runs the suite, writes proof

The exit gate: the agent only gets to stop once there's proof a test actually ran. Otherwise the Stop hook hands back a reason and the session keeps going.

The infinite loop problem

Here's the failure mode that bites everyone who builds one of these. The agent says done. The hook blocks: no proof. The agent has no way to produce proof, because there are no tests, or the task genuinely had nothing to run. It says done again. The hook blocks again. You've built a machine that can never stop, burning tokens in a circle.

That's what stop_hook_active is for. The first time my hook blocks, the harness flips that flag on the next Stop. When I see it's already true, I know I forced a continuation once and the agent still came back empty-handed. So the hook stands down and lets the session end, usually after logging a quiet note that the gate was bypassed this time. A gate that can never be satisfied protects nothing and just hangs the session. The escape hatch has to be in the design from the first line. You learn that the hard way once, when your terminal locks up grinding out the same refusal over and over.

Any hook that blocks an exit needs an answer to "what if the block is impossible to clear?" Without one, the first un-runnable task turns your quality gate into an infinite loop. stop_hook_active is the harness handing you that answer for free.

Grading the code it just wrote

The Stop hook guards the exit. A second gate works further upstream, on PostToolUse, firing right after the agent edits a file. This one can't block, because the edit already happened by the time the hook runs, but it can talk back. After a write, the hook runs the changed file through a handful of cheap, mechanical checks: how deeply nested the functions are, whether there are bare magic numbers with no name, whether the type hints quietly disappeared, whether a 200-line function is doing six jobs while pretending to do one. Each principle gets a rough score.

Then it does the one thing that makes this worth running. It feeds the verdict back to the agent as additionalContext, parked right next to the tool result:

print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "PostToolUse",
        "additionalContext": "Quality check: nesting 4 deep in handle(); 2 unnamed constants. Tidy before moving on."
    }
}))

Note where additionalContext lives here: inside hookSpecificOutput. That's the opposite of the Stop hook's top-level decision, and mixing them up is the quickest way to write a hook that silently does nothing. The agent sees "nesting is four deep, the constant on line 12 has no name" while the change is still warm, and it tends to clean things up on the next pass without being asked. The same checks lean on old, boring ideas like keeping it simple, which a tired model forgets the second the task gets interesting.

Worth being precise about the limit. This gate has no veto. The file is already on disk by the time the hook runs. All it can do is hand back an opinion. But an opinion delivered at the right moment, before the agent has moved on, lands far better than a code review three days later when nobody remembers why the function looks like that.

Forcing the recon before the writing

The gates so far catch trouble after it exists. The cheapest bug is the one the agent never writes, and that means getting it to look before it leaps. A UserPromptSubmit hook fires when I send a message, before the model sees it, and can staple a short instruction onto the front of my prompt through additionalContext.

For anything that smells like an implementation task, it injects a tiny checklist: read the files you're about to change first, find the pattern that's already there and match it, state your plan in one line before you touch anything. It's the same advice I'd give a junior in their first week, except it arrives every single time instead of whenever I remember to say it. An agent that reads the surrounding code before writing produces code that looks like it belongs. One that skips that step writes a lonely island of a function in its own private style, and you pay for it at review.

Closing the loop on todos

The last gate is small and a little dumb and I'd never give it up. When the agent opens a todo list, three steps or five, it has a habit of doing the first two, declaring victory, and quietly abandoning the rest. So a hook watches for started-but-unclosed work and, on Stop, treats an open todo the same as a missing test. You said you'd do five things, four are done, you don't get to stop yet.

Half-finished is the worst state to leave a task in, because it wears the costume of finished. The code runs, the obvious path works, and the thing you actually asked for, the edge case buried in step five, is silently missing. A todo-enforcer turns "I'll get to it" into "you'll get to it now, before this session ends."

Where this stops working

None of this verifies that the code is correct. It verifies that the agent did the checking it claimed to do. A test suite that's all green and tests nothing will sail straight through. A marker file that says "ran the tests" when the tests are hollow gets believed all the same. These gates raise the floor. They make "done" mean "I at least ran something and it didn't blow up" instead of "I have a good feeling about this." They don't raise the ceiling. That part is still on me and on how good the tests are in the first place.

But the floor is where the cheap, embarrassing failures live. The ones where the agent confidently ships code that doesn't even import. Catching those automatically, on every single turn, is worth a small stack of hooks that each do one boring thing well.

Build your own gate

Don't copy my checklist. Your idea of "proof" won't be mine. Maybe it's a passing test, maybe a clean type-check, maybe a screenshot of the thing actually rendering. Copy the shape instead:

Read the JSON on stdin and pull out transcript_path and stop_hook_active.
Decide what counts as proof, then go looking for it. Scan the transcript for a check that passed, or require a fresh marker file the agent had to write before stopping.
No proof? Block. Print a top-level {"decision":"block","reason":"..."}, or exit 2 with one line on stderr. Make the reason say exactly what to run, so the agent acts instead of just retrying the same dead end.
Proof is there? exit 0 and let the turn end.
Always check stop_hook_active first. If it's already true, stand down and let the session close. That single line is what separates a quality gate from an infinite loop.

Five lines of logic, one boring job. The same skeleton, pointed at whatever "done" is supposed to mean on your project.

Series: Claude Code hooks (5 parts)

Context rot + handoff - how I stop sessions from rotting
Guardrails - hooks that won't let the AI shoot me in the foot
Quality gates - forcing the agent to verify before it says "done" (you're here)
The prompt layer - a local LLM that reads my prompt before it hits Claude
The ambient layer - the hooks you stop noticing

All five parts are now live.

Get what I write next in your inbox

Five posts on Claude Code hooks, now complete. Drop your email and I'll send whatever I write next. Just new posts, nothing else.

Email address

Takeaway

"Done" is a feeling the model has. It says nothing about whether the code actually works. A prompt asking it to verify is a request it's free to drop the instant the task gets hard. A hook that won't let the session end without proof isn't asking anything. That's the whole difference, and under pressure it's the only difference that holds.

A Local LLM Reads My Prompt Before Claude Does

Marcin Dudek — Thu, 02 Jul 2026 13:05:00 +0000

Originally published on https://marcindudek.dev/blog/claude-code-prompt-gate-local-llm/

TL;DR

The weak link in AI coding is usually the half-formed prompt I type at the end of a long day. The model can only work with what I hand it.
A hook on UserPromptSubmit fires the instant I hit enter, before Claude reads a single word. It hands short prompts to a small model running on my own machine, which answers one question: is this clear enough to act on?
It runs locally on purpose. UserPromptSubmit blocks the session for up to 30 seconds while it works, so a cloud round-trip on every short message would be unbearable. A small on-device model answers in about a second, costs nothing per call, and the prompt never leaves the laptop.
The gate flags, it does not block. A vague prompt gets a one-line note stapled alongside it through additionalContext; my words still reach Claude untouched. I would never let a vagueness score erase something I typed.
If the local model is slow or down, the hook exits with a non-blocking error and the prompt goes through ungated. I lose the check, never the message.

I sat down to write this post, the one about the hook that reads my prompts, and typed: "ok, time to write post #4 of the series about". Then I trailed off and hit enter anyway. Before Claude saw a single word, a small model running on my own laptop read that prompt and flagged it: vague, missing context, says nothing about which series or what the post should actually cover. It was right. I had run out of sentence at the end of a long day, and the cheapest model in my stack caught it before the expensive one burned a turn guessing what I meant.

This is part 4 of my series on Claude Code hooks. Part 1 was about context rot and the handoff that resets a session before it decays. Part 2 was guardrails that catch a dangerous command before it runs. Part 3 was quality gates that won't let the agent say "done" without proof. Those all sit downstream of the model. This one sits upstream of it, on the one part of the whole pipeline I am personally responsible for: the prompt.

The weak link is the thing I type

It's tempting to blame the model when a session goes sideways. Most of the time the model did exactly what I asked. The problem is that I asked badly. At 11pm I write three terse words, leave out the file, the constraint, and the goal, and then expect the agent to read my mind. It can't, so it guesses, and a confident guess off a thin prompt is how you get forty minutes of work pointed at the wrong target.

I tried fixing this with a line in the system prompt, the same way I fix everything first: "if a request is unclear, ask before you act." It helps a little. It's also the first instruction to evaporate the moment the model gets a whiff of a plausible interpretation. A prompt is a request the model is free to ignore. So I stopped asking the model to police my input and moved the check to a place the model doesn't control: the moment between hitting enter and the model reading anything.

A hook that runs before the model reads a word

The UserPromptSubmit hook fires when I submit a message and before the model sees it. Claude Code hands it a small JSON blob on stdin with the prompt right there in it:

{
  "hook_event_name": "UserPromptSubmit",
  "prompt": "ok, time to write post #4 of the series about",
  "cwd": "/path/to/project"
}

From here the hook has a choice. It can block the prompt outright, which erases it from context entirely, or it can let the prompt through and staple extra context onto it. For my own input I almost always want the second one. I don't want to stop myself from typing. I want the agent to know when my prompt is thin before it commits to it.

A small local model reads the prompt first

Here is the part people raise an eyebrow at. For short prompts, the ones under about a hundred characters, which are reliably the half-baked ones, the hook hands my text to a separate, much smaller language model. A quantized Qwen running entirely on the laptop through Apple's MLX. It gets one job: read the prompt and decide whether it's clear enough to act on. If it isn't, it writes a single line saying what's missing.

It has to run locally, and the reason is right there in the docs. UserPromptSubmit blocks model processing while the hook runs, so it ships with a 30-second timeout instead of the usual ten minutes. Now imagine putting a cloud API call in that path. Every short message I send would stall behind a network round-trip and a queue, and I would spend my day watching a spinner. A small model on-device answers in roughly a second, costs nothing per call, works on a plane, and the prompt never leaves my machine. The latency budget alone forces this layer to be local.

Flag, don't block

The mechanism is the same one I leaned on in part 3: additionalContext. On a clean exit, the hook prints a small JSON object and whatever sits in additionalContext rides into the conversation right alongside my prompt:

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Heads up: this prompt is short and light on specifics (no target, no goal). Confirm scope before you run."
  }
}

There is a more aggressive option, and I deliberately don't use it. Exiting with code 2 blocks the prompt and erases it from context completely. That's the right call for a genuinely dangerous prompt. It's the wrong call for a vague one, because a small model's opinion that my prompt "seems unclear" isn't worth deleting something I just typed. A false positive there would be infuriating: you write a message, the gate disagrees with its phrasing, and your words vanish. So the gate never blocks my input. It flags. Claude receives my three sleepy words and the note, reads both, and asks the clarifying question instead of charging off a cliff. Which, for the record, is exactly what happened with this post.

You submit a short prompt. A local model reads it before Claude does. If the prompt is clear it passes straight to Claude. If it is vague, the hook staples a one-line clarity note onto it as additionalContext, and Claude receives the prompt together with that note.

You hit enter
short prompt

Local model
clear enough?

vague

clear

Staple a clarity note
additionalContext

Claude reads it
your prompt + any note

joined to your prompt

The clarity gate: a vague prompt picks up a one-line note on the way through, a clear one passes straight to Claude. Either way your words reach the model untouched.

What else this prompt layer can do

Once you own that sliver of time between hitting enter and the model reading, flagging vague prompts is just the first thing you can do with it. A few others I run on the same input layer:

Keyword to skill. The hook scans the prompt for intent and, when it spots a clear match, pre-loads the right tool or skill so the agent shows up already holding what it needs instead of fumbling for it three messages in.
Context that arrives with the prompt. The relevant project facts and past decisions get pulled in and handed to the model along with my message, so the prompt reaches Claude already carrying the context I would otherwise have to retype for the hundredth time.
Trimming the empty stall. A small nudge so the agent acts on clear, unambiguous instructions instead of reflexively asking "should I go ahead and do the thing you just asked for?" Real decisions, the ones with a genuine tradeoff, still get a question, because I want to be asked about those. It is only the hollow permission-seeking on an obvious yes that gets trimmed.

A small local model is a cheap, private pre-processor for everything you type. It does not need to be smart. It needs to be fast, free, and right next to the keyboard. Most of its value is in the boring, repetitive judgment you would never bother a frontier model with.

Where this stops working

A four-billion-parameter model is no genius, and I don't pretend otherwise. Sometimes it flags a prompt that was perfectly clear, and sometimes it waves through one that was mud. That's survivable precisely because the note is advisory. Claude can read "this looks vague" and reasonably decide it isn't. Nothing was blocked, nothing was erased. A wrong call from the small model costs me a sentence of context. That's the whole price.

The failure mode I care more about is the gate getting in the way of the work. That's what the fail-open behavior is for. If the local model hangs or isn't running, the hook exits with a non-zero code that isn't 2, which Claude Code treats as a non-blocking error: it shows a small notice and processes my prompt normally. The gate going dark never costs me my message. It just quietly stops checking until I notice. For a tool that sits in front of every single thing I type, that asymmetry is the whole design: a missed flag is a shrug, a swallowed prompt would be a real problem.

And the honest limit: it can only read what I wrote. It catches the prompt that is vague on its face. It can't catch the prompt that is perfectly clear and perfectly wrong, or the crucial constraint I just forgot to type. Garbage in, garbage out still rules. This just catches the garbage I can see in my own sentence before I make the expensive model eat it.

Build your own

The skeleton is small. Point it at whatever "a good prompt" means for your work:

Hook on UserPromptSubmit. Read the JSON on stdin and pull out the prompt field.
Gate cheaply. Only bother for short or terse prompts, where the payoff is biggest. Let the long, detailed ones sail straight through untouched.
Ask a local model one question: is this clear enough to act on, and if not, what is missing? Keep it on-device so you stay inside the 30-second timeout and your text never leaves the machine.
Flag, don't block. Exit 0 and return the verdict in hookSpecificOutput.additionalContext. Never exit 2 on your own input, because a false positive that erases your prompt is far worse than a prompt that was a little vague.
Fail open. If the model is slow or down, let the prompt through. The gate is a helper standing next to the door. It was never the lock.

Series: Claude Code hooks (5 parts)

Context rot + handoff - how I stop sessions from rotting
Guardrails - hooks that won't let the AI shoot me in the foot
Quality gates - forcing the agent to verify before it says "done"
The prompt layer - a local LLM that reads my prompt before it hits Claude (you're here)
The ambient layer - the hooks you stop noticing

All five parts are now live.

Get what I write next in your inbox

Five posts on Claude Code hooks, now complete. Drop your email and I'll send whatever I write next. Just new posts, nothing else.

Email address

Takeaway

The model gets all the attention. The prompt gets almost none, and the prompt is the part I actually control. Putting a small, free, local model in front of the expensive one, to read what I typed before Claude does, turned out to be one of the cheapest upgrades I've made to this setup, and most days it earns its keep before I've finished my coffee. The post you just read exists because that gate stopped me from firing three sleepy words into a fresh session and calling it a brief.

The Hooks You Stop Noticing: Claude Code's Ambient Layer

Marcin Dudek — Thu, 02 Jul 2026 13:04:59 +0000

Originally published on https://marcindudek.dev/blog/claude-code-ambient-hooks-sessions/

TL;DR

The first four posts in this series were about hooks that stop things: block a command, hold an exit, flag a vague prompt. This last one is about hooks that do none of that. They run quietly and change how it feels to work with the agent.
TTS narration. A hook on Stop speaks the result of a finished turn, and one on Notification speaks up when a session needs me. I hear state changes instead of watching the terminal for them.
A status file. Each session writes its state on SessionStart and refreshes it every time it ends a turn. Glance at one small file and see what every parallel session is doing.
Sessions leaving notes. A shared queue file, checked at session start and between turns, lets parallel sessions hand each other messages without me playing courier.
Showing up equipped. SessionStart can pre-load a tool, re-scan skills with reloadSkills, and inject this project's conventions through additionalContext, so the agent starts the session already knowing the local rules.

The hooks in the first four parts of this series all announce themselves. A blocked command throws an error in your face. A held exit makes the agent keep working when it wanted to stop. A flagged prompt staples a visible note onto your message. You feel each one the moment it fires. The hooks in this post are the opposite. The best one I run is a hook I forget exists, because it never interrupts anything. It just sits in the background and quietly changes the texture of working with the agent.

This is part 5, the last one. Part 1 was context rot and the handoff that resets a session before it decays. Part 2 was guardrails that catch a dangerous command before it runs. Part 3 was quality gates that won't let the agent say "done" without proof. Part 4 was the prompt layer, a local model reading my input before Claude does. Those were all about control. This one is about comfort, and it lives on three events that never block a thing: SessionStart, Notification, and Stop.

Hooks that whisper instead of shout

Every hook in the earlier parts had a verdict. Allow this, block that, here's a note you should read. The ambient ones have no verdict at all. They observe an event and produce a side effect somewhere off to the side: a sound, a line in a file, a message dropped in a queue. The agent's turn is completely unaffected. Nothing is held, nothing is denied, nothing is injected into the conversation unless I choose to.

That sounds like a smaller thing than a guardrail, and on any single turn it is. The payoff shows up over a week. After living with these for a while, the hooks stopped feeling like rules I imposed on the agent and started feeling like the agent's interface to me. They are how I keep a sense of what's going on without staring at a wall of scrolling text. That shift, from policing the agent to quietly living alongside it, is the whole reason I wanted to end the series here.

Hearing the agent instead of watching it

The first ambient hook I ever wrote reads the agent's turns out loud. There was nothing clever behind it. I was tired of babysitting a terminal. I'd kick off a long task, then sit there watching lines scroll, afraid to look away in case it finished or got stuck. Text-to-speech let me look away.

Here's the part the marketing version of this gets wrong, and I want to be precise about it. There is no hook in Claude Code that fires on every little thing the agent does mid-turn. The events I have to work with are turn boundaries and notifications. So the narration isn't a live play-by-play of every file edit. It's narration of state changes, which turns out to be exactly what I actually want.

Two events carry it. Stop fires when the agent finishes a turn, so a hook there can speak a short summary of what just happened: "finished, tests green" or "stopped to ask you something." And Notification fires when Claude Code wants my attention, which is the real moment I need to hear about. The input is small:

{
  "hook_event_name": "Notification",
  "message": "Claude needs your permission to run a command",
  "session_id": "abc123",
  "cwd": "/path/to/project"
}

One thing to know before you build on this: the Notification hook is informational only. It cannot block, it cannot change anything, its exit code is ignored. That's perfect for narration, because narration should never be able to interfere with the work. The hook reads the message field, pipes it to a text-to-speech voice, and gets out of the way. It also fires on a fixed set of moments rather than continuously, things like the agent going idle or asking for permission, so what I hear is "your turn" and "I'm done," never a firehose. I can go make coffee, hear the voice say the build passed, and wander back. The terminal stopped being something I have to guard.

The trick with audio is to narrate state changes rather than activity. You don't want to hear every tool call. You want to hear the two moments that matter: it needs you, or it's done. Notification and Stop map onto exactly those two, which is why this works as well as it does.

A small file that says what each session is doing

The minute you run more than one Claude session at a time, you lose the plot. Three terminal tabs, each grinding on something, and no way to tell at a glance which one is waiting on you and which one is happily working. I fixed that with a hook and a single tiny file.

On SessionStart, each session writes a line into a shared status file: who I am, what I'm working on, started just now. The event hands the hook everything it needs to identify itself:

{
  "hook_event_name": "SessionStart",
  "source": "startup",
  "session_id": "abc123",
  "cwd": "/path/to/project"
}

The source field tells the hook how the session began. It's one of startup, resume, clear, or compact, so a hook can write "fresh start" differently from "resumed an old session" if it cares to. Then, on every Stop, the same session updates its line: still working, or now idle and waiting. The status file becomes a live board. One small file each session keeps current, and a glance at it tells me the state of everything running. No dashboard server, no daemon, just a file that every session politely keeps honest as it goes.

The reason this is a hook and not a feature I bolted onto my workflow is that I will absolutely forget to update a status by hand. The hook never forgets. It fires on SessionStart and Stop whether I'm paying attention or not, so the board is never stale. That's the recurring theme of this whole series: the things you mean to do every time are the things a hook should do for you.

Sessions leaving notes for each other

Once each session is writing where I can see it, the next thought is obvious: can they talk to each other? Not in real time, they're separate processes that don't share memory. But they can leave notes. A shared queue file, one session appends a message addressed to another, and the recipient picks it up the next time one of its hooks runs.

The honest mechanical detail here matters, because it's easy to imagine this as live chat and it isn't. Hooks are event-triggered rather than background daemons. A session can only check its inbox at the moments its hooks fire: at SessionStart, it reads any messages left while it was away, and on Stop, between turns, it peeks at the queue again. So the delivery is "the next time you come up for air" rather than "instantly." In practice that's plenty. One session finishes a piece of research and leaves a note for another that's been waiting on it; the waiting session sees it the next time it ends a turn and picks up the thread. I stopped being the courier carrying findings from one tab to another.

Two parallel Claude sessions and an ambient layer between them. On SessionStart each session writes its state to a shared status file and reads any queued messages. On Stop, at each turn boundary, a session refreshes its status, leaves a note in the queue for another session, and speaks the result out loud through text to speech. You glance at the status file and hear the narration without watching the terminal.

Session A
SessionStart / Stop

Session B
SessionStart / Stop

Status file
who, what, idle?

Message queue
notes between sessions

You glance
one quick look

You hear it
TTS on Stop

read state
speak result

The ambient layer: sessions write state and leave notes at their SessionStart and Stop boundaries. You take it in by glancing at one file and listening, instead of watching every terminal.

Showing up already equipped

The other thing SessionStart is good for is making the agent useful from its first message instead of its fifth. A fresh session is a blank slate. It doesn't know which project it's in, what the local rules are, or which tools this particular job needs. Normally I'd spend the first few exchanges telling it. A hook can hand it all of that before I type anything.

There are three concrete moves here, and unlike the narration story, these come straight from documented fields:

Inject the local conventions. A SessionStart hook can return additionalContext, the same field the prompt gate from part 4 uses, and whatever it returns lands in the agent's context for the session. I use it to feed in this project's git rules, the report format I expect, the conventions that would otherwise need repeating every single time.
Re-scan skills. The hook output supports a reloadSkills boolean. Set it and Claude Code re-scans for skills after the hook runs, so a tool I just added or a project-specific skill is available immediately rather than after a restart.
Pre-load a tool. If a job reliably needs a particular tool ready, a browser driver, say, the hook can warm it up at session start so the agent shows up already holding it instead of fumbling for it three messages in.

The shape of the output is the familiar one. Print JSON, and the context rides into the session:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Project conventions: branch off main, never commit to it directly. Reports go in the project report folder, not the repo root."
  }
}

Note the casing, because it's a silent-failure trap. The input field is hook_event_name in snake_case; the output key is hookEventName in camelCase. Get one wrong and the hook runs, exits clean, and does precisely nothing, which is the most annoying kind of bug to chase. If you'd rather skip the JSON entirely, a SessionStart hook can just print plain text to stdout on a clean exit and Claude Code folds that into the context too. The JSON form is for when you also want to flip reloadSkills or set a session title.

Where this stops working

Ambient hooks fail quietly, which is both their charm and their risk. A guardrail that breaks throws an error you can't miss. A status writer that breaks just stops updating, and you might not notice for an hour that the board has gone stale and you've been trusting a frozen snapshot. So the failure mode flips compared to the earlier posts: there, a broken hook was loud and safe; here, a broken hook is silent and quietly misleading. I keep these dead simple for exactly that reason. The more an ambient hook does, the more ways it has to lie to you without saying a word.

The other limit is restraint. It is genuinely tempting to narrate everything, write five status files, wire up elaborate cross-session protocols. Don't. The value of the ambient layer is that it's quiet. The moment it starts demanding attention, narrating noise, filling files you have to parse, it's just another thing shouting at you, and you've lost the one property that made it worth building. The good version fades into the background. The bad version becomes a second job.

Build your own

The pattern is the smallest in the whole series, because these hooks don't decide anything:

Pick an event with no verdict: SessionStart for setup, Stop for turn boundaries, Notification for "needs you" moments.
Read the JSON on stdin. Pull source on SessionStart, message on Notification, session_id when you need to tell sessions apart.
Produce a side effect off to the side: speak a line, append to a status file, drop a note in a shared queue. Never touch the agent's turn.
To feed the session at startup, return hookSpecificOutput.additionalContext (camelCase) or just print plain text. Add reloadSkills if you need skills re-scanned.
Keep it boring and keep it quiet. An ambient hook earns its place by being something you stop noticing, not something you have to manage.

Series: Claude Code hooks (5 parts)

Context rot + handoff - how I stop sessions from rotting
Guardrails - hooks that won't let the AI shoot me in the foot
Quality gates - forcing the agent to verify before it says "done"
The prompt layer - a local LLM that reads my prompt before it hits Claude
The ambient layer - the hooks you stop noticing (you're here)

That's the series. Five posts, from the loud hooks to the quiet ones.

That's the series

Five posts on the hooks that keep Claude Code honest. Drop your email and I'll send whatever I write next. Just new posts, nothing else.

Email address

The whole series, in one line each

Five posts, and a shape underneath them. It started with context rot: a session that runs too long quietly gets worse, so a hook resets it before it decays. Then guardrails, catching the one dangerous command before it runs. Then quality gates, refusing to let "done" mean anything less than proof. Then the prompt layer, a local model reading my half-formed input before the expensive one ever sees it. And finally this, the ambient layer, where the hooks stop being walls I built around the agent and become the way I keep a calm sense of what it's doing. Each one is a small piece of judgment I got tired of supplying by hand, handed to the deterministic part of the system that never gets tired and never forgets. That, more than any single hook, is what the whole series was about.

Takeaway

The loud hooks get the credit. They block the disaster, hold the exit, catch the bad prompt, and you feel grateful the moment they fire. The quiet ones get none of that, and they might be the ones I'd miss most if they vanished. A voice that tells me the build passed while I'm across the room. A file that shows me what four sessions are doing in one glance. Sessions that hand each other notes so I don't have to. None of it blocks anything. All of it changed how it feels to work with the agent, which is the part the loud hooks never touch.

The Podcast Invite That Was Actually Malware

Marcin Dudek — Thu, 02 Jul 2026 13:04:12 +0000

Originally published on https://marcindudek.dev/blog/fake-podcast-invite-phishing/

TL;DR

A verified X account with thousands of followers invited me to a podcast. Flattering, personalized, professional.
The "Google Meet link" in the follow-up email led to a fake Meet page on a free website builder - real Meet links are always on meet.google.com.
The page used a browser protocol-handler trick to push a self-signed "meeting app" installer - an infostealer that goes after passwords, sessions, and crypto wallets.
Rule of thumb: no real meeting ever requires you to install something or run a command to join. Meet, Zoom, and Teams all work in the browser.
This is a real attack I received and reported in June 2026 - I've left out all identifying details on purpose. What matters is the method, not who ran it.

I got invited to a podcast this week. The host had done his homework: he knew how long I've been in the industry, name-dropped the tech I actually work with, and said my profile was "exactly what his audience wants to hear." Verified account, blue check, a few thousand followers, registered years ago.

One problem. The podcast didn't exist, and the "Google Meet link" was a delivery mechanism for malware built to empty browser sessions and crypto wallets.

I didn't get caught, but I want to walk you through exactly how it works, because this one is good. This isn't the usual "DEAR SIR, URGENT BUSINESS PROPOSAL" spam. It's a targeted, researched, multi-step con, and there's been a whole wave of these fake-meeting attacks through 2025 and 2026. If you have any kind of public track record - a blog, a GitHub, a conference talk - you're on the target list.

How the Attack Unfolds

Step 1: The flattering DM

It starts with a direct message on X. A verified account - blue check, thousands of followers, registered years ago - says they run a podcast and would love to have you on as a guest. The message references your real work. This is the part that disarms people: it doesn't read like spam because it isn't mass-sent. Someone (or someone's AI) actually researched you.

Tailored flattery is the whole trick. The more accurately a stranger describes your career, the more you should wonder what they want from you next.

Step 2: Moving off the platform

You agree to a date, they ask for your email "to send the calendar invite." The email that arrives looks like a normal meeting invitation with a "Join with Google Meet" button. Two details are off, though both are easy to miss:

The sender is a throwaway free email address with a name that doesn't match the X account. Different person entirely, no domain, no podcast branding.
The button doesn't go to meet.google.com. It goes to a page hosted on a free website builder, dressed up to look like the Meet lobby.

That second point is worth repeating, because it's the single most reliable check in this whole story: a real Google Meet link is always on the meet.google.com domain. Not "almost", not "usually". Always. Anything else - a lookalike subdomain, a free-hosting page, a shortened URL that unwraps to something Google-ish - isn't Meet.

Step 3: "Just be with your PC"

Before the call, the "host" asks a strange question: will you be at your computer, on Windows? I asked why that mattered for a podcast. The full answer I got was: "just be with your pc."

Here's why they care. The whole attack depends on you sitting at a desktop machine during the "meeting", so that when the fake Meet page tells you to install something or run a "fix", you can actually do it. A phone won't execute their payload. A real podcast host couldn't care less what device you join from.

Step 4: The trap springs

The fake Google Meet page is where the technical part kicks in. Instead of a meeting, you get one of two endings:

The installer. Through a browser protocol-handler trick, the page force-opens a URL in a specific browser and pushes a "meeting application" install. The package is self-signed - no trusted publisher, just a certificate the attacker generated themselves. The "app" is an infostealer: it grabs saved passwords, browser session cookies (which let attackers walk into your logged-in accounts without ever needing your password), and crypto wallet data.
The login. Some variants skip the malware and simply ask you to "sign in with Google to join the waiting room." That's a straight account-takeover phish.

Either way, the moment you comply, it's over. Sessions, passwords, wallets - gone in seconds, quietly, while you sit there waiting for a podcast host who was never going to show up.

The 7 Red Flags, In Order of Appearance

Looking back at the whole exchange, the warning signs were there from the first minute. Here's the checklist version:

Identity mismatch. One name on X, a different name in the email, a random free email address as the sender. Real podcasts have domains, websites, and consistent branding.
No public footprint. A real show has episodes you can listen to, past guests you can find, a page that existed before last month. This one had nothing.
A "Meet" link outside meet.google.com. The number one tell. Hover before you click and read the actual domain.
"Be at your computer" pressure. No legitimate meeting cares about your operating system.
Any request to install or run something to join. Meet, Zoom, and Teams all work in a plain browser tab. "Install our meeting client to continue" is the attack, every single time.
The blue check means nothing. Verified accounts get bought, sold, and hijacked. Followers can be purchased by the thousand. Account age and verification prove nothing here.
Flattery tuned precisely to your CV. That's research, and research costs effort. Ask yourself why a stranger invested it.

How to Not Get Caught

Never install a "meeting client" sent by someone you've never met. Every mainstream conferencing tool runs in the browser, and if you do use desktop apps, you already have them installed. There's no scenario where joining a podcast requires new software from a link in an email.
Never run "fix" commands a meeting page gives you. A page that tells you to paste a command into your terminal, PowerShell, or the Windows Run dialog "to fix your microphone" is doing something else entirely. This pattern - known as a ClickFix attack - is one of the most effective malware delivery tricks of the past two years precisely because it makes you do the installation.
Verify the person through an independent channel. Look up the podcast. Listen to thirty seconds of a past episode. Find the host's name on the show's website and contact them there. A real host will be happy you checked; a fake one will evaporate.
Read domains before you click. Hover over the button, look at the status bar, read the actual hostname right-to-left. meet.google.com is Meet. A free site-builder URL with "meet" somewhere in the path isn't.

If you suspect you already ran something, do this now, in this order:

Disconnect the machine from the network immediately.
Change critical passwords from a different, clean device - email first, then anything tied to money or code.
Treat every browser session as compromised: log out everything, everywhere, and enable two-factor authentication as you go.
If you keep crypto on that machine, consider the wallet burned - migrate funds from a clean device.
Then scan or reinstall. Modern infostealers finish their job in the first minute, so speed matters more than forensics.

Report it. Report the account on X, report the phishing page to Google Safe Browsing and to the abuse channel of whatever free host it sits on, forward the email as phishing in your mail client. It takes five minutes and it genuinely burns the attacker's infrastructure - these campaigns reuse the same pages and accounts against many targets, and takedowns hurt them.

Why You, Specifically

Here's the uncomfortable part. This scam targets people because they have a visible body of work. Developers, founders, writers - anyone whose career is public enough to research and whose machine is likely to hold something worth stealing: GitHub sessions, cloud consoles, deploy keys, crypto wallets, client access.

Fifteen-plus years in this industry, and I still felt the pull of "someone noticed my work." That's the hook. It works on experienced people precisely because it flatters the thing we're proudest of. You won't out-think the scammer in the moment, so don't try. What works is mechanical rules that don't bend to flattery: real Meet lives on meet.google.com, real meetings never require installs, and real hosts survive a background check.

Stay paranoid. It's cheaper than the alternative. It's the same instinct that once made me dig into a weird metric and catch an attack in progress - I wrote that one up in spotting an XML-RPC brute force through a dropping cache hit rate.

And if you know someone with a public profile - a blog, a GitHub, a few conference talks - send them this post. The next "podcast invite" in their DMs might be this exact play, and the cheapest defense is having seen it once before.

Claude Code Quietly Taught Itself to Stop Waiting for You

Marcin Dudek — Thu, 02 Jul 2026 13:04:09 +0000

Originally published on https://marcindudek.dev/blog/claude-code-afk-mode/

TL;DR

Claude Code shipped AFK mode (away from keyboard) in v2.1.198, built July 1, 2026. It is not in the changelog and there is no release note.
An unanswered AskUserQuestion dialog now auto-answers after 60 seconds (with a 20-second on-screen countdown) and tells the model to proceed on its best judgment.
Two undocumented env vars control it: CLAUDE_AFK_TIMEOUT_MS and CLAUDE_AFK_COUNTDOWN_MS. Set the timeout to 2147483647 and it effectively never fires.
I found all of this by running strings over the local binary and bisecting four versions. Every command in this post is reproducible on your own machine.
The upside: unattended and remote sessions stop hanging forever. The catch: an away user hasn't agreed to anything, so the model can now proceed on a guess and act on it.

I run a lot of Claude Code sessions I'm not watching. Delegated tasks, overnight jobs, browser QA runs kicked off from another session. So when one of them auto-answered its own question and kept going, I noticed. The transcript had a line I'd never seen: it had continued without an answer. Nothing had crashed. It had waited about a minute, given up on me, and moved on. That's Claude Code's AFK mode, and it's brand new.

Away from keyboard - that's the whole idea. AFK mode resolves an unanswered AskUserQuestion dialog after a timeout and lets the model carry on instead of blocking forever. It landed in v2.1.198 on July 1, 2026, with no changelog entry, no release note, and no mention anywhere I could find. So I pulled the binary apart to see exactly what it does. Here's the whole thing, and the commands to check it yourself.

The message the model actually gets

When the countdown runs out, the dialog resolves itself and the tool hands the model an injected instruction. This is the string, pulled verbatim out of the v2.1.198 binary:

No response after ${Math.round(e/1000)}s — the user may be away from keyboard. Proceed using your best judgment based on the context so far; you can re-ask this question later if it's still relevant.
Injected tool result, verbatim from claude v2.1.198

Notice the ${Math.round(e/1000)}. The "60s" you see in the transcript isn't hardcoded. It's computed from whatever the timeout is set to, which is the first hint that the number is configurable. The transcript line you actually see depends on the state of the dialog when it expired:

Nothing highlighted when the clock ran out, so the transcript shows continued without an answer. That's the one that caught my eye.
Options were pre-selected, so it reads continued with the answers selected so far, and those selections are what get submitted.

There's also a telemetry event, tengu_ask_user_question_afk_auto_advance, that fires on every auto-advance with the timeout, the number of questions, whether there were partial answers, and whether the session was in plan mode. So Anthropic is measuring this. It just isn't telling anyone about it yet.

How I found it (run this yourself)

Nothing here needs a debugger or a disassembler. Claude Code ships as a big JavaScript bundle inside the binary, and strings plus grep gets you most of the way. On my Mac the versioned binaries live under ~/.local/share/claude/versions/ - your installer may keep them elsewhere, but the idea is the same.

# Look for the AFK strings in the current version
cd ~/.local/share/claude/versions/
strings 2.1.198 | grep -o 'CLAUDE_AFK_TIMEOUT_MS'
strings 2.1.198 | grep -o 'No response after[^"]*'

The second command prints the full injected message, dynamic ${Math.round(e/1000)}s and all. Once I had the strings, the next question was: when did this show up? I kept a few old versions around, so I bisected them by counting the AFK tokens in each:

for v in 2.1.195 2.1.196 2.1.197 2.1.198; do
  echo "=== $v ==="
  strings "$v" | grep -c -E 'CLAUDE_AFK_TIMEOUT_MS|afkTimeoutMs|No response after'
done

Clean cutover. The implementation is absent from every version before 2.1.198 and present in it:

Version	Built	AFK auto-advance
2.1.195	Jun 26	absent
2.1.196	Jun 30	absent
2.1.197	Jun 30	absent
2.1.198	Jul 1	present

One nuance worth being precise about. The feature gate id, afk-mode-2026-01-31, shows up in all four versions, not just the new one. That date is January 31, 2026. So the concept has been sitting behind a gate for about five months. What's new in 2.1.198 is the part that matters to you: the code that actually watches the clock in the terminal and answers the question when it runs out.

The internals, de-minified

The logic reads clean once you rename the minified variables. Two defaults, and an env var that wins over each:

// Reconstructed from the minified bundle in v2.1.198
const AFK_TIMEOUT_DEFAULT   = 60000;  // 60s before it answers for you
const AFK_COUNTDOWN_DEFAULT  = 20000;  // 20s visible countdown

// env var wins, else the default; countdown can't exceed the timeout
timeout   ??= env.CLAUDE_AFK_TIMEOUT_MS   ?? AFK_TIMEOUT_DEFAULT;
countdown  = Math.min(countdown ?? env.CLAUDE_AFK_COUNTDOWN_MS ?? AFK_COUNTDOWN_DEFAULT, timeout);

That's the entire knob set. A 60-second timeout, a 20-second countdown that appears near the end of it, and two environment variables that override both. Nothing in settings.json schema, nothing in --help, nothing in the docs. Just these two strings baked into the bundle.

Users asked for this for months. Twice they were told no.

Here's the part that makes this more than a patch note. This exact behavior was requested on GitHub, repeatedly, and closed as not planned - before it shipped anyway with no announcement.

Timeline from January to July 2026: the AFK gate is created in January, users file issues in March and May asking for a timeout and both are closed as not planned, a related issue stays open in June, and in July v2.1.198 ships the feature silently.

Jan 31
gate created

Mar 4

30740

"add timeout" · not planned

May 22

61337

blocks /goal · not planned

Jun 23

70294 open

Jul 1
v2.1.198
ships, silent

Five months from gate to ship. Two feature requests closed as "not planned" along the way, and no changelog line when it finally landed.

#30740 (March 4, closed, not planned): "Add configurable timeout (or option to disable) for AskUserQuestion tool." The exact thing that just shipped.
#33848 (March 13): the afk-mode-2026-01-31 beta header leaked into Auto Mode API calls and caused a 400 error. Proof the gate existed in dev long before the terminal ever used it.
#61337 (May 22, closed, not planned): "Claude can use AskUserQuestion to block /goal mode indefinitely." A session that made zero progress overnight because it was waiting on a question.
#70294 (June 23, still open): interactive prompts hang remote sessions on Telegram and Slack with no timeout, called the single biggest reliability cliff when running Claude Code remotely.

I get why it shipped quietly. It's a behavior change that could surprise people, and a soft rollout behind a gate is the safe way to do that. But the people in those threads are the ones who'd most want to know it's fixed, and right now they have no way to find out except by tripping over the transcript line like I did.

How to configure it

The two env vars go in the env block of your ~/.claude/settings.json, or in whatever launcher starts your delegated and headless sessions. All values are milliseconds and strings.

{
  "env": {
    // Wait 10 minutes before answering for me
    "CLAUDE_AFK_TIMEOUT_MS": "600000",

    // Or effectively never auto-advance (max 32-bit int)
    // "CLAUDE_AFK_TIMEOUT_MS": "2147483647",

    // Grow or shrink the visible countdown
    "CLAUDE_AFK_COUNTDOWN_MS": "30000"
  }
}

One honest caveat, because I couldn't verify past the client. These vars are the defaults the binary carries, but the whole thing sits behind a Statsig gate called afk_mode. A gate can be flipped per cohort from the server, so I can't promise the 60-second default is live for every user, or that it won't change. What I can promise is that the strings, the constants, and the env vars are exactly what's in the v2.1.198 binary on my disk today.

The new failure mode: proceeding on a guess

For unattended work this is a real fix. My delegated sessions run non-interactive, and before this they could wedge forever the moment the model decided to ask me something. A hung session that burns nothing and produces nothing is the worst outcome, and AFK mode kills it. That alone makes it worth knowing about.

But there's a cost, and it's the flip side of what issue #30740 warned about. An away user hasn't agreed to anything. "Best judgment" is the model's judgment, made with no answer to the question it thought was worth asking. If the question was "should I delete these or archive them?" and nobody's there, the model now picks one and acts on it. The clarifying question exists precisely because the answer wasn't obvious. Auto-answering it means the least-obvious calls now get made by a guess, and then executed.

A blocked session wastes your time. An auto-advanced session can waste your data. Those are different risks, and AFK mode trades the first for the second. For read-only work that's a clear win. For anything that writes, deletes, or sends, it's a reason to keep a human in the loop or turn the timeout way up.

What this changes about how I write questions

Here's the practical takeaway, and it's the part nobody's written down yet. If an unanswered question resolves on its own, then the option the model lands on when I'm not there is effectively the choice I made by walking away. So the design rule for AskUserQuestion shifts.

Put the safe option first. Make the default the one you'd be fine with an absent human "picking" - usually the conservative, reversible, do-less choice. If I'm scripting agents that run without me, and I do, then every question they might ask needs a safe fallback baked into its first option, because that's the one AFK mode will effectively select. This matters most in delegation setups like my own op workflow, where a session runs another session's task with no human watching either end. A hung prompt there used to strand the whole chain. Now it proceeds, which is better, as long as "proceeds" means "does the safe thing."

This is the same instinct behind the guardrails I've written about before. If you want the background on making Claude Code fail safe instead of fail loud, the PreToolUse guardrails post covers catching a dangerous command before it runs, and the Stop-hook quality gates post covers not letting a session end until the work is actually verified. AFK mode is one more place where the default behavior decides what happens when you're not looking.

One thing I want to be straight about, since I checked. There are already third-party tools with "AFK" in the name for Claude Code, and hook-based workarounds people built to escape exactly this hang. Those are real and they predate this. What's undocumented is the native auto-advance that now ships in the binary and the two env vars that drive it. That's the new part, and that's what nobody's written up.

Get the next teardown in your inbox

I dig into Claude Code internals and ship notes when I find something worth sharing. Drop your email and I'll send the next one. Just new posts, nothing else.

Email address

Takeaway

Claude Code stopped waiting for you, and it did it without saying so. For the overnight and remote sessions that used to hang, that's the fix a lot of people asked for and gave up on. For anything with consequences, it's a new default worth setting on purpose. Check whether it's live in your version with one strings command, decide how long you actually want it to wait, and write your questions so the option it lands on when you're gone is one you can live with.

I'll keep pulling on these threads as new versions ship. The interesting stuff is rarely in the changelog.

I Tested All 11 Free WooCommerce EU Withdrawal-Button Plugins

Marcin Dudek — Thu, 18 Jun 2026 15:27:01 +0000

Originally published on https://marcindudek.dev/blog/woocommerce-eu-withdrawal-button-plugins-tested/

From 19 June 2026, every shop selling to EU consumers has to put a clearly labelled, one-click "withdraw from contract" function in the storefront. That's Directive (EU) 2023/2673, which adds a new Article 11a to the old Consumer Rights Directive. WooCommerce has no native support for it - there's just an open request (#65443) sitting there with no roadmap.

So you need a plugin. The wp.org repo has a pile of them now, all claiming compliance. I didn't trust the readme screenshots. I installed all 11 I could find, one at a time, on a real WooCommerce site and drove the actual withdrawal flow as a guest. Then I scored each one against what the directive literally asks for.

This is the "I did the tedious testing so you don't have to" post. Here's what I found, including two I'd actively avoid for this job.

What the law actually wants

First, the thing everyone gets wrong: this is not a new right. The 14-day cooling-off period already existed. Refund timelines, return-shipping rules - all unchanged. What changed is the method. If a customer can buy in a few clicks, they have to be able to withdraw with comparable ease, through a clear electronic function. Not by hunting for a PDF or emailing your support inbox.

In practice the directive boils down to a few hard requirements:

A visible button/link, reachable from every page. "withdraw from contract here" (PL: "Odstąp od umowy tutaj") or an unambiguous equivalent. A buried footer link that looks like your T&Cs is no longer enough.
Guest access. If you allow guest checkout, guests have to be able to withdraw without registering or logging in. This is the one that kills half the "return" plugins.
A two-step flow. Initiate, then a separate "confirm withdrawal" action so nobody submits by accident.
Whole order or part of it. Partial withdrawal - per item, per quantity - is explicitly required.
No extra mandatory fields. You can ask for name, order ID and an email for the confirmation. You can't force IBAN or a reason-for-return as required fields.
A durable-medium acknowledgement. A timestamped email (or account record) confirming receipt, without undue delay.

One easy-to-miss knock-on: your pre-contractual info under Art. 6 now has to mention the function exists and where it is. So your return-policy and terms pages need a small update too, not just the UI.

How I tested (and scored)

This wasn't a desk review. I spun up a real WooCommerce site on my local wp-test stack - store country Poland, currency PLN, guest checkout on - and installed each plugin on its own, one at a time. Then I placed a real guest order (#13, jan.kowalski@example.com) and drove the withdrawal flow in a real browser as a logged-out guest.

For the durable-medium step I hooked wp_mail and captured what each plugin actually queued, because the test box can't send real mail. So "email verified" here means "the plugin generated a timestamped customer + admin email", not "it landed in an inbox". That's an honest limitation - confirm deliverability on your own staging with real SMTP.

I scored nine criteria, 0-2 each, mapped straight to Art. 11a (max 18):

C1	Site-wide visible button, reachable from every page
C2	Guest access - usable without login, by order # + email
C3	Two-step flow - initiate, then a separate confirm
C4	Durable-medium acknowledgement - timestamped email/record
C5	Partial withdrawal - select specific items / quantities
C6	No extra mandatory fields - IBAN / reason not forced
C7	Admin management - request list / status flag / order-note trail
C8	Polish i18n - translatable, label editable to "Odstąp od umowy"
C9	Doesn't break the store - no fatal, HPOS-compatible

0 = no, 1 = partial or paywalled, 2 = yes, free.

The scoreboard - all 11

Plugin	C1	C2	C3	C4	C5	C6	C7	C8	C9	Total
EU Order Withdrawal Button (Vendidero) ★	2	2	1	2	2	2	2	2	2	17
EU Withdrawal Button (runner-up)	2	2	2	2	2	2	1	2	2	17
WWU Withdrawal Button (OSS)	1	2	2	2	2	2	2	2	2	17
WPify Woo (module)	1	2	2	2	2	2	2	2	2	17
Germanized (bundles the winner)	2	2	1	2	2	2	2	2	2	17
EU Withdrawal Compliance	1	2	2	2	1	2	2	2	2	16
Easy Return	1	2	2	2	2	2	2	2	1	16
WebToffee EU Order Withdrawal	2	2	2	2	0	2	2	2	2	16
BuddyPilot Withdrawal *	1	2	2	1	1	2	2	2	2	15
Bitron Right of Withdrawal	1	2	0	2	0	1	1	2	2	11
WP Desk Flexible Refund	0	0	1	1	1	1	2	1	2	9

BuddyPilot: C4/C5 scored conservatively. The architecture (magic-link, partial, PDF declaration) is clearly there, but it doesn't use wp_mail and the access-link step wouldn't complete in my headless harness, so I couldn't verify the end-to-end email live. It's likely higher on a real-mail staging site.

The same scores as a picture. Five plugins tie at 17/18; the two at the bottom (Bitron, WP Desk) are the ones I'd avoid for this job.

Five plugins tie at 17/18. That's not as decisive as it looks - the gaps are in different places, and for a Poland-only store the practical winner is clear.

The winner: EU Order Withdrawal Button (Vendidero)

EU Order Withdrawal Button for WooCommerce - wordpress.org/plugins/eu-order-withdrawal-button-for-woocommerce, v2.2.1, ~1,000 installs, ★5, HPOS-ready. The free core covers everything you need. Pro only adds per-product exclusions and CSV export.

It's the closest fit to the literal Art. 11a checklist with the least fuss. Nice surprise from testing: this is Vendidero's plugin - the same company behind Germanized, and Germanized literally bundles this exact engine. So you get a serious legal-compliance vendor's code, standalone and lightweight.

Guest form - only Email is required - and the site-wide sticky "Withdraw from contract" button, bottom centre.

WooCommerce → Withdrawals: a real request queue with full/partial badge, verified email, status and per-row actions.

What I verified on the test site:

Site-wide button (C1): one toggle (embed_everywhere) drops a sticky "Withdraw from contract" button on every page.
Guest (C2): submitted as a logged-out guest against order #13, no account. Only the email is required - the email_repeat field is a hidden anti-spam honeypot, not a real field.
Durable medium (C4): I captured two real wp_mail calls - a customer "Your withdrawal request for order #13 has been received" and an admin notification, both timestamped.
Admin/audit (C7): a dedicated Withdrawals queue, a custom "Pending withdrawal" order status, and an order note logging the exact items. This is the best merchant side of the bunch.

Where it loses its one point: the confirm is a single-page "Confirm withdrawal" rather than a distinct review screen (C3=1), and the per-item picker for partials is delivered through the emailed link instead of inline. Two honest cons: site-wide visibility is off by default - flip the toggle - and there's no Polish bundled, though the page title and button label are freely editable to "Odstąp od umowy tutaj".

If you just need to be compliant and move on, this is the one. Most complete free feature set, a real admin queue with an audit trail, the install leader, and a vendor that does compliance for a living.

The runner-up: EU Withdrawal Button

EU Withdrawal Button for WooCommerce - wordpress.org/plugins/eu-withdrawal-button-for-woocommerce, v2.0.1, freemium. This is the one with the nicest customer-facing UX of the lot. A genuine two-step modal (Continue, review, Confirm) and the cleanest inline partial picker I saw - per-item checkboxes and editable quantities with a live total. IBAN and reason are both explicitly optional, with helpful copy.

Step 2: order #13 recovered as a guest, per-item plus quantity partial selection, live total, then Confirm. The cleanest withdrawal UX I tested.

So why not #1? The admin side is weak. There's no dedicated request dashboard, and the selected partial items aren't stored on the order - they only go out in the email. For a merchant who has to act on each request, that's an operational gap the winner doesn't have. It also defaults to "My Account only" and needs a couple of toggles to go truly site-wide.

If you care most about the customer experience and you're fine managing requests from the email, this is a great pick. For most stores, the better admin tooling on the winner wins out.

Three alternatives worth knowing

Most legally rigorous: WWU Withdrawal Button (OSS) - 17/18

If compliance evidence is your priority, nothing beats this open-source one. Every declaration gets a PDF plus an OpenTimestamps cryptographic timestamp, precise legal wording, EU/EEA applicability rules, exclusions and consent-IP capture. The catch: it's off the wp.org repo (GitHub install, no automatic updates), disabled by default, and has more knobs than the leaders. Great for the audit-minded, more upkeep.

WWU step 2 - "withdraw from contract here", reason optional, per-item partial.

Easy Return step 2 - polished wizard, per-item partial, and it ships Polish out of the box.

The only one with Polish bundled: Easy Return - 16/18

Gorgeous 3-step wizard, good guest order recovery, and the only plugin that ships pl_PL out of the box. But it's SaaS-coupled (easyreturn.eu). In free/unconnected mode the confirmation email is literally labelled "This is a test withdrawal confirmation email", and it doesn't declare HPOS. Lovely UX, but I wouldn't bet compliance-grade email delivery on the free tier.

Most reliable vendor, but no partial: WebToffee - 16/18

Established vendor, clean email verification, and a site-wide footer link on by default. The dealbreaker for Art. 11a: no partial withdrawal, whole order only. The directive explicitly says "whole order or part of it", so this misses a hard requirement.

What I'd avoid for this job

Two plugins came up when I searched but are the wrong tool here:

WP Desk Flexible Refund (9/18). It's a capable refund/RMA tool, but the free form is login-gated behind My Account with no guest path. It fails the two non-negotiable tests - site-wide and guest - so for the withdrawal-button obligation it's the wrong category, even though the plugin itself is fine at what it does.
Bitron Right of Withdrawal (11/18). Single-step (no separate confirm), no partial, and the declaration isn't even tied to the real order - the order ID is optional and unvalidated. Too loose for this.

And a note on the other two 17/18 plugins: WPify Woo and Germanized both do the feature well - Germanized actually bundles the winner's engine. But both are heavy suites (Czech and DACH respectively). Only pick them if you also need the rest of the suite. For a Poland-only store that just wants the button, the standalone winner is a fraction of the weight.

The Poland gotcha

Here's where Poland is different from "just install it before the 19th". Poland missed the 19 December 2025 transposition deadline. The withdrawal-button rules were meant to ride into the ustawa o prawach konsumenta via a consumer-credit vehicle (UC82), steered by UOKiK. In May 2026 the government pulled that and said it would start new work. So there's likely no Polish statute in force on 19 June. Commentators are calling the date "nierealne".

Does that mean you can wait? I wouldn't. A few reasons:

The directive is binding EU law. Polish transposition is a when, not an if - and it may land with a short runway.
If you ship to other EU consumers, those countries' rules already apply to those sales from 19 June. Germany (§356a BGB) and France (Art. 54-bis) have transposed.
Big platforms are rolling it out now, so it's becoming a baseline trust signal. Doing it calmly this week is cheap. Retrofitting under enforcement pressure later is not.

So which plugin for a Polish store?

Same answer as overall - EU Order Withdrawal Button (Vendidero). There's one Poland-specific catch worth knowing: it doesn't ship a Polish translation. But everything is editable, so you just type the labels yourself - the page title and button become "Odstąp od umowy tutaj" and the confirm becomes "Potwierdź odstąpienie od umowy". Two minutes of work, and you get the best admin tooling of the bunch.

The only plugin that ships pl_PL out of the box is Easy Return. If you want zero translation work and a polished Polish wizard, it's tempting. I'd still hesitate on the free tier - its confirmation email is labelled "test", and the durable-medium email is the one part of this you can't get wrong. For a Polish store I'd rather spend two minutes translating the winner than rely on Easy Return's free-tier email. If you're already paying for Easy Return's connected service, that calculus changes.

This is a practitioner write-up, not legal advice. For final shop-policy wording, confirm against the Polish transposition once it's published, and for high-value exposure talk to a consumer-law lawyer.

What it costs if you skip it

The penalties vary by member state, but one consequence is EU-wide and it's the one that actually bites day to day: if a compliant withdrawal function is missing, the 14-day cooling-off window can extend to 12 months and 14 days. Customers can send things back the better part of a year after delivery. That's the real commercial risk, well before any regulator gets involved.

On top of that, fines exist where the rule is enforceable:

Poland (UOKiK): collective-consumer-interest fines up to 10% of annual turnover, once it's transposed and enforceable.
Germany: administrative fines up to €75,000 for legal persons, per current commentary.
Cross-border (CPC / Omnibus): coordinated actions can reach up to 4% of annual turnover in the member states concerned.

What I'd actually do

If this were a client store on Poland/PLN, here's the path. It's a 1-2 hour job on staging, not a fire:

Install EU Order Withdrawal Button for WooCommerce on a clone first.
Turn on site-wide embed. Rename the page and button to "Odstąp od umowy tutaj" and the confirm to "Potwierdź odstąpienie od umowy". Labels are editable, no PL pack ships.
Check only name + order ID + email are required. Leave IBAN and reason off.
Wire real SMTP and confirm the timestamped acknowledgement email actually fires. The durable-medium email is the legal bit, so don't skip it.
Update your return-policy / terms pages to disclose the function and where it lives (Art. 6).
Cache-exclude the withdrawal page so the no-login form isn't served stale. If you're on a full-page cache, this matters - I wrote about the cache-bypass cookie logic in my WooCommerce performance stack post.
Keep refunds manual through your existing gateway. The form only registers the legal declaration.

On step 2: the winner lets you edit the button text in its settings and rename the page, which is the simplest route. If you'd rather pin the labels in code - handy when you manage several stores - a small gettext filter does it without a translation file. This works for any plugin that runs its strings through WordPress translation:

// Force Polish labels without shipping a .po file.
// Drop this in a tiny mu-plugin or your theme's functions.php.
add_filter( 'gettext', function ( $translated, $text ) {
    $pl = [
        'Withdraw from contract' => 'Odstąp od umowy tutaj',
        'Confirm withdrawal'     => 'Potwierdź odstąpienie od umowy',
    ];
    return $pl[ $text ] ?? $translated;
}, 20, 2 );

That's it. The good news is the hard part - figuring out which plugin to trust - is already done. WooCommerce will probably ship something native eventually, but #65443 has no roadmap, so I wouldn't wait for core on a deadline.

If you want more WooCommerce config wins while you're in there, my 30 WordPress & WooCommerce performance tips is a decent companion read.

FAQ

Do I need the withdrawal button if I'm a small Polish store?

Yes, in practice. The obligation applies to any business selling to EU consumers from 19 June 2026, regardless of size. Poland's own statute is delayed (see above), but the directive is binding and your cross-border EU sales are already covered. There's no small-shop exemption.

Can I just label the button "Cancel" or "Return"?

No. The directive points to clear wording like "withdraw from contract here" to open the form and "confirm withdrawal" to submit. Ambiguous labels like "Cancel" are likely treated as insufficient. In Polish, use "Odstąp od umowy tutaj" and "Potwierdź odstąpienie od umowy".

Is a footer link to my returns policy enough?

Not anymore. A policy page you have to read, or a "email us for the form" line, no longer satisfies the rule. You need a working digital function - reachable from every page, usable by guests without logging in, with a two-step confirm and a timestamped acknowledgement email.

Does the plugin handle the actual refund?

No, and that's fine. The withdrawal function only registers the legal declaration and timestamps it. The refund still goes through your normal WooCommerce flow and payment gateway, and the physical return and inspection rules are unchanged. Keep refunds manual.

Will WooCommerce add this to core?

Maybe eventually. There's an open enhancement request (#65443) but no roadmap or shipped support as of June 2026. I wouldn't wait for core on a deadline - install a plugin.

WordPress Manifesto - 15 Years In, Here's What's Actually Broken

Marcin Dudek — Tue, 26 May 2026 13:54:11 +0000

Originally published on marcindudek.dev

I've been doing WordPress for 15 years. I love it and I'm tired of it at the same time. Not tired in the "I'm moving to Webflow" way. Tired of the lies - the small ones and the big ones. The "free CMS", the "open source community", the "40% of the web" brag. All of it. Here's what's actually going on.

The "40% of the web" line is a cope

Yeah, it's probably true. But most of those sites are throwaway blogs and directory junk. WordPress makes it trivial to spin up a basic content site, so of course the number is huge. Quantity isn't quality. Stop quoting it like it proves something.

Core is broken

Vanilla WordPress, fresh install, no plugins - and XML-RPC is wide open. The moment your site goes live, bots start brute-forcing wp-login. You shouldn't need a plugin to not get owned on day one. That's not a minor gap, that's a design failure.

Then there's SEO. You need a plugin for basic meta titles. You need a plugin for descriptions. Meta tags. In 2026. There's no excuse for that. SEO should be native by now.

You can't just flip one switch to kill comments site-wide. The settings sprawl across multiple screens and are absurdly complex for a feature most sites don't even want anymore. A single "Comments: off" checkbox would save millions of hours of googling and plugin installs.

There's a full admin page at /wp-admin/options.php that lists every option in the database and lets you edit it. It's been there forever. It's actually useful. And there's literally no link to it anywhere in the admin UI. You either know the URL or you don't. That's just weird.

WordPress has Recovery Mode for when a plugin fatals your site. Nice feature - except the recovery link only goes to one admin email. A site can have ten admins, any of them can break something, but only the "main" admin gets the recovery email. If you're admin number two and you crash the site, you're locked out. Your only way back is FTP or SSH. In 2026. Bonkers.

And instead of fixing any of this, Automattic keeps bolting more React and builder tooling onto the editor. The wrong direction. What core needs is hardening, slimming, cutting dependencies. Maybe even a real fork into something modern. It's long overdue and nobody wants to say it out loud.

I tried contributing. There's a "good first bugs" list, so I picked one - an underperforming function, open for 8 years, with a couple of stale PRs sitting on it. I posted mine. Silence. If that's the on-ramp for new contributors, no wonder core moves like it does.

Free isn't free

Core WordPress is bare-minimum. To get a real, usable site you need a stack of plugins. Running a store? You need WooCommerce, a pile of Woo add-ons (because Woo doesn't ship with invoicing or most payment gateways), an SMTP plugin, a security plugin, 2FA, SEO, and something like ACF or Pods for custom content types.

Most of those plugins have a "free" tier that's a gateway drug. You hit a wall, then pay. Forty bucks here, sixty there. Individually cheap, but it compounds. And it's almost always a yearly subscription. So before your site earns a single euro, you're already locked into hosting, domain, and a stack of renewals.

"Just cancel the subscriptions" isn't a real answer. The moment a plugin stops updating and a vulnerability drops, your site is a sitting duck. Pay or get hacked. Those are the options.

Most site owners also end up paying for maintenance - because knowing how to configure all these plugins and fix the gaps between them is its own full-time skill. So "free CMS" quietly becomes hosting + domain + 6–10 subscriptions + a retainer. Let's stop pretending it's free.

And the market knows it. Core is free. Hosting is cheap because WordPress runs on ancient PHP and weak shared boxes. Themes are free. Plugins are free. So everyone expects everything around WordPress to cost nothing too - designing, implementing, cleaning up hacked installs, performance, SEO. All of it. Treated like it should cost nothing. That's a bad deal for everyone doing the actual work.

The GPL racket

Plugins are what makes WordPress different from every other CMS. In theory, a non-developer can buy hosting, click together a few plugins, and turn a blog into a shop, a directory, a booking system, whatever. That's incredible.

But try to actually sell a plugin and you hit a wall. People don't want to pay. And the GPL crowd will tell you that you can't sell the code anyway - you can only sell "support" or "updates". That's bullshit. If your plugin is good and stable, you shouldn't be forced to sell babysitting on top of it. You're selling a license to use software, like every other commercial software on earth.

Meanwhile entire scammer networks buy one license, strip it, and resell the same plugin on hundreds of "GPL sites" for a few bucks. Basically nothing you can do about it, because it's PHP and anyone with a text editor can edit a plugin.

Automattic also gatekeeps wordpress.org. Plugins can get banned if the directory team doesn't like how they're sold. A loud chunk of the community - moderators, GPL purists, people who personally benefit from the status quo - will fight any attempt to charge for code by waving the license at you. The people benefiting most from that setup aren't the small developers. They're the resellers and the platform owners.

The community fiction

Site owners, freelancers, agencies, theme shops, plugin shops, core contributors, hosts - all lumped together as "the WordPress community". WordCamps, WordUps, meetups everywhere. On the surface, one big family.

Underneath, it's tense. Plugin developers ally with other plugin developers because they share enemies (the GPL resellers), but they're also competing with each other, so the alliances are shallow. Plugin devs and theme devs are in permanent conflict because there's no clean line between what a theme should do and what a plugin should do. I've opened sites with custom CSS in five different places - core, theme, three plugins - all fighting each other. That's not a community. That's a turf war with a friendly logo on top.

And the bar to call yourself a "WordPress developer" is on the floor. If you can install WordPress and pick a theme, you can call yourself one. There's no real distinction between that and someone who can build a custom theme from scratch, write a real plugin, or debug core. After 15 years, it's genuinely hard to differentiate yourself in a market where the word means nothing.

Automattic's two faces

The mission is "free and open source, for everyone". Meanwhile Automattic runs WordPress.com for profit, takes huge sponsor money, and quietly buys up plugin companies. They're a for-profit business extracting enormous value from an ecosystem they frame as community-owned. You can't preach open source on stage and run a hosting empire backstage and pretend there's no tension.

Here's the part that gets me. WordPress looks open source, but in practice it's basically in Automattic's hands. If you're a small plugin developer, you're on your own. But the second your work gets popular and solves a real pain point, Automattic can just take it. They can fold it into core. They can copy it and ship their own version. They can buy you. The best case for you is they throw some money your way - and they don't even have to do that.

Beside Automattic, the big winners are scammers, GPL resellers, and a handful of hosting giants. Everyone else is small fries. Freelancers can still pull in a few hundred bucks building sites - but that tier is being eaten by AI fast. The money is consolidating: Automattic, the Elementor owners, a couple of big hosts. Hundreds of thousands of people contribute to the ecosystem. A handful of companies capture almost all the value. That's not a community. That's a supply chain.

The WP Engine drama showed exactly how this works. Grow big enough inside the WordPress world and eventually one of Automattic's tentacles comes out, grabs you, and either devours you or kills you. It wasn't a one-off. It was the mask slipping. It's not a family. It's a pond, and there's one big fish in it.

Users lose too

Most of this is from a developer's seat, but users are paying for this mess just as much. Because core is so bare-minimum and because "anyone can build a WordPress site", the experience is wildly inconsistent. One WordPress site is a polished, fast, accessible portal. The next one - same CMS - is a slow, broken disaster hosted on the cheapest shared box by someone building their second site ever. Users have no way to tell the difference until they're on the page.

If core had real quality baked in - speed, SEO, security, sane defaults - the floor would be much higher and every site in the world would benefit. Right now "it's WordPress" tells a user almost nothing about what they're about to experience. And that's on core.

What I actually want

Two things. Either serious competition - a truly open CMS, genuinely community-owned, where the only thing you pay for is hosting. That would break this whole weird economy overnight. Or WordPress core finally grows up: lean, fast, secure, SEO-aware by default, with a clean line between core, plugins (features), and themes (layout). Right now everything is tangled and it feels toxic to work in.

The uncomfortable truth is that nobody in power actually wants core to be good. If core shipped proper SEO, proper performance, proper security - most small plugin businesses lose their moat and disappear. So maybe WordPress is partly a facade. A smoke screen that lures small fish in, lets them grow a bit, then eats them when they get big enough to matter.

I'm not leaving. I've spent 15 years on this thing. It's a huge part of my life and I'm actually good at it. But I'm done pretending it's something it isn't. WordPress is still the best tool for a huge chunk of the web. I just want it to stop lying about what it is.

Revolution or collapse

Here's the part nobody in the WordPress world wants to hear. The era where WordPress had no real alternative is ending. AI is already writing whole sites, whole themes, whole plugins. Every month the tooling gets better. The moat that protected the WordPress empire - "it's the easiest way to build a site" - is evaporating. Fast.

Long term, I see exactly two paths:

Revolution. The community wakes up, pushes back on the Automattic-owned "open source" theater, forces core to become genuinely lean, fast, secure and SEO-aware, draws a clean line between core/plugins/themes, and opens the contributor pipeline to people who actually want to fix things. WordPress earns its 40% by being good, not by being entrenched.

Collapse. Nothing changes. Core keeps bloating. The contributor pipeline keeps ghosting people. Automattic keeps extracting. Small devs and small agencies get picked off one by one by AI and by the big players. And WordPress slowly turns into the Roman Empire of the web - still huge on a map, still quoting old stats, rotting from the inside while the world moves on.

This is a wake-up call. Not a goodbye. I'd rather see the revolution. But if nothing changes, the collapse is already on the calendar - we're just arguing about the date.

Tags: wordpress · opinion · manifesto · open-source · automattic · gpl