How to find and fix broken links with Claude Code

Claude Code finds broken links by writing a small crawler, running it against a copy of your site, and sorting every failing link into a category with a suggested fix. Internal links that 404 get pointed at the right page. Links that go through a redirect get updated to the final URL. External links that are truly gone get replaced or removed, after a person decides which. The part that takes judgment is separating real breaks from false alarms: a site that blocks crawlers, rate-limits you or times out isn't necessarily broken.

This guide gives the routine step by step, with example prompts, the check that proves each step worked, and what a person reviews. It covers links in your pages and also the images, scripts, stylesheets and PDFs your pages load, since those break the same way.

Why broken links matter, and what Google says

Broken links hurt visitors first: a dead end in the middle of a buying decision. For search, Google's HTTP status code documentation explains what happens when a URL fails. All 4xx errors except 429 are treated the same: Google's crawlers tell the next system "that the content doesn't exist," and "Newly encountered 404 pages aren't processed." A page that returns 200 but shows an error message gets flagged as a "soft 404" in Search Console.

Redirects behave differently. Google's crawlers "follow up to 10 redirect hops," so a link through a redirect still works. But Google's site-move guide says "redirects are slow for users, so try to update your own links," and it advises against chains. That makes internal links through redirects a cleanup job, not an emergency.

Step 1: Decide what to crawl and how

Work on a branch in git and point the crawl at a local build or staging site. Ask Claude Code to plan the crawler before it writes one; plan mode (/plan) is good for this.

Example prompt: Plan a link checker for the local build at localhost:4000. It should collect every href, src and srcset on every page, including images, scripts, stylesheets and PDFs. Check internal URLs against the local build. Check external URLs with at most two requests per second per domain, a 15-second timeout, and one retry. Don't follow links off the external page. Show me the plan before writing code.

The pacing matters. External sites can block bursts, and your own host may block you if you test the live domain quickly. A polite crawl takes longer and gives you results you can trust.

Step 2: Run the crawl and sort the results

Have Claude run the crawler and write every failure to a spreadsheet with the source page, the link, the anchor text, the status or error, and a category.

The check: the crawl's page count matches your build, and every failure has exactly one category. Ask Claude to re-test the "couldn't check" rows once, later, before anyone acts on them.

Step 3: Find where each broken link comes from

One broken link in a header or footer template appears on every page. Before fixing anything, ask Claude to group failures by where they come from.

Example prompt: Group the failures in broken-links.csv by source file. For each group, say whether the link comes from a shared template (header, footer, sidebar), a content file or a data file, and how many pages it affects. Sort by pages affected.

This can turn hundreds of rows into a handful of fixes. It also shows which links live in content a person wrote, where a careless fix could change meaning.

Step 4: Choose a fix for each group

Claude can propose a fix per row. Some it can apply after approval; some need a person to decide.

• Internal 404 to a page that moved: point the link at the new URL. If other sites link to the old URL, also add a redirect; our guide to building and testing a redirect map covers that.
• Internal 404 to a page that's gone: remove the link or point it at the closest relevant page. Don't point everything at the home page.
• Internal link through a redirect: replace it with the final URL.
• Missing images or files: restore the file, fix the path, or remove the reference.
• Dead external source: a person finds a current source that supports the same statement, or rewrites or removes the statement. A different page on the same topic may not say the same thing.

Example prompt: For each internal 404 and internal redirect in broken-links.csv, propose the corrected URL using the current sitemap. Mark how sure you are. For external 404s, don't propose replacements; list them for review with the sentence that contains each link.

Step 5: Apply the approved fixes in the source

A person reviews the proposals. Then ask Claude to apply only approved rows, in the source files and templates, not in generated output. A rebuild would overwrite fixes made in built HTML. That happened on eseospace.com: a publishing step regenerated every post from source files and deleted edits made only in the built copy.

Example prompt: Apply the approved rows in broken-links.csv to the source files. Replace only the exact URL in the exact source file listed. Log any row where the old URL isn't found. Report counts of changed, skipped and not found.

The check: the changed count matches the approved count minus logged rows, and the git diff shows only URL changes. Run the script a second time. It should change nothing.

Step 6: Re-crawl and compare

Rebuild and run the same crawler again.

A person reviews the diff and approves the deploy. After the deploy, if a live check still shows an old broken link, check the build output and git log before asking Claude to fix it again. A CDN can serve a stale copy for a while, which once made a finished change on our own site look missing.

Step 7: Make it a routine

Links break over time as other sites change. Run the internal check on every pull request, where it's quick and catches mistakes before they ship; our guide to Claude Code in GitHub Actions for website QA shows how. Run the slower external check on a schedule, such as monthly. Claude Code's routines and scheduled tasks can run recurring jobs; routines are a research preview as of October 2026, so keep a person reviewing the report rather than letting a scheduled job edit the site.

A link check also belongs in your QA routine before every deploy. You can make it automatic in a session with a hook that runs the internal check whenever Claude finishes a reply.

What a person must review

• The "couldn't check" list, by opening a sample in a browser.
• Every proposed replacement for an external source, against the sentence it supports.
• Any decision to remove a link or let a page 404.
• The diff before deploy, to confirm only links and paths changed.

Internal links that work but are weak are a separate job, covered in finding and adding internal links. Broken links are one item in the wider checklist in Claude Code for technical SEO, and our older guide on how to monitor and fix broken links covers monitoring tools.

Conclusion

Claude Code makes broken-link work repeatable: a polite crawler on a copy of the site, failures sorted into categories, fixes grouped by source, approved changes applied in the source, and a second crawl to prove it. Keep people on the calls that need judgment, especially replacement sources and removed links, and make the check a routine rather than a yearly cleanup. If you'd rather have this handled as part of ongoing care, see our website maintenance plans. More guides are in our Claude Code Guide.

Frequently asked questions