Multi-page Lighthouse audit via the MIT-licensed

SEO unlighthouse

by AgriciDaniel · MIT license · ★ 17,394 on GitHub · updated Sep 11

Multi-page Lighthouse audit via the MIT-licensed Unlighthouse CLI. Free-tier alternative to running PageSpeed against every URL on a site, no API quota burn, runs locally.

---
name: seo-unlighthouse
description: Multi-page Lighthouse audit via the MIT-licensed Unlighthouse CLI. Free-tier alternative to running PageSpeed against every URL on a site, no API quota burn, runs locally.
metadata:
  version: "2.3.1"
compatibility: "Requires Node 18+ and the unlighthouse npm package. Run extensions/unlighthouse/install.sh to pre-warm."
---

# seo-unlighthouse

Run Lighthouse against every URL on a site (up to a configurable cap)
and aggregate the results. Useful when:

- PageSpeed Insights' free quota (25k QPD) isn't enough for a large site.
- You want offline / local CWV measurement (CI integration, restricted environments).
- You need a quick site-wide regression check after a deploy.

## Prerequisites

Overview

Run Lighthouse against every URL on a site (up to a configurable cap) and aggregate the results. Useful when:

What you get

route_count: number of routes actually audited
aggregate_scores: median score per Lighthouse category across all audited
routes: the per-route breakdown (also on disk at <output_dir>/ci-result.json)

The SKILL.md below is the copy AgentAlley read and checked. The repo has changed it since; the other files are from commit e77e783.

Manual install (npx, ZIP)

Claude Codenpx skills add AgriciDaniel/claude-seo --skill seo-unlighthouse -g -a claude-code

Claude Code (manual)

mkdir -p ~/.claude/skills && curl -sL https://codeload.github.com/AgriciDaniel/claude-seo/tar.gz/e77e783e38ee \
  | tar -xz -C ~/.claude/skills --strip-components=4 claude-seo-e77e783e38ee/extensions/unlighthouse/skills/seo-unlighthouse

Windows (PowerShell)

New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null; Invoke-WebRequest "https://m.agentalley.io/zip/470cc820990d26a88a0c/seo-unlighthouse.zip" -OutFile "$env:TEMP\seo-unlighthouse.zip"; Expand-Archive "$env:TEMP\seo-unlighthouse.zip" -DestinationPath "$HOME\.claude\skills" -Force

Claude.ai / desktopDownload the ZIP and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md2.4 KB

Read the files here

AgriciDaniel/e77e7831 file

SKILL.md2.4 KB

SKILL.md

Show the full text57 lines

seo-unlighthouse/SKILL.md57 lines · 2.4 KB

PreviewCode

Outline

RawView on GitHub

seo-unlighthouse

Run Lighthouse against every URL on a site (up to a configurable cap) and aggregate the results. Useful when:

PageSpeed Insights' free quota (25k QPD) isn't enough for a large site.
You want offline / local CWV measurement (CI integration, restricted environments).
You need a quick site-wide regression check after a deploy.

Prerequisites

Run extensions/unlighthouse/install.sh (no API key needed).
Node 18+ on $PATH.

Routing

Command	Effect
`/seo unlighthouse <url>`	Mobile audit, up to 200 routes, JSON+HTML report in a temp dir
`/seo unlighthouse <url> --device desktop`	Desktop form factor
`/seo unlighthouse <url> --max-routes 50 --output-dir ./reports`	Cap + persist

All flags forward through "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run unlighthouse_run.py, which handles url_safety pre-flight and subprocess timeout management.

Output handling

The wrapper reads ci-result.json from the Unlighthouse output dir, normalizes it (the default jsonSimple reporter writes a flat JSON array of per-route results; a tolerant fallback also accepts the jsonExpanded object shape), and returns:

route_count: number of routes actually audited
aggregate_scores: median score per Lighthouse category across all audited routes (performance, accessibility, best-practices, seo)
routes: the per-route breakdown (also on disk at <output_dir>/ci-result.json)

Route cap and per-page timeout are set via a generated unlighthouse.config.mjs passed with --config-file (the only CLI-documented way to set scanner.maxRoutes; unlighthouse-ci has no --max-routes flag). Use --page-timeout <seconds> to change the per-page Lighthouse task timeout (default 60s); this is separate from the overall --timeout subprocess guard (default 600s).

Cross-skill delegation

For single-URL field data (CrUX), use seo-google psi / seo-google crux.
For LCP subpart decomposition on slow pages, use the "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run lcp_subparts.py workflow (Phase C).

1	---
2	name: seo-unlighthouse
3	description: Multi-page Lighthouse audit via the MIT-licensed Unlighthouse CLI. Free-tier alternative to running PageSpeed against every URL on a site, no API quota burn, runs locally.
4	metadata:
5	version: "2.3.1"
6	compatibility: "Requires Node 18+ and the unlighthouse npm package. Run extensions/unlighthouse/install.sh to pre-warm."
7	---
8
9	# seo-unlighthouse
10
11	Run Lighthouse against every URL on a site (up to a configurable cap)
12	and aggregate the results. Useful when:
13
14	- PageSpeed Insights' free quota (25k QPD) isn't enough for a large site.
15	- You want offline / local CWV measurement (CI integration, restricted environments).
16	- You need a quick site-wide regression check after a deploy.
17
18	## Prerequisites
19
20	- Run `extensions/unlighthouse/install.sh` (no API key needed).
21	- Node 18+ on `$PATH`.
22
23	## Routing
24
25	\| Command \| Effect \|
26	\|---\|---\|
27	\| `/seo unlighthouse <url>` \| Mobile audit, up to 200 routes, JSON+HTML report in a temp dir \|
28	\| `/seo unlighthouse <url> --device desktop` \| Desktop form factor \|
29	\| `/seo unlighthouse <url> --max-routes 50 --output-dir ./reports` \| Cap + persist \|
30
31	All flags forward through `"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run unlighthouse_run.py`, which handles
32	url_safety pre-flight and subprocess timeout management.
33
34	## Output handling
35
36	The wrapper reads `ci-result.json` from the Unlighthouse output dir, normalizes
37	it (the default `jsonSimple` reporter writes a flat JSON array of per-route
38	results; a tolerant fallback also accepts the `jsonExpanded` object shape),
39	and returns:
40
41	- `route_count`: number of routes actually audited
42	- `aggregate_scores`: median score per Lighthouse category across all audited
43	routes (`performance`, `accessibility`, `best-practices`, `seo`)
44	- `routes`: the per-route breakdown (also on disk at `<output_dir>/ci-result.json`)
45
46	Route cap and per-page timeout are set via a generated `unlighthouse.config.mjs`
47	passed with `--config-file` (the only CLI-documented way to set `scanner.maxRoutes`;
48	unlighthouse-ci has no `--max-routes` flag). Use `--page-timeout <seconds>` to
49	change the per-page Lighthouse task timeout (default 60s); this is separate
50	from the overall `--timeout` subprocess guard (default 600s).
51
52	## Cross-skill delegation
53
54	- For single-URL field data (CrUX), use `seo-google psi` / `seo-google crux`.
55	- For LCP subpart decomposition on slow pages, use the
56	`"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run lcp_subparts.py` workflow (Phase C).
57