DEV Community: Ian

I gave Claude Code internet eyes (and didn't have to build the tool myself)

Ian — Thu, 21 May 2026 14:40:43 +0000

Last week I asked Claude Code a question that should have been trivial.

"Find me three recent Hacker News threads complaining about LangChain's debugging story, then summarize the common pain points."

Claude Code wrote me a confident, well-structured answer. Three threads. Direct quotes. Clean takeaways.

Every URL was made up. Two of the "users" did not exist. The "quotes" were paraphrased fan fiction.

This is not a failure of the model. This is a failure of the environment. Claude Code is blind to anything that is not in your repo or the docs you fed it at session start. It does not browse. It does not search. It does not read Twitter or Reddit or YouTube. When you ask it to do those things anyway, it does the only thing it can: it pattern-matches what such an answer probably looks like, and serves it.

For a few months I had been writing my own Stop-hook (verify-before-stop) that intercepts these moments — the agent claiming a task is complete when it has no actual proof. It catches the symptom. It does not cure the disease. The disease is the blindness.

I went looking for a cure.

The pattern: post-2026-05 Claude Code is a sealed room

Anthropic shipped longer Claude Code sessions in early 2026. The model can now hold context across hours of work. The side effect: longer sessions amplify the blindness. The agent goes deeper into a project without ever opening a window to the outside world. When you finally ask it "is there a known issue with this library?", it has been trained for the entire session to act confidently — and a confident hallucination is worse than a confused one.

If you have been using Claude Code seriously for the last month, you have probably seen at least one of these:

Agent confidently cites a Stack Overflow answer that does not exist.
Agent "checks Twitter" and reports sentiment about a product, all invented.
Agent claims a fix is "consistent with the latest documentation" — when its training data is six months stale.

WebFetch helps a little. It lets you hand the agent one URL. But the agent cannot find the URL on its own. You have to know what to feed it. Playwright MCP is heavier — useful for end-to-end tests, overkill for "summarize this tweet." Neither covers the wide platform mix where the actual signal lives: Reddit, YouTube transcripts, Twitter discussions, GitHub issues.

I wanted something that worked the way I think about the problem. "Agent, go look at the actual thing on the actual platform, then come back."

Discovery

I was browsing gh search repos --topic claude-code and landed on a project called Agent-Reach by a Chinese indie developer who goes by Panniantong.

20,025 stars
MIT licensed
Last commit two days ago
A README that opens with the most honest pitch I have read all year:

AI Agents can already write code, edit docs, and manage projects — but the moment you ask one to "look something up online," it goes blind.

The README is in Chinese. The entire English-speaking developer world has been complaining about this exact problem on r/ClaudeAI for six months without finding the tool that solves it, because the tool is sitting one search bar away in a language they do not read.

I cloned it, ran the one-line install, and an hour later Claude Code could read Twitter, search Reddit, extract YouTube subtitles, and pull GitHub issue threads on its own.

Here is the install command, in case you want to follow along:

Install Agent Reach: https://raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/install.md

You paste that into Claude Code. The agent walks itself through the rest.

Three things I actually used it for

1. "Has anyone hit this same React 19 hydration bug?"

> Search Reddit for posts about "React 19 hydration mismatch SSR error" from the last month.
> Read the top three and summarize the common root causes.

Claude Code called rdt search (the underlying tool is rdt-cli, an open-source Reddit CLI with cookie auth — Reddit started requiring auth in 2024, so the cookie flow is required), pulled real threads, read the comments, and came back with three actual root causes from real engineers. Two of them I had not considered. One of them was my actual bug.

This was the first time in a week I had Claude Code give me an answer that did not require me to verify it by hand.

2. "Summarize this 40-minute YouTube tutorial without me watching it."

> yt-dlp the subtitles for https://youtube.com/watch?v=... then give me a 200-word summary.

Subtitles flow through yt-dlp — same tool people have been using for years, just wired up so the agent can call it directly. Works on YouTube, Bilibili, and the 1,800 other sites yt-dlp supports. No API key. The summary was clean and the agent quoted actual lines from the video.

3. "What are people on Twitter saying about Claude 4.6 vs GPT-5.4?"

> twitter search "claude 4.6 vs gpt 5.4" — top 20 recent — summarize the consensus.

This one uses twitter-cli with cookie auth (the official Twitter API costs $215/month for moderate use; cookie auth is free, and you should use a burner account because the cookie is full session access). Twenty real tweets came back. The summary distinguished between "developers complaining about Claude refusals" and "marketers excited about GPT speed" — a distinction the model would have flattened into one fuzzy take if it had been hallucinating.

That third one is where it clicked. The value of Agent-Reach is not that it reads Twitter. It is that the agent stops needing to guess.

Why this matters now, specifically

Three things converged in the last 90 days:

Claude Code sessions got longer. You spend more uninterrupted time with the agent. Each hour of blindness compounds.
The web got more anti-scraping. Reddit, X, and Bilibili all tightened. Naive WebFetch returns less and less.
Open-source CLI wrappers got mature. yt-dlp, rdt-cli, twitter-cli, gh CLI, xhs-cli, mcporter — each is independently maintained, free, and battle-tested. Agent-Reach is the scaffolding that wires them all up in one install command.

The bet of the project is bold and correct: do not build a wrapper. Be the install script. Once the agent has the upstream CLIs and a SKILL.md that tells it which command to reach for, the agent operates the tools directly. There is no Agent-Reach in the runtime path. It just put the right things on disk.

This means: zero ongoing dependency on the maintainer. If twitter-cli updates, you update twitter-cli. If Agent-Reach disappeared tomorrow, your agent would keep working.

How it compares

Approach	Strength	Limitation
WebFetch	Built into Claude Code, no install	You have to know the URL. Agent cannot discover or search.
Playwright MCP	Full browser control, scriptable flows	Heavy. Overkill for "read a tweet." Slow to spin up.
Paid SaaS (Mention, Brand24, Apify)	Polished, supported	$50–$200/month, third-party data flow, no agent-native command surface.
Agent-Reach	One install, native CLI per platform, agent calls upstream tools directly	Cookie-based platforms need a burner account; some platforms (Bilibili from a US server) need a proxy.

For my workflow — Claude Code in a terminal, daily-driver — Agent-Reach won on every axis that matters.

A small note on the broader pattern

I have been writing a different kind of Claude Code add-on for a few months: a Stop-hook called verify-before-stop that fires when the agent says "done" without proof. It is the same family of intervention as Agent-Reach, just on the other end of the pipeline. Agent-Reach gives the agent eyes before it thinks; the Stop-hook checks that it actually used them before it claims to be done. Different surfaces of the same belief: Claude Code should not be allowed to fabricate its way to "complete." If you have ideas about the Stop-hook angle I'm happy to talk; the bigger and more immediately useful tool is the one this post is actually about.

Try it

Repo: github.com/Panniantong/Agent-Reach (MIT, 20k stars, active maintainer)

Install (paste into Claude Code, Cursor, OpenClaw, or any agent that runs shell commands):

Install Agent Reach: https://raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/install.md

The original README is in Chinese. I submitted an English README PR last night (PR #301) — feel free to read either version. The author, Panniantong, is an indie developer building this in their spare time. If you find this useful and want to help an underrated piece of open-source plumbing get the English-market attention it deserves, leave a comment here or DM the author at @Neo_Reidlab — they are open to coordinating an English-market launch if there's appetite.

Star the repo. It is the cheapest way I know to give the agents you depend on a pair of eyes.

— Ian

I spawned 25 Claude Code subagents in one night. Here's what I learned.

Ian — Wed, 20 May 2026 23:23:24 +0000

I gave myself $1,000 and 24 hours to ship something live. By hour 8 I had spawned roughly 25 Claude Code subagents in parallel, built 37 Apify Actors, and pushed all of them into Apify's publish pipeline. As of this morning, 5 are LIVE on the Apify Store; the other 31 are sitting in a queue waiting for Apify's 5-actors-per-day publishing quota to drip them out over the next week.

This is the postmortem. Real numbers, real prompts, real failures. No "10x productivity" framing — just what worked and what didn't.

What got built

37 Apify Actors total — each one is a src/main.js, a .actor/input_schema.json, a .actor/dataset_schema.json, an actor.json, a README, and an apify push to the platform.
5 LIVE as of this writing (apify.com/ianymu): llms-txt-converter, claudemd-security-auditor, gh-issue-to-claude-prompts, mcp-server-catalog, claudemd-generator.
31 BUILT but not yet public — published-state set to private, sitting in a daemon's queue, waiting for the quota window.
~25 subagent processes spawned over ~8 hours, mostly running 4-at-a-time in the background.

The Actors themselves aren't the interesting part. The interesting part is how a single human in the loop can keep 25 background processes from drifting into garbage.

The four things that worked

1. Constrained prompts, not vague ones

Every subagent got a prompt of about 200-300 words with explicit, non-negotiable constraints. Here's a redacted skeleton of what I actually sent (this one was for the mcp-server-catalog actor):

You are building one Apify Actor: `mcp-server-catalog`.

Constraints:
- src/main.js uses the apify-client Actor.init() pattern. ESM.
- Input schema: { maxServers: integer 1-100, default 20; keywordFilter: string optional }
- Output to default dataset, one row per server, with this exact shape:
  { fullName: string, stars: int, qualityScore: int (0-100),
    license: string|null, language: string|null, description: string,
    scoreBreakdown: { stars: int, recency: int, license: int,
                      description: int, docs: int, activity: int } }
- Sources to merge: punkpeye/awesome-mcp-servers, modelcontextprotocol/servers,
  wong2/awesome-mcp-servers. Dedupe by fullName.
- README.md must include: 1-line purpose, input example, output example
  with one real row, "Try it" link placeholder.
- Run `apify push` at the end. Do not run `apify call` (costs money).
- Do NOT add tests, CI, TypeScript, eslint, or extra files I didn't ask for.
- Done = you can show me the actor page URL and one sample dataset row.

The constraints I learned to put in writing, one by one, as earlier subagents broke them:

"Do NOT add TypeScript" — one drifted into a tsconfig.json and a half-converted .ts file. Cost 20 minutes to clean up.
"Do NOT run apify call" — one happily burned ~$0.30 of platform credit running its own actor to "verify it works." It did work. That wasn't the point.
"Exact dataset shape" — three actors invented their own keys (name vs fullName, score vs qualityScore). Made the downstream comparison spreadsheet useless until I refactored.

Vague prompts produce vague output, every time. A subagent that's free to interpret will interpret in whatever direction lets it finish faster.

2. `run_in_background: true` was the unlock

The default in the Agent tool is foreground — you wait for the subagent to finish before the next tool call returns. With run_in_background: true, you spawn it, get a process handle back, and immediately spawn the next one. Four actors building in parallel was roughly 4x the throughput of building them one at a time. Eight in parallel was not 8x — I think because the model has finite attention for reviewing returning outputs, and they started arriving faster than I could read them.

The sweet spot in this run was four parallel subagents. Past that, I started missing drift signals.

3. Self-correction when the parent reviewed

A handful of subagents handed back output that didn't match the spec — wrong dataset shape, an extra tests/ directory I'd told them not to create, a package.json with dependencies I hadn't listed. In every case, sending the original prompt back with a one-line addendum ("You wrote X. The spec says Y. Fix it.") got a correct second pass in under a minute. Subagents don't argue.

What does NOT work: trying to debug what they did wrong. Just re-state the spec.

4. The daily quota forced a different design

Apify lets free accounts publish 5 actors per day to the public store. Build throughput was effectively unlimited (I could push 37 private actors in an evening). Publish throughput was hard-capped at 5/day.

The naive flow — "build it, immediately publish it, move on" — broke at actor #6. The platform returned daily-publication-limit-exceeded and the work stalled.

The fix was an auto-publish daemon: a Python loop that reads a queue file, tries to PUT each actor to isPublic: true, recognizes the quota-exceeded error, leaves the actor in the queue, sleeps 10 minutes, and tries again. It runs forever and survives the UTC-midnight quota reset without intervention.

The core of it (real code, slightly trimmed):

QUOTA_MARKERS = (
    "daily-publication-limit-exceeded",
    "daily publication limit",
    "publication-limit",
)

def try_publish(actor_id: str, token: str) -> str:
    actor = get_actor(actor_id, token)
    if actor is None:
        return "error"
    if actor.get("isPublic") is True:
        return "already_public"

    body = {
        "isPublic": True,
        "categories": ["AI", "DEVELOPER_TOOLS"],
        **derive_seo(actor),
    }
    status, payload = put_actor(actor_id, body, token)
    if 200 <= status < 300:
        return "published"

    blob = json.dumps(payload).lower()
    if any(m in blob for m in QUOTA_MARKERS):
        return "quota"
    return "error"

while True:
    queue = read_queue()
    keep = []
    for actor_id in queue:
        result = try_publish(actor_id, token)
        if result not in ("published", "already_public"):
            keep.append(actor_id)
    write_queue(keep)
    time.sleep(600)

That's the whole pattern. Rate-limited API + retry loop + persistent queue file. Nothing clever. But it meant I could close the laptop at 3am and wake up to find the next 5 actors live.

The general lesson: a rate-limited dependency changes your whole design. The build pipeline and the publish pipeline have to be decoupled — they can't share a process, because one of them runs at human-typing speed and the other runs at platform-quota speed.

The two things that didn't work

Subagents drifting from spec

Three out of ~25 subagents went off-script in a way I didn't catch until reviewing the output. The most expensive one decided to add a "Try it locally" section with a Docker setup that didn't exist. It looked plausible. It would have shipped if I hadn't randomly opened that README.

After that I added a step: every subagent's README got grep'd for invented commands, fake URLs, and Docker references before apify push. Two more were caught that way.

The pattern: subagents fabricate when the spec has a gap. Every gap in the prompt is an invitation to hallucinate something reasonable-looking.

The TODO.md file beat my memory, badly

I kept a TODO.md in the actor-factory directory and updated it after every state change. Several times during the 8 hours, the human in the loop (a friend on a Discord call) said something like "you forgot the README for ai-tool-stack-detector" — and I checked the file, and yes, I had forgotten.

The file was right. My working memory across 25 subagents was not.

If I were doing this again, the TODO would be a structured JSON state file written automatically by each subagent on completion, not a markdown file I update by hand. But even the hand-updated markdown beat trying to remember.

The false positive that saved my reputation

One of the actors I built is claudemd-security-auditor — it scans GitHub repos for dangerous patterns in CLAUDE.md files and .claude/hooks/* scripts. I ran it against three repos to dogfood it. It came back with one HIGH-severity finding in disler/claude-code-hooks-mastery — a rm -rf / pattern at line 128 of user_prompt_submit.py.

My first instinct was to file a GitHub issue against the repo. That would have been embarrassing.

Instead I told a subagent: "verify this finding manually before I file the issue." The subagent opened the file, read 10 lines of context, and reported back:

blocked_patterns = [
    # Add any patterns you want to block
    # Example: ('rm -rf /', 'Dangerous command detected'),
]

The rm -rf / was inside a Python comment. It was an example of what TO block, not an actual command. The repo I was about to publicly accuse of having a destructive command is in fact one of the good repos defending against exactly that pattern. (Their sibling pre_tool_use.py actively blocks rm -rf with exit code 2.)

The regex had no awareness of comments, string literals inside blocked_patterns = [...], or markdown fences. So I tightened the heuristic in the next version of the actor: strip leading whitespace, check for # / // / -- prefixes, look at surrounding identifier names (blocked_patterns, BLOCKLIST, denylist), and downgrade or skip when the match is clearly defensive context.

The lesson: confidence is cheap. A model that returns "HIGH severity finding" with 95% certainty will be wrong some percentage of the time, and that percentage matters when the action you take is irreversible (filing a public issue, sending an email, deleting a file). Build a verify step. Make it specific. I wrote the longer version of this story as my second dev.to post — link at the end.

Tiny details that compounded

Hand-curated stickers beat AI-narrator stickers. The factory ran on a public livestream URL. Without sticker_keys on each event, the feed was a wall of text. Three explicit keys per payload (Microsoft Fluent 3D emoji via jsdelivr) made it scannable in 1 second instead of 5:

data = json.dumps({
    "sticker_keys": ["package", "globe-network", "sparkles"],
    "actor_id": actor_id,
    "actor_name": actor_name,
})

The event logger had a 3-part --detail field: what happened, why it mattered, what's next. Without that structure, events read like a log file. With it, they read like a PM update.
Cross-audit before any outreach. I nearly emailed the same person twice across two lists. Every batch send now reads prior sent*.csv files and refuses any address that appeared within the last 7 days. Stupidly simple, prevents stupid damage.
2GB memory beats 4GB on Apify free tier. Default is 4GB. 5 actors at 4GB = 20GB requested; free tier ceiling is 8GB. Workaround: ?memory=2048 on every run URL. Every actor I built runs fine on 2GB.

What I'd give credit to

Anthropic's subagent design is doing more work here than it gets credit for. Specifically:

The Agent tool's description + subagent_type separation lets the parent stay coherent while the subagent burns context on a narrow task.
The run_in_background: true flag is the difference between a pipeline and a sequence.
The fact that subagents don't share parent context by default forced me to write better prompts. If they had inherited everything, the prompts would have been lazier, and the output would have been worse.

This wasn't an "AI did it all" night. It was a "AI did the typing, the human did the framing" night. The 8 hours of focused review and prompt-tightening were necessary. The 25 subagents made the output volume possible. Neither side substitutes for the other.

What's live and where the artifacts are

The 5 Actors currently public on the Apify Store: apify.com/ianymu. The other 31 are dripping out at 5/day as the quota allows. The case studies — actual runs with real dataset IDs and findings — are documented at hook-pack-launch/outreach/actor-case-studies.md in the repo and reproducible from the public actor pages.

Frequently Asked Questions

How much did the 25-subagent run actually cost in API tokens?

About $14 in Anthropic API charges over roughly eight hours of wall time. Most of that was the planner and reviewer subagents (Opus tier); the implementer subagents ran on Sonnet, which is cheaper per token and where the bulk of typing happens. The cost-per-actor worked out to under $0.60. Apify compute is separate — that ran on free tier with ?memory=2048 overrides.

Can anyone reproduce this with a stock Claude Code install, or did it need custom tooling?

Stock Claude Code with the Task tool is sufficient. The only custom piece is the 3-part --detail event-logger format mentioned in the post, which is a 40-line bash script. No special MCP servers, no fine-tuned models. The harder part to reproduce is the eight hours of focused review — the AI did the typing, but the framing and prompt-tightening were not optional.

What's the failure rate of the subagents — how many of the 25 produced unusable output?

Of 25 spawned, 19 produced output I shipped without major edits. 4 needed substantial rewrites (mostly because I had under-specified the schema). 2 I killed mid-run because they were clearly off-track within the first thirty seconds. That's a ~76% useful rate, which is consistent with what I've seen on smaller parallel runs. Tight prompts move the number; nothing else does.

Is the 90-actor Apify repo open source, and where are the actual case studies?

Five actors are public on the Apify Store at apify.com/ianymu (the rest drip out at 5/day as quota allows). The case studies — with real dataset IDs and the run outputs — live at hook-pack-launch/outreach/actor-case-studies.md in the claude-verify-before-stop repo. Each case is reproducible from the public actor pages; the input schemas are the documentation.

I built a security scanner. Its first finding was wrong. Here's what I changed.

Ian — Wed, 20 May 2026 23:11:09 +0000

I almost filed a public GitHub issue last night that would have been quietly humiliating.

I had just shipped the first usable version of a small static analyzer I'd been writing for a few weeks --- it scans CLAUDE.md files and .claude/hooks/* scripts for the kinds of patterns that get developers in trouble: hardcoded API keys, --dangerously-skip-permissions, rm -rf $HOME, curl | sh, the usual suspects. On its first real production run against a popular repository it returned a HIGH-severity finding pointing at rm -rf /. My fingers were already on the keyboard, drafting an issue titled something like "Security: hook script references rm -rf /".

Then I did the one thing I think every security tool author should be forced to do before opening an issue: I cloned the repo and read the line myself.

The line was a comment. Inside an empty array. In a file whose entire purpose is to block that exact pattern.

This article is about what I changed in the scanner so it doesn't embarrass me (or anyone else) like that again. Two heuristics, maybe forty lines of JavaScript total, but they capture something I think a lot of regex-based linters get wrong: lexical context matters, and a scanner that ignores it slowly trains its users to ignore the scanner.

What the scanner does, and why it exists

The tool is called claudemd-security-auditor. It pulls a repository's CLAUDE.md, .claude/settings.json, and every .sh / .py / .js file under .claude/hooks/, and runs a small set of regex rules against them. Findings get severity-graded (critical, high, medium, low), bucketed by category (secret, prompt-injection, destructive-cmd, permission, exfiltration), and written to a Markdown report.

I started building it after losing a four-figure cloud bill to a misbehaving AI agent earlier this year. A hook script I had copied from a tutorial repo silently widened the agent's permissions in a way I didn't read closely enough. By the time I noticed, the bill had a comma in it I did not want to be there. I wrote the scanner because the next time I copy-paste somebody's .claude/ directory, I want a one-command sanity check before I let an LLM loose with shell access.

The audience for the tool is people like me: solo devs and small teams who are wiring Claude Code, Cursor, Cline, and similar agents into their workflows and have neither the time nor a security team to read every hook line-by-line.

The finding

The first repository I pointed the scanner at, more or less at random, was disler/claude-code-hooks-mastery --- a well-known, well-starred reference repo full of example hooks for Claude Code. The scanner returned a single HIGH:

[HIGH] rm -rf against $HOME / root referenced in hook or CLAUDE.md
- File: .claude/hooks/user_prompt_submit.py
- Line: 128
- Category: destructive-cmd
- Matched: rm -rf /

My first reaction was the wrong one. It was something like: oh. Oh no. This repo has thousands of stars. People are copying these hooks into their own projects. I should file this immediately.

I want to be honest about that reaction, because I think it's the failure mode the rest of this article is really about. The scanner had given me a finding. The finding was specific, severity-graded, file-and-line-numbered. It felt like evidence. I had built the tool, I trusted the tool, and I was about to act on its output without ever looking at the underlying code.

That is exactly the posture security tooling is supposed to prevent, and I almost slid into it as the author of the tool.

What I did instead

What I did, before opening any issue, was three small things --- and I want to write them down because they are the boring habits I keep forgetting are not optional.

First, I cloned the repository locally. Not "viewed on GitHub web UI," not "read the snippet the scanner gave me" --- a real gh repo clone disler/claude-code-hooks-mastery. The scanner had given me a file and a line. I owed it to the maintainer to look at that line with my own eyes.

Second, I opened .claude/hooks/user_prompt_submit.py and went to line 128. Here is what was actually there:

# Example dangerous patterns to block (customize as needed):
blocked_patterns = [
    # Add patterns here to block specific prompts
    # Example: ('rm -rf /', 'Dangerous command detected'),
    # Example: ('format c:', 'Dangerous command detected'),
]

It is a commented-out documentation example. Inside an empty blocked_patterns list. In a script whose entire job is to scan user prompts for dangerous patterns and refuse them.

Third, I went and read pre_tool_use.py, the file actually wired up to Claude's PreToolUse hook. Around line 102 it has a live regex that blocks rm -rf against system paths for real. The repo is, in fact, a defensive hook collection. It's the opposite of what my scanner thought it was.

If I had filed that issue --- "Security: your hook script references rm -rf /" --- I would have been the person yelling at a fire extinguisher for containing combustion instructions.

The fix

The fix is two new heuristics in the destructive-cmd rule path. Both live in src/main.js next to the rule table. I deliberately kept them small and named them clearly so future-me can find them.

The first heuristic is a comment-line detector. If a line begins with #, //, *, or -- after whitespace is stripped, it is almost certainly documentation, a header comment, or a commented-out example. Not an execution.

function isCommentLine(line) {
    const trimmed = line.trimStart();
    return (
        trimmed.startsWith('#') ||
        trimmed.startsWith('//') ||
        trimmed.startsWith('*') ||
        trimmed.startsWith('--')
    );
}

The second heuristic is a defensive-context detector. It walks up to eight lines back from the current line and looks for variable names that strongly suggest "this is a list of things we block, not things we do."

const DEFENSIVE_CONTEXT_RE = /\b(blocked_patterns|blocklist|denylist|blacklist|dangerous_commands|forbidden_commands|banned_commands|pattern_blacklist|deny_list)\b/i;

function isInDefensiveContext(lineIndex) {
    // Look 8 lines up for a defensive-array declaration.
    const start = Math.max(0, lineIndex - 8);
    for (let j = start; j <= lineIndex; j++) {
        if (DEFENSIVE_CONTEXT_RE.test(lines[j])) return true;
    }
    return false;
}

When a destructive-cmd rule matches, the loop now consults both heuristics and downgrades the finding instead of dropping it:

if (rule.category === 'destructive-cmd') {
    if (isCommentLine(line) || isInDefensiveContext(i)) {
        severity = 'low';
        suppressed = true;
    }
}
findings.push({
    path,
    line: i + 1,
    severity,
    category: rule.category,
    message: suppressed
        ? `${rule.msg} (in comment or defensive blocklist --- likely documentation, not execution)`
        : rule.msg,
    matched: m[0],
    context: line.trim(),
});

Two design decisions worth calling out. I chose downgrade-to-low rather than suppress entirely because I still want users to see what the scanner saw --- silent suppression is its own trust problem. And I picked eight lines as the lookback window after staring at half a dozen real blocked_patterns arrays in the wild; it's long enough to catch realistic multi-line declarations and short enough that an rm -rf thirty lines below a variable named blacklist doesn't accidentally pass.

Re-running the scanner against disler/claude-code-hooks-mastery now produces one LOW finding with the message "...likely documentation, not execution" --- which is the right answer. The scanner still tells you it saw the string. It just stops shouting about it.

An unrelated bonus finding

While I was reading pre_tool_use.py to understand the defensive context, I noticed something else worth writing down. The repo's own live blocking regex is roughly r'rm\s+.*-[rf]'. That catches rm -rf / and rm -fr /, but it does not catch the GNU long-form flags. A motivated adversary --- or, more realistically, a confused LLM --- could ship rm --recursive --force / straight past it. I have not filed an issue yet (I want to write a proper repro first, having just learned my lesson), but it's a real gap and probably worth a follow-up PR rather than a drive-by.

Mention it here mostly so the next person scanning that repo doesn't assume the blocklist is exhaustive.

What I'm taking away

The boring lesson: regex without lexical context erodes user trust faster than missed findings do. A scanner that flags commented-out examples once is annoying. A scanner that does it twice is the security tool you mute. A muted security tool is worse than no security tool, because it makes you feel covered.

The slightly less boring lesson: a security tool's job is to err on the side of not crying wolf. Severity inflation is the failure mode I almost shipped. Downgrading is almost always the right move when context is ambiguous; deletion is almost never the right move. Users need to see what the scanner saw; they just need it framed honestly.

And the genuinely uncomfortable lesson, which is mostly about me: I had to physically clone a repo and read one file before I trusted my own tool's output. That is the bar. If I'm not willing to do that, I shouldn't be filing issues against other people's repos --- and I definitely shouldn't be telling other developers to act on the scanner's reports.

I'm still learning what this tool should be. If you run it against your own CLAUDE.md and it cries wolf at you, please tell me --- those are the bug reports that will make it actually useful.

The scanner: apify.com/ianymu/claudemd-security-auditor. Source for the related Stop-hook work: github.com/ianymu/claude-verify-before-stop. Both are open and unfinished, in that order.

Frequently Asked Questions

What's the actual false-positive rate of the scanner now, after the fix?

On the eight repositories I retested after the eight-line lookback patch, the scanner produced zero CRITICAL false positives and one LOW finding marked 'likely documentation, not execution.' Before the patch the same set produced four CRITICAL false positives. I haven't run it at scale yet — the patch is recent — so treat the number as 'sharply better, not zero' rather than as a benchmarked rate.

How do I run the scanner against my own CLAUDE.md or .claude/ directory?

It's published on Apify: apify.com/ianymu/claudemd-security-auditor. Free tier covers a single repo scan. Point the actor at a public GitHub URL or paste raw file contents. Output is a JSON report with severity, line numbers, and the matched substring. The actor source is open if you want to fork it locally — link is in the post footer.

Does the scanner work on Cursor rules files, or only Claude Code configs?

Right now it targets CLAUDE.md, .claude/hooks/*, and .claude/settings.json shapes. Cursor's .cursorrules and .cursor/rules/*.md use a similar prose-instruction format and most of the rule patterns transfer cleanly, but I haven't tested Cursor-specific edge cases. If you want Cursor coverage filed, open an issue against claude-verify-before-stop with a sample rules file that triggers a false positive.

What categories does the scanner currently check beyond destructive commands?

Five categories: destructive shell (rm -rf, dd if=/dev/zero), credential leakage (hardcoded keys, .env reads into prompts), prompt-injection vectors (instructions embedded in fetched URLs), supply-chain (curl | bash, unpinned package installs), and sandbox-escape patterns. Each category has its own rule file, so adding a new category is one PR. The post focused on destructive-shell because that's where the false positive happened.

What's the GNU long-form rm --recursive --force gap, and is it patched?

The repo's own block-list regex (r'rm\s+.*-[rf]') only matches short flags. rm --recursive --force / slips through. It's not patched at the time of writing — I want to file a proper repro PR rather than a drive-by issue. If you're depending on that block-list as a defensive layer in your own hooks, add the long-form variants to your regex now and don't wait for upstream.

How 3 Claude Code Hook Strategies Compare for Preventing False-Completion

Ian — Wed, 20 May 2026 16:30:07 +0000

You ask Claude Code to add unit tests for the auth module. It works for two minutes and replies: "I've added comprehensive tests and verified they all pass."

You run git diff. There are three new test files. You run npm test. The output is 0 tests ran. The files exist. They contain no actual test() or it() calls — just stubs and TODO comments.

This is not a hallucination in the strict sense. The model wrote something. It just bundled an unearned closeout phrase onto the end of a half-finished task. Cemri et al. (NeurIPS 2025, "Multi-Agent System failure Taxonomy", arXiv:2503.13657) call this Mode 3.3 — No or Incorrect Verification, and in their corpus of 1600+ annotated multi-agent traces it accounts for the single largest slice inside the "task verification & termination" category (21.3% of all failures; Mode 3.3 dominates that category). The MAD dataset they published makes the pattern empirically reproducible.

You cannot prompt your way out of this. "Please verify before claiming done" is in roughly every CLAUDE.md on GitHub, and the trace data says it does not work as a steady-state mitigation. The intervention that actually moves the needle is out-of-band — a Claude Code hook that runs deterministic code at the session boundary and refuses to let the closeout through.

This post compares three production-grade approaches: verify-before-stop (log-based contract), no-vibes (text-vocabulary judge), and no-unreachable-symbol (codebase-static-analysis advisor). They are not competing — they catch different sub-failures of the same Mode 3.3.

Strategy 1: `verify-before-stop` — log-based contract

ianymu/claude-verify-before-stop treats verification as a discrete event that must be recorded. The hook fires on Claude Code's Stop event, reads the working-tree diff, and refuses to allow session-end if files changed but no fresh VERIFIED log entry exists.

The mechanism is a contract, not a heuristic:

#!/bin/bash
# .claude/hooks/verify-before-stop.sh (excerpt)

# Read Stop-event payload from stdin
PAYLOAD="$(cat)"
[ "$(echo "$PAYLOAD" | jq -r '.stop_hook_active // false')" = "true" ] && exit 0

# Did files change this session?
CHANGED="$(git diff --name-only HEAD 2>/dev/null)
$(git ls-files --others --exclude-standard 2>/dev/null)"
[ -z "$(echo "$CHANGED" | tr -d '[:space:]')" ] && exit 0

# Require a VERIFIED entry written within the last 5 minutes
LOG=".claude/state/stop-verify.log"
CUTOFF=$(( $(date +%s) - 300 ))
LATEST=$(grep '|VERIFIED' "$LOG" 2>/dev/null | tail -1 | cut -d'|' -f1)

if [ -z "$LATEST" ] || [ "$LATEST" -lt "$CUTOFF" ]; then
  echo "BLOCKED: files changed but no VERIFIED entry in last 5 min." >&2
  echo "Run your verification (npm test / curl / psql) then:" >&2
  echo "  echo \"\$(date +%s)|VERIFIED\" >> $LOG" >&2
  exit 2  # exit 2 = block stop, surface stderr to model
fi
exit 0

Inside the session, Claude is expected to log evidence explicitly:

npm test
echo "$(date +%s)|VERIFY_ACTION|npm test passed" >> .claude/state/stop-verify.log
echo "$(date +%s)|VERIFIED" >> .claude/state/stop-verify.log

What it catches well: the entire class of failures where the model writes a confident closing message without ever shelling out to a verifier. Because the contract is external (the log file is outside the model's context window), paraphrase attacks don't work — there is no clever phrasing that satisfies a missing log entry.

What it does not catch: a model that does write a VERIFIED line but whose verification was bogus (echo "VERIFIED" with no prior test command). It enforces that verification happened, not that the verification was correct.

Tradeoffs: zero language coverage problem (it doesn't read code or text — it reads filesystem state), zero false-positive rate by construction (silence on pure-conversation turns where no files changed), 60-second setup, MIT-licensed, no dependencies beyond bash + python3 stdlib.

Strategy 2: `no-vibes` — text-vocabulary judge

waitdeadai/no-vibes, part of the llm-dark-patterns suite, takes the opposite angle. It reads the model's outgoing text on Stop and looks for the linguistic signature of unearned closeouts — "all tests pass", "looks good", "should work", "verified" — when no proximate evidence (a fenced block with tool output, a recognized verifier binary name, a hash, an exit code) appears in the same message.

The detector is deterministic regex + locale packs + an evidence-binary allowlist with 200+ entries spanning app-dev, devops, k8s, cloud, and database tooling. Operators extend it without forking by dropping a .txt file at ${XDG_CONFIG_HOME}/llm-dark-patterns/packs/.

# Conceptual pattern (the real hook is ~530 lines with negation handling and proximity windows):

POSITIVE_CLOSEOUT_RE='\b(all tests pass(ed|ing)?|looks good|should work|verified|fixed|done|complete[d]?)\b'
EVIDENCE_BINARY_RE='\b(npm|pytest|cargo|go test|jest|playwright|curl|psql|kubectl|terraform|...)\b'

MSG="$(cat | jq -r '.message.content // empty')"

if printf '%s' "$MSG" | grep -qE "$POSITIVE_CLOSEOUT_RE"; then
  if ! printf '%s' "$MSG" | grep -qE "$EVIDENCE_BINARY_RE"; then
    echo "no-vibes: positive closeout without same-message evidence." >&2
    echo "Either run the verifier and quote its output, or hedge the claim." >&2
    exit 2
  fi
fi
exit 0

Empirical baseline: F1 0.815 (95% CI [0.615, 0.941], n=19) on the human-labelled subset of MAD against Mode 3.3 — published at the umbrella suite's evaluation/MAST-RESULTS.md. On the full LLM-judge subset (n=954) it scores F1 0.308 — recall is high (0.486) and precision falls because the LLM judge is noisier than human annotators.

What it catches well: the "confidence theater" surface. Cases where the model has the vocabulary of a successful turn but didn't actually run anything. Useful as a pure complement to verify-before-stop because it can fire mid-message (PreToolUse / Stop) rather than only at session-end.

What it does not catch: a model that closes flatly — no positive verbs at all, just "Here are the files I added." Some failure modes route around no-vibes by producing prose that is technically not a positive closeout but still implies completion.

Tradeoffs: language coverage is per-locale pack (English, Spanish, Polish ship; others need a .txt contribution). False-positive rate is non-zero — operators report occasional fires on legitimate hedged-positive turns, hence the clause-local negation hardening in the May 2026 release. Setup: 30 seconds via the plugin marketplace or one curl.

Strategy 3: `no-unreachable-symbol` — codebase static-analysis advisor

The third strategy lives at a different boundary entirely. no-unreachable-symbol fires on Stop, diffs the working tree against HEAD, extracts new public Python symbols from added lines, and flags symbols with zero callers under an exclusion-aware grep that understands decorators (@app.route, @pytest.fixture, @click.command), __all__ markers, registry patterns (HANDLERS["foo"] = sym), and private prefixes.

# Conceptual flow (the real hook is ~200 lines):

DIFF="$(git diff HEAD -- '*.py')"
NEW_SYMBOLS="$(printf '%s' "$DIFF" | grep -E '^\+\s*(def|class)\s+' | sed -E 's/^\+\s*(def|class)\s+([a-zA-Z_][a-zA-Z0-9_]*).*/\2/' | sort -u)"

# Skip private (_foo) and dunder (__foo__) symbols
# Skip decorator-wired symbols (framework callbacks)
# Respect __all__ public-API markers
# ... (full exclusion logic in the real script)

for sym in $REMAINING_SYMBOLS; do
  CALLERS="$(grep -rE "\b$sym\b" --include='*.py' --exclude-dir=tests . | grep -vE "^[^:]+:\s*(def|class)\s+$sym\b" || true)"
  if [ -z "$CALLERS" ]; then
    echo "ADVISORY: new public symbol \`$sym\` has zero callers." >&2
  fi
done

# Default: advisory mode (exit 0 with stderr). Strict mode via env:
[ "${LDP_UNREACHABLE_SYMBOL_BLOCK:-0}" = "1" ] && exit 2

What it catches well: the specific failure where Claude generates a new public function or class as part of a refactor, claims the refactor is wired up, but never edits any caller. This is invisible to no-vibes (no positive-closeout language was used) and invisible to verify-before-stop (the model dutifully logged VERIFIED after running tests — which passed because nothing called the new symbol).

What it does not catch: non-Python languages (Slice 0 is Python-only; TS/JS/Rust/Go are roadmap), and dynamic-dispatch patterns where the symbol is called but via getattr / string-based reflection that grep cannot resolve.

Tradeoffs: language coverage is limited (Python at Slice 0). False-positive rate is non-zero for codebases that rely heavily on registry patterns the hook doesn't recognize — hence the advisory-by-default ship mode, with strict-blocking opt-in via LDP_UNREACHABLE_SYMBOL_BLOCK=1. No empirical F1 baseline because MAD is text-only traces with no git-diff-vs-codebase ground truth; the hook ships against a 12-scenario smoke harness instead.

Side-by-side

Dimension	`verify-before-stop`	`no-vibes`	`no-unreachable-symbol`
Signal source	filesystem (`VERIFIED` log)	model's outgoing text	git diff + codebase grep
Operator effort per session	active (must `echo VERIFIED`)	passive	passive (advisory) / active opt-in (strict)
Catches false closeout phrasing	no (out-of-band)	yes (primary target)	no
Catches verified-but-bogus	no	partially	no
Catches dead-code-on-merge	no	no	yes
Language coverage	language-agnostic	per-locale pack (en/es/pl ship)	Python (Slice 0)
Empirical F1 vs MAST 3.3	not published (strict contract; no false-negative-acceptable mode)	0.815 human-labelled, 0.308 LLM-judge	n/a (no ground truth dataset)
False-positive rate	~0 (silence when no files changed)	low but non-zero (hedge-then-positive cases)	non-zero on heavy-registry codebases
Setup time	60s	30s (plugin marketplace) or 60s (curl)	30s (part of umbrella plugin)
License	MIT	Apache 2.0	Apache 2.0

When to use which

Use verify-before-stop if you are running a single-developer Claude Code project with frequent destructive operations (database migrations, API deploys, infra changes) where the cost of an unverified closeout is high (rollback, on-call page, data loss). The active-logging discipline is friction by design — it forces a verification step into muscle memory. Best fit for shipping individual contributors who have been bitten by Mode 3.3 in production and want the hardest contract.

Use no-vibes if you are working across many short turns where active logging is impractical (e.g. extended exploratory sessions, planning work, multi-agent supervisor closeouts). It is also the right pick for multi-language stacks because the locale packs and evidence-binary allowlist generalize, and for teams where the vocabulary of false success is the primary failure surface — overconfident closeouts from junior-coded prompts or model drift on long sessions.

Use no-unreachable-symbol if your codebase is primarily Python and your dominant failure shape is the "refactor mirage" — Claude added the new helper but never edited any caller, tests still pass because nothing exercises the new symbol, and you only discover it when reviewing the PR. Especially useful for library work where unused public symbols become part of the API surface and accrue maintenance cost forever.

Decision shortcuts:

"My tests are green but my prod is on fire" → verify-before-stop (you have a test/reality mismatch, not a model-vocabulary problem).
"Claude says 'looks good' on turns where I know it didn't run anything" → no-vibes.
"My PR reviewers keep finding orphan code Claude added" → no-unreachable-symbol.

Combining all three: defense-in-depth

The hooks compose. Each closes a different gap. A session that survives all three has had filesystem-contract, text-evidence, and symbol-evidence line up — which is roughly the contract MAST 3.3 actually asks for.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/verify-before-stop.sh" },
          { "type": "command", "command": "bash .claude/hooks/no-vibes.sh" },
          { "type": "command", "command": "bash .claude/hooks/no-unreachable-symbol.sh" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/no-vibes.sh" }
        ]
      }
    ]
  }
}

Order matters: verify-before-stop first (cheapest check; exits early on read-only sessions), then no-vibes (text scan), then no-unreachable-symbol (most expensive — runs a full repo grep). Any hook returning exit 2 blocks the stop and surfaces its stderr to the model, which then has the corrective context on the next turn.

If you want a starting point tailored to your stack instead of a generic template, Ian's free audit tool generates three personalized hook recommendations from your repo's language mix and CI setup in about 41 seconds — no signup, no email gate.

Frequently Asked Questions

Which of the three hook strategies should I add to my project first?

Start with verify-before-stop. It catches the highest-leverage failure (false-completion claims) with the lowest false-positive rate (around 4% on the runs I measured) and exits early on read-only sessions, so the perf cost is negligible. Add no-vibes second once you stop trusting bare assertions in stdout, and no-unreachable-symbol last because it runs a repo-wide grep and only pays off on multi-file refactors.

Can these three strategies be combined safely in one Stop hook chain?

Yes. The config in the post shows all three under a single Stop matcher, executed in order. Each script returns exit 0 (allow) or exit 2 (block + surface stderr to the model). Order matters for perf: verify-before-stop first (cheapest), no-vibes next (text scan), no-unreachable-symbol last (grep). If any one blocks, the rest don't run, which is the behavior you want.

Is verify-before-stop production-ready, or is this still experimental?

I've run it across ~40 sessions over three weeks on my own projects. The false-positive rate sits around 4%, and the false-negative rate (model claims completion, hook misses it) is harder to measure but bounded by the assertion list. It's stable enough for solo work. For team use I'd recommend pinning a specific version of the script in your repo rather than curling the latest from main.

How is this different from running CI tests or pre-commit hooks?

CI runs after you push; pre-commit runs at git commit. Both happen too late if the goal is to stop the model from claiming a task is done mid-session. Stop hooks fire inside Claude Code itself, before the model returns control to you. The output is fed back to the model as corrective context, so it iterates rather than handing you a broken state.

Does this work on Linux, macOS, and Windows (WSL)?

macOS and Linux: yes, tested. WSL: should work — the hooks are POSIX bash with grep, git, and find. Native Windows (PowerShell) would need a rewrite; nothing in the logic is OS-specific but the shebang and pipe syntax aren't portable. If you're on Windows, run Claude Code inside WSL2 and the hooks behave the same as on Linux.

What's the false positive rate, and how do I tune it down if it's too noisy?

About 4% in my measurement window. The two main sources: (1) the assertion list flags phrases like 'all tests pass' that appeared in a code comment, and (2) the unreachable-symbol grep misfires on dynamic dispatch. Tune (1) by editing the regex array at the top of verify-before-stop.sh; tune (2) by adding paths to the skip list. Both are inline-documented in the script.

Stop Claude Code from lying about completion — a 50-line bash hook

Ian — Wed, 20 May 2026 11:38:04 +0000

After 12 months running Claude Code on 14 parallel projects, the same regression cycle kept happening:

Claude: "All tests passing ✅"
Me:     [merges PR]
Prod:   [throws 500s]
Me:     [2h debugging]
Tomorrow: [same cycle]

The model isn't lying on purpose — it's just optimistic about its own work. The fix isn't a better prompt. The fix is a workflow guard.

So I built verify-before-stop.sh — a Stop hook that blocks the session from ending until verification is actually logged. Here's the full implementation and why it works.

The pattern

Claude Code's Stop hook fires when the model tries to end a session. The hook receives JSON on stdin with stop_hook_active, transcript_path, session_id. If the hook exits non-zero with stderr message, Claude continues the turn — and the stderr becomes part of the model's context.

That's the leverage point. If the model claims "done" without proof, exit 2 with instructions for what proof is required.

The hook (50 lines)

#!/bin/bash
# verify-before-stop.sh

INPUT=$(cat)

# Avoid infinite loop — Claude Code sets stop_hook_active=true
# when continuing from a previous block
STOP_HOOK_ACTIVE=$(echo "$INPUT" | python3 -c \
  "import sys,json; d=json.load(sys.stdin); print('true' if d.get('stop_hook_active') else 'false')" \
  2>/dev/null)
if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
    exit 0
fi

VERIFY_LOG=".claude/state/stop-verify.log"
mkdir -p .claude/state

# No file changes → pure conversation → allow stop
HAS_CHANGES=$(git diff --name-only 2>/dev/null | head -5)
HAS_UNTRACKED=$(git ls-files --others --exclude-standard 2>/dev/null | grep -v '.claude/state/' | head -5)
if [ -z "$HAS_CHANGES" ] && [ -z "$HAS_UNTRACKED" ]; then
    exit 0
fi

# Files changed → require VERIFIED log entry in last 5 min
if [ -f "$VERIFY_LOG" ]; then
    FIVE_MIN_AGO=$(date -v-5M +%s 2>/dev/null || date -d '5 minutes ago' +%s 2>/dev/null || echo 0)
    LAST_VERIFY=$(grep '|VERIFIED' "$VERIFY_LOG" 2>/dev/null | tail -1 | cut -d'|' -f1)
    LAST_ACTION=$(grep '|VERIFY_ACTION' "$VERIFY_LOG" 2>/dev/null | tail -1 | cut -d'|' -f1)
    if [ -n "$LAST_VERIFY" ] && [ "$LAST_VERIFY" -gt "$FIVE_MIN_AGO" ] 2>/dev/null; then
        if [ -n "$LAST_ACTION" ] && [ "$LAST_ACTION" -gt "$FIVE_MIN_AGO" ] 2>/dev/null; then
            echo "$(date +%s)|STOP_ALLOWED" >> "$VERIFY_LOG"
            exit 0
        fi
    fi
fi

echo "$(date +%s)|STOP_BLOCKED" >> "$VERIFY_LOG"
echo "⛔ BLOCKED: files changed but no verification logged in last 5 min." >&2
echo "Required: log a VERIFY_ACTION + VERIFIED entry, e.g.:" >&2
echo '   echo "$(date +%s)|VERIFY_ACTION|ran npm test, 3 failures" >> .claude/state/stop-verify.log' >&2
echo '   echo "$(date +%s)|VERIFIED" >> .claude/state/stop-verify.log' >&2
exit 2

Install

Drop into .claude/hooks/ and wire it up:

// .claude/settings.json
{
  "hooks": {
    "Stop": [{
      "matcher": "*",
      "hooks": [
        { "type": "command", "command": "bash .claude/hooks/verify-before-stop.sh" }
      ]
    }]
  }
}

Restart your Claude Code session. Done.

How verification works in practice

When Claude tries to end after edits, the hook blocks with stderr telling it exactly what to log. The model then has to either:

# A) Actually verify
$ npm test
# ...test output...
$ echo "$(date +%s)|VERIFY_ACTION|npm test all green" >> .claude/state/stop-verify.log
$ echo "$(date +%s)|VERIFIED" >> .claude/state/stop-verify.log

# B) Admit it didn't verify
# Claude in next turn: "I couldn't actually run the tests — they require a
# dev DB. Here's what I changed; please run npm test manually before merging."

Either way, you stop getting false "done" reports.

4 design decisions worth defending

1. Why a 5-minute TTL on VERIFIED?
Long enough that legitimate verify→stop sequences don't trip on it. Short enough that stale entries from yesterday don't accidentally allow stops.

2. Why git diff as the change signal?
Catches both edits and untracked new files. Excludes .claude/state/ (the hook's own writes) to avoid self-triggering loops.

3. Why exit 2 (not 1)?
Claude Code treats exit 2 as a Stop block with stderr passed to the model. Exit 1 is treated as a generic error and may not surface the message correctly.

4. Why explicit VERIFY_ACTION + VERIFIED two-line pattern?
The VERIFY_ACTION line forces the model to commit what it verified in writing — not just claim it. Doubles as an audit trail you can grep later.

Watch out for the cap

Claude Code v2.1.143+ added a built-in safeguard: after ~8 consecutive Stop-hook blocks, the turn ends with a warning regardless. This is intentional — prevents broken hooks from infinite-looping the model. Override with CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=20 if you have legitimate reason for more retries.

Design your hook to give the model enough information to comply on the next turn, not on the 8th turn.

What this saved me

After 6 months of using this hook across 14 projects:

Eliminated "AI says tests pass, they didn't" regressions — the #1 source of "wait, I thought you said this worked" merges.
Forced explicit verification logging — .claude/state/stop-verify.log now reads like an audit trail.
Survived conversation compaction — the log file persists, so even after Claude Code summarizes the session, the verification record is still on disk.

Open source

Full source on GitHub: https://github.com/ianymu/claude-verify-before-stop

MIT license. Star it if you find it useful — easier to find when you need it again.

If you want the rest

I packaged this with 5 more hooks I built over those 12 months — cost-tracker.sh (logs every $ of Opus spend to costs.jsonl), block-secrets.sh (scans Write/Edit/Bash for sk-ant-*/JWT/AWS keys before commit), force-progress-update.sh (checkpoint every 5 actions to survive compaction), pre-compact-diary.sh (preserves WIP context), enforce-autoplan.sh (no code-write without a plan).

Full 6-pack is $49 launch price (regular $79), 30-day money-back, instant download via Polar: https://landing-ianymu.vercel.app

But honestly — verify-before-stop alone solves 80% of the pain. Start there. Use it free for a week, then decide if the rest is worth it.

Discussion

Curious if you've built similar workflow guards. The verify-before-stop pattern feels obvious in hindsight — what other "lies of completion" patterns have you caught?

Drop your own hooks in the comments. If they're solid I'll add them to the README with credit.

— Ian

I analyzed thousands of founder posts and built a platform to solve the #1 complaint

Ian — Tue, 10 Mar 2026 12:44:42 +0000

6 months ago I quit my job to build products solo. The coding was fine. Marketing I could figure out. What almost made me give up was the silence.

Not "I'm lonely" silence. More like — I just spent three weeks on a feature and I genuinely can't tell if it's brilliant or stupid. And there's nobody to ask.

The research

I started reading everything solo founders were posting online. Reddit, HN, IndieHackers, Twitter. Thousands of posts. Same three problems everywhere:

1. No accountability
You set goals on Monday. By Wednesday they're gone. Nobody notices, nobody cares. Without a co-founder or team, goals are just wishes.

2. Generic advice
"Have you tried content marketing?" Thanks. Very helpful. The advice you get from people who don't know your product is almost always useless. Not because they don't care — they just don't have context.

3. Communities built for broadcasting, not connection
You scroll, read, maybe post something. It gets 2 upvotes. You move on. There are hundreds of founder communities, but they're all optimized for content consumption, not for actual relationships.

What actually worked

The one thing that changed my productivity was finding another founder at my exact stage. We did weekly 30-minute calls. Simple format:

What did you do this week?
What's the plan for next week?
What's blocking you?

My output doubled. Just knowing someone would ask me on Friday whether I did the thing I said I'd do on Monday — that was enough.

Then he got busy, the calls stopped, and I went back to building alone.

What I'm building

So I'm making a platform called ADot to solve this at scale.

The core: AI matches you with a founder at your stage (pre-launch? first 10 users? trying to hit $1K MRR?) for structured weekly check-ins. Not networking events. Not another Slack group. Actual accountability with someone who gets it.

On top of that:

Community feed where milestones get seen (not buried)
AI recommendations based on what similar products did to grow
Open-source founder tools (pain point analyzer, competitor tracker)

Current status

Just launched the landing page. Validating whether this resonates or if I'm projecting.

If you've ever built alone and wished someone was in the trenches with you: https://adot-lp.vercel.app

Feedback >> signups. Tell me why this won't work.

I analyzed thousands of founder posts and built a platform to solve the #1 complaint

Ian — Tue, 10 Mar 2026 12:44:42 +0000

6 months ago I quit my job to build products solo. The coding was fine. Marketing I could figure out. What almost made me give up was the silence.

Not "I'm lonely" silence. More like — I just spent three weeks on a feature and I genuinely can't tell if it's brilliant or stupid. And there's nobody to ask.

The research

I started reading everything solo founders were posting online. Reddit, HN, IndieHackers, Twitter. Thousands of posts. Same three problems everywhere:

1. No accountability
You set goals on Monday. By Wednesday they're gone. Nobody notices, nobody cares. Without a co-founder or team, goals are just wishes.

What actually worked

The one thing that changed my productivity was finding another founder at my exact stage. We did weekly 30-minute calls. Simple format:

What did you do this week?
What's the plan for next week?
What's blocking you?

My output doubled. Just knowing someone would ask me on Friday whether I did the thing I said I'd do on Monday — that was enough.

Then he got busy, the calls stopped, and I went back to building alone.

What I'm building

So I'm making a platform called ADot to solve this at scale.

On top of that:

Community feed where milestones get seen (not buried)
AI recommendations based on what similar products did to grow
Open-source founder tools (pain point analyzer, competitor tracker)

Current status

Just launched the landing page. Validating whether this resonates or if I'm projecting.

If you've ever built alone and wished someone was in the trenches with you: https://adot-lp.vercel.app

Feedback >> signups. Tell me why this won't work.

DEV Community: Ian

I gave Claude Code internet eyes (and didn't have to build the tool myself)

The pattern: post-2026-05 Claude Code is a sealed room

Discovery

Three things I actually used it for

Why this matters now, specifically

How it compares

A small note on the broader pattern

Try it

I spawned 25 Claude Code subagents in one night. Here's what I learned.

What got built

The four things that worked

1. Constrained prompts, not vague ones

2. run_in_background: true was the unlock

3. Self-correction when the parent reviewed

4. The daily quota forced a different design

The two things that didn't work

Subagents drifting from spec

The TODO.md file beat my memory, badly

The false positive that saved my reputation

Tiny details that compounded

What I'd give credit to

What's live and where the artifacts are

More reading

Frequently Asked Questions

I built a security scanner. Its first finding was wrong. Here's what I changed.

What the scanner does, and why it exists

The finding

What I did instead

The fix

An unrelated bonus finding

What I'm taking away

Frequently Asked Questions

How 3 Claude Code Hook Strategies Compare for Preventing False-Completion

Strategy 1: verify-before-stop — log-based contract

Strategy 2: no-vibes — text-vocabulary judge

Strategy 3: no-unreachable-symbol — codebase static-analysis advisor

Side-by-side

When to use which

Combining all three: defense-in-depth

Frequently Asked Questions

Stop Claude Code from lying about completion — a 50-line bash hook

The pattern

The hook (50 lines)

Install

How verification works in practice

4 design decisions worth defending

Watch out for the cap

What this saved me

Open source

If you want the rest

Discussion

I analyzed thousands of founder posts and built a platform to solve the #1 complaint

The research

What actually worked

What I'm building

Current status

I analyzed thousands of founder posts and built a platform to solve the #1 complaint

The research

What actually worked

What I'm building

Current status

2. `run_in_background: true` was the unlock

Strategy 1: `verify-before-stop` — log-based contract

Strategy 2: `no-vibes` — text-vocabulary judge

Strategy 3: `no-unreachable-symbol` — codebase static-analysis advisor