# Run and track PageSpeed tests with Paperclip

> Tracking PageSpeed scores with Paperclip means giving one of the agents it runs a routine that reads your sites' stored PageSpeed history through xSpeed Hub and posts drops on a task, with fresh tests left for a person to approve.

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

Paperclip turns the PageSpeed check into a ticket. A routine fires on a cron schedule, creates a task and wakes the agent you assigned, for example a Claude Code agent with xSpeed Hub added on its host. The task says what to do: read get_score_history for every site, compare the newest mobile and desktop runs with the previous ones, and post any drop with its LCP, CLS and TBT. Every call and its result land on the task trace, so the review is something you read in the dashboard rather than a chat you have to remember to start.

The data has limits worth writing into the task. get_score_history reads what the plugin stored and starts nothing, and the Hub does not run PageSpeed tests on a timer, so a site with no new run repeats last week's numbers; have the agent print each run's date. A fresh reading is run_speed_test, mobile or desktop, up to about two minutes each, saved to the Hub's own report history rather than to the stored list. run_benchmark adds a cached against uncached timing of the home page with no Lighthouse score.

When the report flags a site, the follow-up can be a second task: retest that one site on mobile and post the result. Assign it when you are around to approve it, because a test spends the shared allowance and the routine that found the drop runs with nobody watching.

## Set up Paperclip 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 to the agent Paperclip runs

For a Claude Code agent, run this on the machine that hosts it, as the same OS user the Paperclip heartbeat runs as. Paperclip's docs say MCP wiring lives at the adapter and runtime layer, and user scope makes the Hub available to every Claude Code agent that user runs.

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

### 3. Sign in once, or use a token

Start claude interactively as that same user, run /mcp, choose xspeedhub and approve access on the xSpeed Hub page. Claude Code keeps the credentials, so later headless runs need no browser; claude mcp get xspeedhub shows the status. On a host with no browser, add the server with the connection token from Connect AI in the Hub instead, ideally with Read-only everywhere on.

```bash
# Interactive sign-in
claude
/mcp

# Or a token, no browser
claude mcp add --transport http --scope user xspeedhub https://app.xspeedcache.com/xspeed/mcp \
  --header "Authorization: Bearer <your connection token>"
```

Full setup: https://xspeedcache.com/agent/paperclip/

### 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. Paperclip's Claude Code adapter runs headless with dangerouslySkipPermissions on by default, which lets the agent call MCP tools without asking. Set it to false and a tool that needs approval does not run. A server added on the adapter does not pass through Paperclip's action permissions or review queue. A Paperclip connector does: each Hub tool is set to Allowed, Ask first or Off, and because the Hub publishes no annotations Paperclip classifies them by name, which can under-classify, so start every write Off. xSpeed Hub has no confirmation step of its own, so a write that gets past those settings runs as soon as your connection allows writes. For unattended routines, send a connection token with Read-only everywhere on, which makes the Hub refuse every write tool.

## Prompts

- Weekly routine: use xSpeed Hub to read the PageSpeed history for every site and post any mobile or desktop drop on this task. Do not run tests.
- Using xSpeed Hub, list each site's newest stored PageSpeed run with its date, and flag any older than two weeks.
- With xSpeed Hub, run one mobile test on the site last week's review flagged and post the result on this ticket.

## Example session

```
You: Ticket: use xSpeed Hub to review stored PageSpeed for every site. Read only.
  → list_sites [read-only]: 3 sites: shop, blog, docs
  → get_score_history(site: shop) [read-only]: latest mobile 58 (3 days ago), previous 58; desktop 82
  → get_score_history(site: blog) [read-only]: latest mobile 51 (5 days ago), previous 62; LCP 4.7 s against 3.3 s
  → get_score_history(site: docs) [read-only]: latest mobile 70 (6 weeks ago); no newer run
Agent: Posted on the ticket: blog fell eleven points on mobile, with LCP up to 4.7 s. shop is flat. docs has no run in six weeks, so its score is stale rather than stable. No tests were run; a follow-up task can retest blog once you approve it.
```

## 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 Paperclip

The Claude Code adapter runs headless with dangerouslySkipPermissions on by default, so an agent whose host config holds the Hub can call run_speed_test with no prompt, and a server added there does not pass through Paperclip's action permissions or review queue. The Hub has no confirmation step of its own either. There are two fixes. Give the routine's agent a connection token with Read-only everywhere on, which makes the Hub refuse every test. Or attach the Hub on the Connectors page instead: the Hub publishes no tool annotations, so Paperclip classifies tools by name and can under-classify, so check how run_speed_test came out and set it to Ask first or Off. Refresh actions can widen what agents may call, so look again after a refresh. User scope on the host is shared by every Claude Code agent that OS user runs.

## 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

### Can a Paperclip routine start PageSpeed tests?

It can if the agent's connection allows writes and nothing stops the call, because the Claude Code adapter skips permission prompts by default and the Hub has no confirmation step. Give routine agents a connection token with Read-only everywhere on, or use the Connectors route with run_speed_test on Ask first or Off.

### Where do the PageSpeed results show up in Paperclip?

On the task the routine created, with each Hub call and its result in the trace. A fresh run_speed_test is also saved to the Hub's own report history, which the Hub dashboard shows on its Reports tab.

### 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/) · [Grok Build](https://xspeedcache.com/agent/grok-build/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/) · [NanoClaw](https://xspeedcache.com/agent/nanoclaw/pagespeed-tests/)

## More with Paperclip

- [Purge the WordPress cache with Paperclip](https://xspeedcache.com/agent/paperclip/purge-cache/)
- [Find out why WordPress pages are not cached with Paperclip](https://xspeedcache.com/agent/paperclip/troubleshoot-cache/)
- [Scan a website for speed problems with Paperclip](https://xspeedcache.com/agent/paperclip/speed-scan/)
- [Raise a WordPress site's PageSpeed score with Paperclip](https://xspeedcache.com/agent/paperclip/optimize-site/)
- [Tune WordPress cache settings with Paperclip](https://xspeedcache.com/agent/paperclip/cache-settings/)
- [Warm the WordPress cache with Paperclip](https://xspeedcache.com/agent/paperclip/preload-cache/)
- [Set up the Redis object cache with Paperclip](https://xspeedcache.com/agent/paperclip/object-cache/)
- [Manage Cloudflare caching with Paperclip](https://xspeedcache.com/agent/paperclip/cloudflare/)
- [Manage every WordPress site at once with Paperclip](https://xspeedcache.com/agent/paperclip/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/