# Unlighthouse

Scan a whole site with Google Lighthouse from a CLI, with CI budgets and static reports.

Unlighthouse finds the pages of a site from robots.txt, the sitemap or a crawler, runs Lighthouse on each in parallel Chrome instances, and reports scores. The unlighthouse-ci binary exits with a status code against score budgets and writes JSON, CSV or static HTML reports. The npm package ships a SKILL.md for agents, and the v1 beta adds an MCP server.

- Capabilities: adaptable, operable
- Vertical: content-publishing
- Shape: internal-tool
- Form factor: cli
- Execution model: deterministic
- Provenance: unknown (recorded, never ranked)
- Repo: https://github.com/harlan-zw/unlighthouse (MIT), 4933 stars, last commit 2026-10-23
- Last activity: 2026-10-23
- Page: apps/harlan-zw--unlighthouse.html
- JSON: apps/harlan-zw--unlighthouse.json

## Use it when

- you want an agent to audit every page of a site for Lighthouse scores before launch
- you want CI to fail when performance or SEO scores drop

## Gotchas

- Needs Node 22.18 or newer and a Chrome install (it downloads one if none is found)
- Default dynamic sampling scans at most 8 URLs per route group
- The Nuxt, Vite and Webpack integrations are deprecated; run the CLI
- Lighthouse scores vary between runs; use samples for CI gates
- The MCP server and scan history are in the v1 beta (npm install -g unlighthouse@beta), which needs Node 24.13.1 or newer

## Editions

- Free: Free, open source
  - source: https://github.com/harlan-zw/unlighthouse
  - installable: npx unlighthouse-ci --site https://example.com --budget 80

## Adaptable: make it yours

Effort: config-only (1 things to edit)

unlighthouse.config.ts (or .js, .mjs) sets the site, which paths to include or exclude, mobile or desktop, samples, throttling, auth, and per-category CI budgets for performance, accessibility, best-practices and seo. CLI flags override it.

- Env vars: none
- Config files: unlighthouse.config.ts
- Prompt files: none
- Accounts you'll need: none

## Operable: what an agent can drive

Operability: official. Interface: cli at https://unlighthouse.dev/integrations/cli (published by the builder, local).

### Reach (partial coverage)

- Scan every page of a site: reachable. unlighthouse-ci --site <url> (CI docs)
- Discover pages from robots.txt, sitemap or crawl: reachable. Automatic; flags --sitemaps, --urls, --include-urls, --exclude-urls (CLI docs)
- Fail a build when scores drop under a budget: reachable. unlighthouse-ci --budget 80; ci.budget in config; exit code 1 on failure
- Write static HTML reports: reachable. unlighthouse-ci --build-static writes to .unlighthouse/
- Write JSON or CSV reports: reachable. --reporter json, jsonExpanded, csv, csvExpanded
- Scan sites behind a login: reachable. --auth, --cookies, --extra-headers flags
- Scan as mobile or desktop, with samples and throttling: reachable. --mobile, --desktop, --samples, --throttle
- Upload results to a Lighthouse CI server: reachable. --reporter lighthouseServer with --lhci-host and --lhci-build-token
- Browse results in the live dashboard: not reachable. The unlighthouse binary serves a browser dashboard on port 5678 and never exits; agents are told to use unlighthouse-ci instead
- Reopen and compare saved scans: not reachable. Scan history is a v1 beta feature; the stable 0.19 CLI has no history command. The beta MCP tools history_list and compare_run cover it.

## Code stack

- Languages: TypeScript
- Frameworks: Lighthouse, Puppeteer
- Package manager: pnpm
- Database: none
- Hosting target: npm

## Skills

bundled: Tells an agent which binary to run, how URL discovery and budgets behave, and how to read exit codes. Also published at unlighthouse.dev/SKILL.md.
- Paths: packages/unlighthouse/skills/unlighthouse/SKILL.md
- Install: npx skilld install harlan-zw/unlighthouse/unlighthouse

## Evidence and confidence

- formFactor: README and docs: npx CLI, two binaries (confidence 0.95)
- executionModel: Lighthouse audits; no model (confidence 0.95)
- operability: packages/cli/src/createCli.ts defines the flags; unlighthouse.dev/integrations/cli and /ci docs; SKILL.md in repo (confidence 0.9)
- effort: unlighthouse.dev/guide/guides/config shows unlighthouse.config.ts with scanner and ci.budget keys (confidence 0.75)
- editions: MIT; homepage says free and open source, funded by sponsors; no pricing page (confidence 0.9)
- active: gh api: last commit 2026-10-23; release v0.19.1 2026-10-03
- skills: README links skilld.dev/gh/harlan-zw/unlighthouse, which gives the install command; skilld is Harlan Wilton's package; package.json files includes skills
- vertical: No vertical covers site auditing. Two other SEO audit Listings sit in content-publishing (seo-skills--seo-audit-skill, nowork-studio--notfair-plugin).
- reach:  (confidence 0.9)
- provenance:  (confidence 0.2)

## Sources

- https://unlighthouse.dev (sourcing:content-publishing:vendor)
- https://github.com/harlan-zw/unlighthouse (analysis)
- https://unlighthouse.dev/v1/integrations/mcp (verification)