/fix-broken-links

name: fix-broken-links
description: Find and fix broken links, dead pages, and redirect chains on a website
  with crawlie. Use when the user asks to find broken links, 404s, dead links, link
  rot, redirect chains/loops, or 4xx/5xx pages, or to check that a site's links are
  healthy. Works even if crawlie is not installed.

Find & Fix Broken Links (powered by crawlie)

Crawl a site, surface every broken link and redirect problem, group them by where they live, and propose concrete fixes. crawlie ships on npm as `crawlie` — no pre-install and no source repo required.

Bootstrap — make crawlie runnable

1. If `mcp__crawlie__*` tools exist this session, prefer them and skip the CLI. 2. Else choose a CLI prefix:

• `crawlie` if it's on PATH (`command -v crawlie`), else
• `npx -y -p crawlie crawlie` (auto-downloads from npm; needs only Node).

3. If neither is available, ask the user to install Node (https://nodejs.org) or the crawlie MCP, then stop.

`<crawlie>` below = the prefix from step 2 (or the matching MCP tool).

Workflow

1. **Crawl** for link health as JSON:

   <crawlie> crawl <url> --format json

• Keep external link checking ON (it's the default) so off-site 404s are caught.

Add `--no-external` only if the user explicitly wants internal-only.

• Large sites: `--max-pages N`. (MCP equivalent: `crawl_site`.)

2. **Filter** the findings to the link/status rules:

• `broken-link` — link target returns an error.
• `client-error` (4xx), `server-error` (5xx) — pages/resources failing outright.
• `redirect-chain` — multi-hop or looping redirects that waste crawl budget + link equity.
• `connection-error` — host unreachable / DNS / TLS failures.

3. **Group by source page.** For each finding crawlie reports the page the bad link is *on* and the failing target. Cluster by source page so the user can fix several at once, and note repeated targets (a single dead URL linked from many pages = one fix, big impact). 4. **Explain + recommend.** Run `<crawlie> explain broken-link` (and `redirect-chain`) for the rationale, then for each cluster propose the fix:

• 404 internal → correct the URL, restore the page, or remove the link.
• 404 external → update to the live URL or drop the link.
• redirect chain → point the link directly at the final destination.
• 5xx → flag as a server issue to investigate, not just a link edit.

5. **Deliver** a table: source page · broken target · status/rule · suggested fix. Sort by number of occurrences so the highest-leverage fixes are first.

Tips

• Re-check a handful of pages after fixes without a full re-crawl:

`<crawlie> audit <url> [<url> ...]` (MCP: `audit_urls`).

• For a CI gate that blocks merges on broken links:

`<crawlie> crawl <url> --fail-on error` (exits non-zero when errors exist).

Make it permanent (optional — offer once, don't block)

"Want crawlie installed for good? `npm i -g crawlie`. For first-class agent tools, also `claude mcp add crawlie crawlie-mcp` (active after a Claude restart)."