llms-link-check

Fast CI-friendly link health checks for llms.txt.

Built by ConfigCrate.

llms.txt is becoming a common entry point for AI agents and LLM-aware documentation. The file often ships with links to Markdown docs, API guides, examples, and generated pages. When those links go stale, agents get a bad first context window.

llms-link-check focuses on one job: find broken or suspicious links in llms.txt before they reach production.

What it checks

• Markdown links like [Guide](/guide.md)
• duplicate URLs
• empty link text or empty URLs
• unsupported schemes such as mailto: or javascript:
• broken HTTP links, including 4xx and 5xx
• redirects
• optional cross-host warnings
• optional text/html warnings, useful when you expect agent-readable Markdown/plain text

It does not generate llms.txt, crawl whole sites, or run SEO scoring.

Install

go install github.com/configcrate/llms-link-check/cmd/llms-link-check@latest

Or download a release binary from GitHub Releases.

Usage

Check a local file:

llms-link-check ./llms.txt --base-url https://example.com

Check a remote file:

llms-link-check https://example.com/llms.txt

JSON output:

llms-link-check ./llms.txt --base-url https://example.com --format json

Parse only, without network requests:

llms-link-check ./llms.txt --no-network

Strict CI mode:

llms-link-check ./llms.txt \
  --base-url https://example.com \
  --require-same-host \
  --fail-on-warn

GitHub Actions example

name: llms.txt

on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v6
        with:
          go-version: "1.25.12"
      - run: go run github.com/configcrate/llms-link-check/cmd/llms-link-check@v0.1.0 ./llms.txt --base-url https://example.com

Exit codes

• 0: no failing findings
• 1: errors found, or warnings found with --fail-on-warn
• 2: usage, file read, or internal execution error

Flags

--base-url string       base URL used to resolve relative links when checking a local llms.txt
--concurrency int       maximum concurrent link checks (default 8)
--fail-on-warn          exit with code 1 when warnings are found
--format string         output format: text or json (default "text")
--no-network            only parse links; do not make HTTP requests
--require-same-host     warn when a checked link points to a different host than the source/base URL
--timeout duration      overall timeout (default 15s)
--user-agent string     HTTP User-Agent
--version               print version
--warn-html             warn when a link resolves to text/html (default true)

Why this exists

The llms.txt ecosystem is active: the reference repository and related hubs/generators have substantial GitHub activity, while real projects are already filing issues for broken llms.txt links and missing AI-readable docs. Most existing tools are generators, full validators, or AEO/SEO suites. This project intentionally stays narrow so it is easy to add to CI.

License

MIT