Help us improve
Share bugs, ideas, or general feedback.
From lychee
This skill should be used when the user asks to "check links", "run lychee", "validate links", "find broken links", "check URLs in markdown", "check URLs in HTML", or wants to use lychee to check links in documentation or files.
npx claudepluginhub tarqd/skills --plugin lycheeHow this skill is triggered — by the user, by Claude, or both
Slash command
/lychee:using-lycheeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Lychee is a fast, asynchronous link checker for markdown, HTML, and plain text files. Use it to validate links in documentation, find broken URLs, and maintain link health in projects.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
Lychee is a fast, asynchronous link checker for markdown, HTML, and plain text files. Use it to validate links in documentation, find broken URLs, and maintain link health in projects.
lychee README.md
lychee README.md CONTRIBUTING.md docs/
lychee '**/*.md'
lychee 'docs/**/*.{md,html}'
Important: Quote glob patterns to prevent shell expansion.
lychee https://example.com
lychee https://example.com/docs/
Enable caching to skip re-checking previously validated links:
lychee --cache README.md
Cache location: .lycheecache/ directory (add to .gitignore)
Benefits:
--max-cache-ageControl request behavior:
# Set timeout (default: 20s)
lychee --timeout 30 docs/
# Configure retries (default: 3)
lychee --max-retries 5 README.md
# Wait time between retries (default: 1s)
lychee --retry-wait-time 2 docs/
Accept status codes beyond the default 2xx range:
# Accept 429 (Too Many Requests)
lychee --accept '200..=299,429' README.md
# Accept range including specific codes
lychee --accept '100..=103,200..=299,429,500' docs/
Default accepted codes: 100..=103,200..=299
Exclude URLs matching regex patterns:
# Exclude specific domain
lychee --exclude 'example\.com' README.md
# Exclude multiple patterns
lychee --exclude 'localhost|127\.0\.0\.1|example\.com' docs/
# Exclude URL paths
lychee --exclude '/draft/|/wip/' docs/
Check only URLs matching patterns:
# Check only HTTPS links
lychee --include 'https://.*' README.md
# Check specific domain only
lychee --include 'https://mysite\.com/.*' docs/
Note: Include patterns take precedence over exclude patterns.
lychee README.md
Shows summary with broken links.
lychee --format detailed README.md
Shows all links checked with status codes.
lychee --format json README.md > report.json
Machine-readable output for automation.
lychee --format markdown README.md > report.md
GitHub-friendly markdown report.
Resolve relative links as if files were hosted at a base URL:
lychee --base-url https://example.com/docs/ README.md
Example:
../api/reference.htmlhttps://example.com/docs/guide/https://example.com/docs/api/reference.htmlResolve absolute links in local files:
lychee --root-dir $(pwd)/build /page.html
Use case: Checking generated static sites with absolute paths.
lychee --base-url https://example.com --root-dir $(pwd)/public docs/
Constructs URLs from: domain + root-dir + absolute-path.
Remap production URLs to local paths for testing:
lychee --remap 'https://example.com file:///$(pwd)/build' docs/
Use case: Check links in locally built documentation that reference production URLs.
IMPORTANT: Only use --preprocess when explicitly instructed by the user.
Preprocess files into supported formats before checking:
# Example: Convert PDFs to HTML before checking
lychee --preprocess 'pdftohtml -i -s -noframes {} {}.html' docs/*.pdf
Format placeholders:
{} - Input file path{}.html - Output file path (lychee will check this)Common preprocessors:
pdftohtml - PDF to HTMLpandoc - Various formats to HTML/MarkdownRequirement: Preprocessor must be installed and accessible.
Avoid GitHub API rate limits:
export GITHUB_TOKEN=your_token_here
lychee README.md
Or pass directly:
lychee --github-token $GITHUB_TOKEN README.md
Lychee exit codes indicate check results:
0 - All links valid1 - Links have warnings (non-fatal)2 - Broken links foundUse in scripts:
if lychee README.md; then
echo "All links valid"
else
echo "Broken links found"
exit 1
fi
Use lychee.toml for persistent settings:
# Uses lychee.toml in current directory
lychee docs/
# Specify custom config
lychee --config custom-lychee.toml docs/
See configuring-lychee skill for configuration file details.
# With caching for repeated checks
lychee --cache --exclude 'localhost|127\.0\.0\.1' 'docs/**/*.md'
# After building site
lychee --cache --root-dir $(pwd)/build --base-url https://mysite.com build/
# Check only markdown files
lychee --extensions md,markdown README.md docs/
# Check markdown and HTML
lychee --extensions md,html,htm docs/
Check only local file references, block network requests:
lychee --offline docs/
# Minimal output
lychee --no-progress --quiet README.md
# Very quiet (errors only)
lychee --no-progress -qq README.md
--cache for repeated checks--max-concurrency for large sites (default: 128)Solution: Accept 429 status or reduce concurrency:
lychee --accept '200..=299,429' README.md
# or
lychee --max-concurrency 10 README.md
Solution: Use --insecure flag (not recommended for production):
lychee --insecure docs/
Solution: Increase timeout:
lychee --timeout 60 README.md
lychee.toml for project-specific configuration.lycheecache/ directory