pagespeed-audit

PageSpeed Audit

Run Google's PageSpeed Insights against deployed pages and report findings.

Scope: Tests one or more public URLs. Audits both mobile and desktop strategies by default.

Critical constraint: PSI fetches the URL from Google's servers, so it cannot reach localhost, 127.0.0.1, or private network addresses. If the user provides such a URL, stop immediately and explain — point them at their deployed staging or production URL instead.

---

Execution Flow

0. Determine Test Scope

Parse the current invocation for URL(s) — never carry over a URL from a previous turn or assume from prior conversation context. If the user didn't pass a URL on this invocation, you must ask before fetching.

URL provided in this invocation:

• "Run PageSpeed on https://example.com" → test that URL
• "/pagespeed-audit https://example.com https://example.com/pricing" → test both

No URL provided in this invocation:

• Read AGENTS.md to find a documented production URL or page list.
• If found, list the URLs and ask the user which to audit (use AskUserQuestion when 2–4 candidates exist).
• If not found, ask the user for at least one deployed URL via AskUserQuestion or a plain question.
• Do not default to a previously-audited URL, even one the user selected earlier in the same session. Ask every time.

Localhost / private addresses → reject:

• http://localhost:*, http://127.0.0.1:*, http://0.0.0.0:*
• RFC1918 ranges (10.*, 192.168.*, 172.16-31.*)
• *.local, *.internal
• Stop and tell the user: "PageSpeed Insights runs from Google's servers and can't reach private addresses. Run this against your deployed URL (staging or production) instead."

1. Check for API Key (REQUIRED)

Resolve the key from (in order): shell env, .env.local, .env. All three are checked in one Bash call:

KEY="${PAGESPEED_API_KEY:-}"
for f in .env.local .env; do
  [ -n "$KEY" ] && break
  [ -f "$f" ] && KEY=$(grep -E '^PAGESPEED_API_KEY=' "$f" | head -1 | cut -d= -f2- | tr -d '"' | tr -d "'")
done
# Don't echo the key value — print only presence to keep secrets out of chat logs.
[ -n "$KEY" ] && echo "FOUND" || echo "MISSING"