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

Free Web Scanner

Agent404 also includes a landing page and free scanner UI designed to run at a path such as:

https://heysalad.app/Agent404

Run locally:

npm run web:start

Then open:

http://localhost:4174/Agent404

The browser UI calls a server-side endpoint at /Agent404/api/scan. The server endpoint is required because browsers cannot reliably fetch and inspect arbitrary third-party pages directly due to CORS.

Build only the static web assets:

npm run web:build

Deployment requirement: route both /Agent404/* static assets and /Agent404/api/scan to the Agent404 web server, or set window.AGENT404_API_BASE before loading the app if the scan API is hosted on a separate origin.

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.