What the agent does
The agent reads how the site is built and tested before it adds a third tool, because a Hugo site with modules and npm scripts has its own rules. In a site laid out like docsy/docsy-example, hugo.yaml sets baseURL to https://example.docsy.dev, pulls the Docsy theme as a Hugo module through go.mod, and serves three languages, English in content/en, Norwegian in content/no and Persian in content/fa with direction: rtl. package.json pins hugo-extended at 0.166.0, requires Node 24 and npm 11.18 (.nvmrc says 24.22.1), and builds through a chain of scripts: build runs _hugo-dev with -DFE and a BASE_URL, build:production runs hugo --cleanDestinationDir --minify, and install:safe is npm ci --ignore-scripts. test:site runs node --test over tests/*.test.mjs, which read pages out of public/ after a build, and tests/npm-scripts.test.mjs guards the shape of the scripts themselves. .github/workflows/links.yaml already does the full dance on pull requests: setup-go, setup-node from .nvmrc with npm cache, npm ci, npm run update:docsy:pack, the npm-scripts test, a pinned lychee install, npm run check:links and a drift check that fails if generated files changed. netlify.toml builds previews with build:preview and production with build:production. .gitignore ignores /public and resources/.
The agent adds @lhci/cli, current release 0.15.1, as a devDependency, and .lighthouserc.json at the root. ci.collect.staticDistDir is public, so Lighthouse CI serves the built site itself and no server is needed, and ci.collect.url lists the pages that stand for the site: the English home page, /docs/, one page under /docs/getting-started/, /blog/, the Norwegian /no/docs/ and the Persian /fa/docs/, the last because an RTL page is where a theme's layout scores diverge. numberOfRuns is set so a flaky metric does not fail a build on one sample. ci.assert uses the lighthouse:recommended preset with the audits that depend on a live network, such as uses-http2 and is-on-https, turned off for a static server, and the four category scores as error thresholds that the agent sets from the scores it measures in its sandbox rather than from a number it wishes were true. ci.upload.target is temporary-public-storage, so every run links to a full report without an account.
The workflow, .github/workflows/lighthouse.yaml, copies the setup steps of links.yaml line for line, including the pinned action shas, builds with npm run build:production -- --baseURL http://localhost/ so internal links resolve against the static server, and runs npx lhci autorun. It runs on pull requests and on pushes to main, with the same permissions: contents: read. Because tests/npm-scripts.test.mjs guards the scripts, the agent reads it before adding a check:lighthouse script that builds and runs lhci autorun, and keeps the naming it expects; package-lock.json changes for the one new package, and nothing under packages/hugoautogen moves, so the links workflow's drift check stays green. The Google search engine id, the Netlify config and the theme are untouched.
To check it, the agent runs npm ci, npm run update:docsy:pack, the production build and npx lhci autorun in its sandbox, reads the per-URL scores, sets the thresholds just under them, and runs once more to show the assertions pass. It runs node --test tests/npm-scripts.test.mjs to show the new script is accepted, runs npm run _is:clean to show the drift check would pass, and runs zizmor over the new workflow the way zizmor.yaml does.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Lighthouse CI to this Hugo site. Read hugo.yaml, package.json and its scripts, .nvmrc, netlify.toml, .github/workflows/links.yaml, tests/npm-scripts.test.mjs and the content directories first. Add @lhci/cli as a devDependency and a .lighthouserc.json that serves the built public directory with staticDistDir, lists the home page, a docs page, a getting-started page, the blog index and one docs page in each other language including the RTL one, uses the lighthouse:recommended preset with network-only audits turned off, asserts the four category scores at thresholds you set from your own measurements, and uploads to temporary public storage. Add a check:lighthouse script that the npm-scripts test accepts, and a lighthouse workflow that copies the setup steps and pinned actions of links.yaml, builds with build:production and a localhost baseURL, and runs lhci autorun on pull requests and pushes to main. Run the build and lhci in the sandbox, show the scores per page, confirm the npm-scripts test and the drift check pass, and open a pull request with the output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request adds .lighthouserc.json and .github/workflows/lighthouse.yaml, and changes package.json and package-lock.json. Its description pastes the scores per URL from the sandbox run, the thresholds chosen against them, and the lhci autorun output showing every assertion passing, with the temporary report link for each page.
The new lighthouse workflow runs on the pull request itself beside links and zizmor, so the first check is the same command on a GitHub runner, and the links workflow's drift check shows the generated theme files did not move. The run's record keeps the first, unthresholded run that the thresholds came from.
Before merging, a reviewer decides whether the thresholds should be tighter on the home page than on the RTL docs page, whether numberOfRuns is worth the extra minutes on every pull request, and whether to swap temporary storage for a Lighthouse CI server later. The theme, the content and the Netlify build are unchanged.
Run it on every pull request to the docs site
The workflow is the automation: once merged, every pull request builds the site and scores the listed pages, and a theme change that drops a category below its threshold fails the check with the report linked. A team with several Hugo sites sends this body once per repository to POST /o/{org}/sessions, each with its own repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started.
Each run reads its own build: a site that builds with a plain hugo command and no npm gets the CLI installed in the workflow instead of package.json, and a single-language site gets a shorter URL list. A webhook_url on the key reports each run.completed with the pull request in result, and a run.failed names a site whose build broke in the sandbox before Lighthouse ran.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Lighthouse CI is one config file, but on a site with Hugo modules, a guarded npm-script layout, a drift check and three languages, the config is the easy part. The agent builds the site the way its own workflow does, measures each page in its own sandbox, and sets thresholds from those numbers rather than from a default that fails on the first RTL page.
The scores, the report links and the passing assertion output stay with the run and are pasted into the pull request. Several sites can get the same change at once, each measured on its own pages.
Frequently asked questions
Why a static directory instead of a running server?
Because the site is static. staticDistDir makes Lighthouse CI serve public/ itself, which is simpler than keeping hugo server alive in a workflow step and is the same HTML Netlify serves. The build uses a localhost base URL so links inside the pages resolve against that server.
Where do the thresholds come from?
From the agent's own measurement in its sandbox. It runs Lighthouse CI without assertions first, reads the four category scores for each listed page, and sets each threshold just under what the site scores today, so the check guards against regressions without failing on day one. Raising them is a one-line change per category.
Why include the Norwegian and Persian pages?
Because the theme renders them through different layouts, and the Persian pages are right-to-left. A score measured only on the English home page would miss a regression in the language menu or an RTL style. One page per language keeps the run short while covering each layout once.
Will the drift check in the links workflow still pass?
Yes. The agent runs npm run _is:clean after its changes to confirm nothing under packages/hugoautogen or link-cache.jsonc moved, and the only generated file that changes is package-lock.json, which it commits. The npm-scripts test is run too, so the new script fits the layout that test guards.
More Hugo jobs
The same job on other stacks
- Add Lighthouse CI to a Jekyll Site (Jekyll)
- Add Lighthouse CI to a SolidJS App (SolidJS)
- Add Lighthouse CI to a Vite React App (Vite + React)