Lighthouse shaped for AI agents, not HTML reports.

Thin wrapper around Lighthouse + Chrome. Real value is condense() — turns megabytes of audit noise into a few kilobytes of actionable context for coding agents.

Quick start

npx inaria https://example.com
pnpm dlx inaria https://example.com
yarn dlx inaria https://example.com

# Check installed version
npx inaria --version

Prerequisites: Node.js 22+, Google Chrome or Chromium on your system.

Why Inaria

Running Lighthouse is easy. Feeding the output to an AI agent is not.

| | Raw Lighthouse JSON | Inaria output | |---|---|---| | Size | Often 1–5+ MB | Typically a few KB | | Audits | Hundreds, traces, tables | Scores, core metrics, top 25 failures | | DOM context | Buried in details.items | failingElements with selector, snippet, explanation | | Streams | Progress mixed with output | stdout = audit output, stderr = progress |

For an agent that needs to find and fix issues in a codebase, that condensation is the point. Full Lighthouse JSON wastes context, adds noise, and makes prioritization harder.

What it is

• Lighthouse → agent-ready JSON. Scores, metrics, failing audits with DOM selectors and snippets.
• Markdown reports. --format markdown for GitHub issues, PR descriptions, and human-readable summaries.
• Structured diffs. inaria diff compares two audit files and emits only what changed — score deltas, resolved issues, new failures.
• Sitemap sweeps. Parallel Chrome workers with live TTY progress on stderr.
• Pipe-friendly. Compact JSON on stdout by default. Progress never pollutes the output stream.

What it isn't

| Need | Use instead | |------|-------------| | Full audit fidelity (80+ a11y failures) | --all-issues or --fullreport, or raw npx lighthouse | | Real-user field data (CrUX) | PageSpeed Insights API | | CI score gates and regression tracking | Lighthouse CI (@lhci/cli) | | Human-readable HTML dashboards | Lighthouse CLI --view, Unlighthouse | | Deep perf debugging (waterfall, flame charts) | Chrome DevTools | | Zero-setup cloud audits | PSI API (still needs local Chrome for Inaria) |

Default output caps at 25 issues and 15 elements per issue — tuned for agent context, not compliance sign-off. Escape hatches below.

Usage

# Desktop audit (default)
npx inaria https://example.com

# Mobile only
npx inaria https://example.com --mobile

# Both form factors (JSON array of two objects)
npx inaria https://example.com --desktop --mobile

# Write pretty JSON to file
npx inaria https://example.com -o report.json

# Markdown for GitHub issues or PR descriptions
npx inaria https://example.com --format markdown -o report.md
npx inaria https://example.com --desktop --mobile --format markdown

# Compare two audit runs (structured diff)
npx inaria diff before.json after.json
npx inaria diff before.json after.json --format markdown -o diff.md

# Sitemap crawl with live progress on stderr
npx inaria --sitemap https://example.com/sitemap.xml --desktop --mobile -o sitemap-report.json
npx inaria --sitemap https://example.com/sitemap.xml --format markdown -o sitemap-report.md

# 6 parallel workers
npx inaria --sitemap https://example.com/sitemap.xml -c 6

Run inaria --help for the full CLI reference.

CLI reference

 ▄▄▄▄▄                         ▀
   █    ▄ ▄▄    ▄▄▄    ▄ ▄▄  ▄▄▄     ▄▄▄
   █    █▀  █  ▀   █   █▀  ▀   █    ▀   █
   █    █   █  ▄▀▀▀█   █       █    ▄▀▀▀█
 ▄▄█▄▄  █   █  ▀▄▄▀█   █     ▄▄█▄▄  ▀▄▄▀█ 1.2.1

Usage: inaria [options] [command] [url]

Run Lighthouse on a page or sitemap. JSON to stdout; progress to stderr. Turns
megabytes of audit noise into a few kilobytes of actionable context for coding
agents

Arguments:
  url                    Page URL (http/https). Omit with --sitemap.

Options:
  -V, --version          output the version number
  --desktop              Desktop audit (default unless --mobile only).
  --mobile               Mobile audit. Use with --desktop for both.
  --sitemap <url>        Audit all URLs from sitemap (nested indexes
                         supported).
  -c, --concurrency <n>  Parallel Chrome workers for sitemap scans (default:
                         half CPU cores, max 4).
  -o, --output <file>    Save JSON to file instead of stdout.
  --fullreport           Full Lighthouse JSON (1–5+ MB). Not for AI pipes.
  --all-issues           All failing audits and elements (no caps). Ignored
                         with --fullreport.
  --compact              Force compact JSON (default on stdout).
  --pretty               Force pretty JSON (default with -o).
  --format <type>        Output format: json (default) or markdown
                         (GitHub-friendly). (default: "json")
  -h, --help             display help for command

Commands:
  diff <before> <after>  Compare two audit JSON files; emit only what changed

EXAMPLES
  inaria https://example.com
  inaria https://example.com --desktop --mobile -o report.json
  inaria https://example.com --format markdown -o report.md
  inaria diff before.json after.json
  inaria --sitemap https://example.com/sitemap.xml -c 4

inaria diff accepts the same -o, --format, --compact, and --pretty flags as audit runs. --compact and --pretty apply to JSON only; they are ignored with --format markdown.

Sitemap result shape:

┌─────────────────────────────────────┐
│ sitemap                             │
│ total                               │
│ scanned                             │
│ pages[]                             │
│   ├─ url                            │
│   └─ audits | error                 │
└─────────────────────────────────────┘

Sitemap progress

inaria: found 24 URLs — 4 parallel worker(s)

inaria  sitemap scan
[████████░░░░░░░░░░░░░░░░░░░░] 8/24 (33%)  elapsed 1m12s  eta 2m30s
ok 7  fail 1  running 3

running
  • https://example.com/contact
  • https://example.com/blog

recent
  ✓ https://example.com/about
  ✗ https://example.com/broken

inaria  done  23 ok  1 failed  3m45s

When stderr is not a TTY, each completed URL logs on its own line.

Output

Default (condensed)

Each audit returns a small JSON object:

• url — final audited URL
• formFactor — desktop or mobile
• fetchTime — ISO timestamp
• scores — category scores (0–100): performance, accessibility, best-practices, SEO
• metrics — core web vitals and related performance metrics
• issues — up to 25 failing audits, worst first, each with:
  • description — audit explanation
  • failingElements — DOM nodes (label, selector, snippet, explanation)
  • resources — URLs and savings for performance opportunities

npx inaria https://example.com | jq '.issues[0]'

{
  "id": "color-contrast",
  "title": "Background and foreground colors do not have a sufficient contrast ratio.",
  "description": "Low-contrast text is difficult or impossible for many users to read.",
  "score": 0,
  "failingElements": [
    {
      "label": "span",
      "selector": "pre.astro-code.github-dark > code > span",
      "snippet": "<span style=\"color: rgb(227, 148, 220);\">",
      "explanation": "Fix any of the following:\n  Element has insufficient color contrast..."
    }
  ]
}

Output modes

| Mode | Flag | Best for | |------|------|----------| | Default | — | Scores, metrics, top 25 issues. AI fix loops. | | All issues | --all-issues | Every failing audit and element, still agent-shaped. | | Full report | --fullreport | Full Lighthouse JSON (1–5+ MB). Debug and archival. |

JSON formatting

| Target | Format | |--------|--------| | stdout | Compact JSON (default) | | -o, --output <file> | Pretty JSON (default) | | --compact | Force compact JSON | | --pretty | Force pretty JSON | | --format <type> | json (default) or markdown for GitHub-friendly reports |

LLMs parse JSON reliably. Inaria's main token win is condense(), not the serialization format. --compact and --pretty apply to JSON only; they are ignored when --format markdown is set.

Markdown reports

Use --format markdown when the audience is a human reader or a GitHub issue/PR, not an LLM pipe.

npx inaria https://example.com --format markdown
npx inaria https://example.com --format markdown -o report.md
npx inaria https://example.com --desktop --mobile --format markdown
npx inaria --sitemap https://example.com/sitemap.xml --format markdown -o sitemap.md

Markdown output includes:

• Scores — category table (performance, accessibility, best-practices, SEO)
• Metrics — core web vitals with display values
• Issues — failing audits with selectors, HTML snippets, and explanations
• Multi form-factor — desktop and mobile sections separated by ---
• Sitemap — per-page sections with scan summary

--format markdown is not supported with --fullreport (raw Lighthouse JSON has no markdown renderer).

Comparing runs

Save audits before and after a fix, then diff them for a precise before/after summary — score deltas, resolved issues, new failures, and element-level changes.

npx inaria http://localhost:3000 -o before.json
# apply fixes
npx inaria http://localhost:3000 -o after.json
npx inaria diff before.json after.json

# Pretty JSON diff to file
npx inaria diff before.json after.json --pretty -o diff.json

# Markdown diff for a PR comment
npx inaria diff before.json after.json --format markdown -o diff.md

Diff output is structured, not a line-oriented text patch. For a single audit, JSON includes only changed fields:

| Section | What changes | |---------|----------------| | scores | { before, after, delta } per category | | metrics | Changed metrics with scoreDelta where applicable | | issues.resolved | Audits that disappeared (id, title) | | issues.new | Full issue objects for new failures | | issues.changed | Score, value, or element/resource deltas on persisting audits | | unchanged | true when before and after are identical |

Dual form-factor runs produce a JSON array of per-audit diffs. Sitemap reports diff per URL, listing only pages that changed.

Both input files must be the same report shape (single audit, audit array, or sitemap).

Using with AI

Inaria is built to be run by a coding agent, not pasted into chat manually.

See AGENTS.md for a copy-paste tool definition (Cursor rules, AGENTS.md in your repo, etc.).

Example prompt

Run Inaria against https://localhost:4321 for both desktop and mobile:

  npx inaria https://localhost:4321 --desktop --mobile

Use the JSON output to fix every failing audit you can in this codebase. For each
issue, use failingElements (selector, snippet, label) to find the matching
component or stylesheet.

After making changes, run Inaria again and confirm scores improved. Summarize
what you fixed and the before/after scores.

  npx inaria diff before.json after.json

Use the diff output to verify exactly which scores moved and which issues were resolved — without re-interpreting two full audit files.

Agent workflow

# 1. Baseline
npx inaria http://localhost:3000 --desktop --mobile -o before.json

# 2. Agent reads before.json, edits source files

# 3. Re-audit
npx inaria http://localhost:3000 --desktop --mobile -o after.json

# 4. Structured diff (scores, resolved issues, new failures)
npx inaria diff before.json after.json

For PR descriptions, pipe the diff through markdown:

npx inaria diff before.json after.json --format markdown -o perf-diff.md

Alternatives

| Tool | Best for | |------|----------| | Inaria | Small JSON for AI agents — selectors, snippets, fix loops, structured diffs | | npx lighthouse | Full JSON/HTML reports, every audit, official defaults | | @lhci/cli | PR checks, score budgets, historical reports | | Unlighthouse | Whole-site scans with HTML UI | | PageSpeed Insights API | Lab + field data from Google's infra, no local Chrome |

None of these optimize for small AI-consumable JSON with failingElements the way Inaria does.

Where it shines

• Local and staging URLs in agent-driven fix loops
• Before/after diffs that answer "did my fix work?" without manual score comparison
• Markdown reports pasted into GitHub issues and PRs
• Sitemap sweeps piped into scripts that feed an LLM
• stdout/stderr contract that keeps machine output clean for pipes

Install from source

git clone https://github.com/mharwooduk/Inaria.git
cd Inaria
npm install
npm link   # optional: global `inaria` command

License

MIT — free to use, fork, modify, and redistribute. See LICENSE.