# Run and track PageSpeed tests with Grok Build

> Tracking PageSpeed scores with Grok Build means asking xAI's terminal agent for your stored PageSpeed history and a fresh test of the live site, with xSpeed Hub supplying the data.

Page: https://xspeedcache.com/agent/grok-build/pagespeed-tests/
Last updated: October 2026

You are in the terminal with Grok Build, partway through a change, and want to know where the site stands. Ask it, and it calls get_score_history through the Hub and returns the stored runs, with the score, LCP, FCP, CLS, TBT, Speed Index and TTFB for mobile and desktop. If you name two sites it reads both and sets them side by side, which helps when one of them is the control you compare against.

For a fresh run it calls run_speed_test, a PageSpeed Insights run from the Hub, mobile or desktop, taking up to about two minutes. The Hub saves the result in its own report history, the Reports tab of the dashboard, which get_score_history may not read. run_benchmark is the quick option: it times the home page cached and uncached, with no Lighthouse score, and get_benchmark_history shows past benchmark runs so you can see whether a settings change coincided with a better time. Name the tool you want when you ask, so the answer is a score or a timing and never a blend.

Grok Build keeps the sign-in it receives from the Hub on your machine, in its own credentials store, so you sign in once rather than on every session. A written test plan helps here: say how many runs you want and for which device, and have it stop there. It makes the session predictable and keeps your use of the shared allowance small.

## Set up Grok Build once

### 1. Put your sites in xSpeed Hub

Sign in at app.xspeedcache.com with Google or email; the Hub is free and has no site cap. Then connect each WordPress site from its own dashboard: click Connect Hub in the xSpeed Cache top bar, then Connect via xSpeed Hub. Each site needs the free xSpeed Cache plugin.

### 2. Add xSpeed Hub with grok mcp add

Run this once. Add --scope project to write the server to .grok/config.toml in the current directory instead of your user config, which is only sensible if the repo never holds a token. Grok Build handles the OAuth flow for a remote server on its own.

```bash
grok mcp add --transport http xspeedhub https://app.xspeedcache.com/xspeed/mcp
```

### 3. Sign in from the TUI

Start grok and open /mcps. Select xspeedhub and press i to authenticate, or just use a Hub tool and let the browser flow start on first use. Sign in to xSpeed Hub and approve access. There is no token to paste; Grok Build stores the credentials it receives in ~/.grok/mcp_credentials.json. If the connection fails, run grok mcp doctor xspeedhub.

```
/mcps
```

Full setup: https://xspeedcache.com/agent/grok-build/

### Before you send a prompt that changes something

Reads change nothing on your sites, though contact_support emails xSpeed support. Writes run once your connection allows them, so your client's approval prompt and a read-only connection (the token's Read-only everywhere switch, or a Viewer sign-in) are the gates that matter. Grok Build starts in Ask mode, which prompts for anything a rule has not already allowed, so a Hub write tool prompts until you say otherwise. You can allow the reads with a rule such as MCPTool(xspeedhub__get_*) in the permission section of your config, and leave the writes unmatched. Evaluation runs deny, then ask, then allow. Two other modes remove the prompt: Always-approve, from /always-approve, Ctrl+O or --always-approve, approves tool calls unless a deny rule or a hook stops them, and Auto lets a classifier approve tools it judges safe. If a Hub write must never run unprompted, add a deny rule. The Hub itself has no confirmation step.

## Prompts

- Ask xSpeed Hub for the PageSpeed history of shop and list the last three mobile scores with their dates.
- Use xSpeed Hub to run one desktop test on blog and tell me how it compares with the previous desktop run. Stop after that one.
- With xSpeed Hub, show the benchmark history for shop and say whether response time changed after the settings change I made on Monday.

## Example session

```
You: Using xSpeed Hub, where does blog stand on desktop? One test at most.
  → get_score_history(site: blog) [read-only]: latest desktop 84, previous 85; 10 days ago; LCP 1.9 s
Agent: Desktop is 84, one point under the run before it and ten days old. I can run one fresh desktop test, which takes up to two minutes and spends shared allowance. Do it?
You: Yes, one test.
  → run_speed_test(site: blog, strategy: desktop) [uses quota]: desktop score 85, LCP 1.8 s, CLS 0.02, saved to the Hub report history
Agent: Desktop is 85 now, so the one-point dip was within normal variation. I stopped after one test, as you asked.
```

## How it works

1. **Read before you test**: get_score_history returns the stored PageSpeed Insights and GTmetrix runs for a site: the score per run, with LCP, FCP, CLS, TBT, Speed Index and TTFB, mobile and desktop. It starts nothing. The Hub tells the agent to use it whenever you ask what your score is, or whether it improved, because a new test spends a shared allowance.
2. **Run a new test when you need one**: run_speed_test runs a real PageSpeed Insights audit on the site from the Hub and returns the score, the Core Web Vitals and the top opportunities. strategy is mobile (the default) or desktop, and one call tests one of them. It can take up to about 2 minutes, so the agent should say it is running before it calls.
3. **Test the other device**: Mobile and desktop scores differ, often by a lot. For both, the agent makes two calls, one per strategy. A failure is reported with its reason: PageSpeed not configured, quota reached, a timeout, or a site the audit cannot reach.
4. **Measure the cache on its own**: run_benchmark times the home page with the cache bypassed and again served from cache, and returns the response times. It is a read tool, and it accepts site: "all" for every site. It does not return a Lighthouse score, so the agent must not use it to answer a PageSpeed question.
5. **Compare over time**: get_benchmark_history returns past benchmark runs, uncached against cached, together with the settings changes on the same timeline, which is how you answer "did that change help?". For PageSpeed scores over time, use get_score_history.

## Reference

| | |
| --- | --- |
| Read stored scores | get_score_history (read): PageSpeed Insights and GTmetrix runs, starts nothing |
| Metrics per run | Score, LCP, FCP, CLS, TBT, Speed Index, TTFB, for mobile and desktop |
| Run a new test | run_speed_test (write, uses the shared allowance): one PageSpeed Insights run per call |
| strategy | mobile (default) or desktop |
| Duration | Up to about 2 minutes per run |
| Why a test is a write | It spends a shared PageSpeed allowance and stores a report; it changes nothing on the site |
| Read-only access | A connection token with Read-only everywhere on, or a Viewer member's sign-in: run_speed_test is refused; get_score_history, run_benchmark and get_benchmark_history still work. An OAuth sign-in gets the scopes the client asks for |
| Benchmark | run_benchmark (read): cached against uncached response time for the home page, no Lighthouse score |
| Benchmark history | get_benchmark_history (read): past runs plus settings changes on the same timeline |
| Scheduling | The Hub does not schedule PageSpeed tests itself; its daily pass only reads reports the plugin already stored |
| Where a new test is stored | In the Hub's own report history, the one the Hub dashboard shows |

## Rules

- Check the history first. Ask for stored scores before starting a test, and run a new one only when you want a fresh measurement or something changed.
- Never answer a PageSpeed or Lighthouse question with run_benchmark. It times your own cache and carries no score.
- run_speed_test changes nothing on your site, but the Hub classes it a write because it spends a shared allowance. A connection token with Read-only everywhere on, or a Viewer sign-in, refuses it. An OAuth sign-in gets the scopes the client asks for, so there your client's approval prompt is the gate.
- Lab scores move a few points between runs of the same page. The agent should compare like with like, same site, same strategy, and not report one run's difference as a trend.
- A new test does not run on a timer. If you want a regular test, the agent has to be started by something else, such as a scheduled job in your client, and a scheduled run that spends the allowance should be one you are comfortable leaving unattended.

## Good to know with Grok Build

Grok Build starts in Ask mode, which prompts for any tool call no rule has allowed, so run_speed_test asks until you say otherwise. Always-approve, from /always-approve, Ctrl+O or the always-approve flag, skips the prompt for it too, and Auto lets a classifier approve what it judges safe. Allow the reads with a rule such as MCPTool(xspeedhub__get_*), leave run_speed_test unmatched, and add a deny rule if it must never run unprompted, because deny rules still apply under Always-approve. The Hub runs the call as soon as the connection allows writes, so you can also state the number of runs in each request or use a read-only connection (the connection token with Read-only everywhere on, or a Viewer sign-in).

## More prompts for this job

They work in any client connected to xSpeed Hub.

- Using xSpeed Hub, what is the mobile PageSpeed score for shop? Check the stored history before you run anything.
- Use xSpeed Hub to run a new mobile PageSpeed test on blog and tell me the score, LCP and the top opportunities.
- With xSpeed Hub, test shop on desktop and mobile and tell me which one is worse.
- Using xSpeed Hub, has the PageSpeed score on docs improved over the last few runs?
- Use xSpeed Hub to benchmark the cache on every site and tell me which one saves the least time.
- Did turning on minification on shop help? Use xSpeed Hub to compare the benchmark history around that change.
- My PageSpeed test failed on staging. Use xSpeed Hub to tell me why.

## Frequently asked questions

### Does Grok Build ask before it starts a PageSpeed test?

In its default Ask mode it prompts for tool calls that no rule has allowed, so it asks before run_speed_test. The Hub has no confirmation step of its own, so a rule that allows the tool, Auto mode or Always-approve lets it run as soon as your connection allows writes. Add a deny rule to block it, state the number of runs in your request, or connect read-only (the connection token with Read-only everywhere on, or a Viewer sign-in).

### Where does Grok Build keep my sign-in?

It stores the credentials it receives from the Hub sign-in on your machine, in its own credentials file, so you do not paste a token. To remove the sign-in, remove the server in Grok Build. Rotating the Hub's connection token does not end an OAuth sign-in; it revokes only clients that send that token.

### What is the difference between run_speed_test and run_benchmark?

run_speed_test runs a real PageSpeed Insights audit and returns a Lighthouse score with Core Web Vitals. run_benchmark measures how fast your own cache answers compared with an uncached request for the home page, and returns no Lighthouse score. Use the first for "what is my PageSpeed score" and the second for "is my caching working".

### How long does a PageSpeed test take?

A single run can take up to about 2 minutes, so the agent should tell you it has started before it calls. One call tests one device, mobile or desktop, so checking both takes two calls.

### Can I ask for the last score without running a new test?

Yes. get_score_history reads the stored PageSpeed Insights and GTmetrix runs for the site and starts nothing. The Hub tells the agent to read it first whenever you ask what your score is, because a new test spends a shared allowance.

### Will the Hub run PageSpeed tests on a schedule?

No. The Hub does not schedule PageSpeed tests itself. Its daily pass re-verifies sites, snapshots cache status and pulls the PageSpeed and GTmetrix reports the plugin has already stored, and it can alert on a score regression. If you want regular new tests, they have to be started by a client that can run scheduled jobs.

### Why is a speed test treated as a write tool?

It does not change your site. The Hub classes run_speed_test as a write because it spends a shared PageSpeed allowance and stores a report, and a read-only connection (the connection token with Read-only everywhere on, or a Viewer sign-in) should not be able to cost the owner anything. Such a connection can still read stored scores with get_score_history.

## Track PageSpeed scores with other agents

[Claude Code](https://xspeedcache.com/agent/claude-code/pagespeed-tests/) · [Claude](https://xspeedcache.com/agent/claude/pagespeed-tests/) · [Claude Cowork](https://xspeedcache.com/agent/claude-cowork/pagespeed-tests/) · [ChatGPT](https://xspeedcache.com/agent/chatgpt/pagespeed-tests/) · [Codex](https://xspeedcache.com/agent/codex/pagespeed-tests/) · [Cursor](https://xspeedcache.com/agent/cursor/pagespeed-tests/) · [GitHub Copilot in VS Code](https://xspeedcache.com/agent/github-copilot/pagespeed-tests/) · [Windsurf](https://xspeedcache.com/agent/windsurf/pagespeed-tests/) · [Gemini CLI](https://xspeedcache.com/agent/gemini-cli/pagespeed-tests/) · [Antigravity](https://xspeedcache.com/agent/antigravity/pagespeed-tests/) · [Zed](https://xspeedcache.com/agent/zed/pagespeed-tests/) · [Kiro](https://xspeedcache.com/agent/kiro/pagespeed-tests/) · [OpenCode](https://xspeedcache.com/agent/opencode/pagespeed-tests/) · [OpenClaw](https://xspeedcache.com/agent/openclaw/pagespeed-tests/) · [Hermes Agent](https://xspeedcache.com/agent/hermes-agent/pagespeed-tests/) · [ChatGPT dots](https://xspeedcache.com/agent/chatgpt-dots/pagespeed-tests/) · [Grok](https://xspeedcache.com/agent/grok/pagespeed-tests/) · [Grok Bot](https://xspeedcache.com/agent/grok-bot/pagespeed-tests/) · [Muse](https://xspeedcache.com/agent/muse/pagespeed-tests/) · [Manus](https://xspeedcache.com/agent/manus/pagespeed-tests/) · [Kimi Code](https://xspeedcache.com/agent/kimi/pagespeed-tests/) · [Paperclip](https://xspeedcache.com/agent/paperclip/pagespeed-tests/) · [NanoClaw](https://xspeedcache.com/agent/nanoclaw/pagespeed-tests/)

## More with Grok Build

- [Purge the WordPress cache with Grok Build](https://xspeedcache.com/agent/grok-build/purge-cache/)
- [Find out why WordPress pages are not cached with Grok Build](https://xspeedcache.com/agent/grok-build/troubleshoot-cache/)
- [Scan a website for speed problems with Grok Build](https://xspeedcache.com/agent/grok-build/speed-scan/)
- [Raise a WordPress site's PageSpeed score with Grok Build](https://xspeedcache.com/agent/grok-build/optimize-site/)
- [Tune WordPress cache settings with Grok Build](https://xspeedcache.com/agent/grok-build/cache-settings/)
- [Warm the WordPress cache with Grok Build](https://xspeedcache.com/agent/grok-build/preload-cache/)
- [Set up the Redis object cache with Grok Build](https://xspeedcache.com/agent/grok-build/object-cache/)
- [Manage Cloudflare caching with Grok Build](https://xspeedcache.com/agent/grok-build/cloudflare/)
- [Manage every WordPress site at once with Grok Build](https://xspeedcache.com/agent/grok-build/fleet/)

## Documentation

- How to run a speed test: https://xspeedcache.com/docs/external-score/
- PageSpeed Insights integration: https://xspeedcache.com/docs/pagespeed-insights-integration/
- Running speed tests in xSpeed Hub: https://xspeedcache.com/docs/hub-speed-tests-and-notifications/
- How to run a PageSpeed audit: https://xspeedcache.com/docs/pagespeed/