Finding Every Broken Link with a One-Liner Claude Code Wrote

Broken links kill trust with visitors and crawlers alike. The usual answer is a SaaS audit tool. The better answer, if you have a static build, is grep.

The crawler

Astro builds the whole site into dist/. That means every internal link and every page exists as files, so link checking becomes a filesystem problem instead of a network one. Claude Code wrote this:

grep -rhoP '(?<=href=")/[^"#?]*' dist --include="*.html" | sort -u |
while read -r p; do
  [ -f "dist${p%/}/index.html" ] || [ -f "dist${p}" ] || echo "BROKEN: $p"
done

Extract every internal href from the built HTML, dedupe, check each against the build output. No network, no crawler budget, runs in about a second.

What it found

BROKEN: /blog/claude-code-remembers-across-sessions-with-claude-md/
BROKEN: /blog/til-draft-filtering-was-missing/
BROKEN: /blog/til-merge-collections-instead-of-splitting/

Three URLs, all TIL posts, all linked from the homepage, tag pages, and the TIL index. The root cause turned out to be an earlier “fix” that misread an intentional redirect as duplicate content. That one got its own post.

The point here: the crawler didn’t just say “broken.” Because Claude Code found them, it immediately grepped the source for where each link was generated, traced the route change that removed the pages, and reverted it. Diagnosis and fix landed in the same session.

The follow-up nobody does

While in there, Claude noticed the site had no 404 page at all. Unknown URLs returned a blank Workers response. Two additions:

• src/pages/404.astro, a branded not-found page with links back to the content
• not_found_handling: "404-page" in wrangler.json, so Cloudflare actually serves it

Where this lives now

The one-liner runs as part of the pre-deploy check. A broken internal link now fails the build instead of shipping. Total cost of the tooling: zero dollars, one grep.

Next step

The crawl found the symptom. Here is the root cause, and the guardrail that stopped it recurring. If your site is leaking crawl errors, that is the kind of audit I do as consulting. Book a call.