Agent404

Agent404 is a link verification toolkit for finding broken links without over-reporting provider-blocked URLs as failures.

It ships as an npm library and CLI. The core package is designed to be reused later by a web app, Codex plugin, GitHub Action, and browser extension.

Install

npm install @heysalad/agent404

CLI

npx @heysalad/agent404 scan https://developers.openai.com/community/meetups

JSON output:

npx @heysalad/agent404 scan https://developers.openai.com/community/meetups --json

Fail on broken links:

npx @heysalad/agent404 scan https://example.com --fail-on broken

Library

import { scanPage } from "@heysalad/agent404";

const report = await scanPage("https://developers.openai.com/community/meetups");

console.log(report.summary);
console.log(report.results.filter((result) => result.classification === "broken"));

Result Classes

• valid: Link resolved to a successful final target.
• broken: Link returned a strong dead-link signal such as 404 or 410.
• blocked: Provider blocked automated verification, for example LinkedIn 999, 401, 403, or 429.
• timeout: Request exceeded the configured timeout.
• unknown: Verification produced an ambiguous result.

MVP Scope

• Fetch one page.
• Extract HTTP(S) links from anchor tags.
• Deduplicate targets.
• Check each target with HEAD, falling back to GET where needed.
• Follow redirects.
• Classify results as valid, broken, blocked, timeout, or unknown.
• Return structured JSON suitable for CLI, web UI, GitHub Actions, and Codex plugin workflows.

Known Limits

This MVP is HTTP-based. Browser-rendered scanning with Playwright is planned for pages that inject links client-side or require click-level verification.