# Raise a WordPress site's PageSpeed score with Codex

> Raising a WordPress PageSpeed score with Codex means asking it in your terminal to preview an xSpeed optimization plan and then apply it through xSpeed Hub, with you approving the pass.

Page: https://xspeedcache.com/agent/codex/optimize-site/
Last updated: October 2026

A common trigger is a merged pull request that added a heavy plugin or a slider, and a score that dropped with it. You are in the terminal with Codex already open on the repository, so you tell it which site and what happened. It calls list_sites to find the handle, then optimize_site with dry_run on. That preview shows which settings xSpeed would turn on and does not change the site, so you can read it next to the diff that caused the drop.

Ask for the plan at the level you want. Standard is the default, safe keeps to server-side settings and removals, and aggressive includes settings known to break some themes. When you approve, Codex runs the real pass: each setting goes on one at a time, the page is checked after each one, and anything that breaks it is undone. That takes up to two minutes per site. The reply lists what was applied, what was undone, and an unfixable list for what caching cannot reach, so a slider that loads full-size images will show up there rather than as a promised win.

After the pass, the Hub gives Codex a set of verify_urls and tells it to look at the site before it reports success. Codex has a shell, but fetching a page from a shell shows the HTML and not what your JavaScript does in a browser, which is the very thing the plugin cannot check. Ask Codex to fetch the URLs for a quick look, then open them in a browser yourself. If the site has the Pro Critical CSS module, Codex can also run generate_critical_css and purge afterwards.

## Set up Codex 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 and sign in

Add the server with its URL, then log in. The login opens an xSpeed Hub page in your browser; approve access there. There is no token to paste, and Codex keeps the credentials it receives. Start Codex and type /mcp to see the server.

```bash
codex mcp add xspeedhub --url https://app.xspeedcache.com/xspeed/mcp
codex mcp login xspeedhub
```

### 3. Keep the Hub's tools on a prompt

Open ~/.codex/config.toml. Set the server to prompt for every tool, then let one read tool run without a question. The tool timeout defaults to 60 seconds, and a PageSpeed test can take up to about two minutes, so raise it.

File: `~/.codex/config.toml`

```toml
[mcp_servers.xspeedhub]
url = "https://app.xspeedcache.com/xspeed/mcp"
default_tools_approval_mode = "prompt"
tool_timeout_sec = 150

[mcp_servers.xspeedhub.tools.get_cache_status]
approval_mode = "approve"
```

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

### 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. Codex has two layers for shell work: the sandbox mode limits what commands can touch, and the approval policy sets when Codex stops to ask. MCP tools have their own settings. Each server takes default_tools_approval_mode (auto, prompt, writes or approve) and each tool can override it with approval_mode. Codex also asks about MCP calls that advertise side effects or a destructive annotation, but xSpeed Hub's tool definitions do not declare either, so do not rely on that default for the Hub; set the server to prompt. approval_policy never, --yolo and an auto_review reviewer take the human out of the loop. xSpeed Hub has no confirmation step of its own, so an approved or auto-approved write runs as soon as your connection allows writes.

## Prompts

- The slider plugin dropped the shop score. Use xSpeed Hub to preview what it would do at the standard level and stop before applying.
- With xSpeed Hub, apply that plan to shop, then list the verify URLs so I can open them in a browser.
- Using xSpeed Hub, generate critical CSS for shop, then purge the cache so pages rebuild with it. Ask me first.

## Example session

```
You: The new slider plugin dropped the shop score. Use xSpeed Hub to see what it can recover.
  → list_sites [read-only]: 4 sites; shop is shop.example.com
  → optimize_site(site: shop, aggressiveness: standard, dry_run: true) [dry run]: plan: 4 settings to apply (defer JS, CSS minify, lazy-load images, compression), nothing changed
Agent: The plan is script deferral, CSS minify, lazy-loading and compression. Nothing has changed. Apply it to shop?
You: Apply it.
  → optimize_site(site: shop, aggressiveness: standard) [changes site]: applied 3, undone 1 (slider script broke), unfixable: full-size slider images
Agent: Three settings are on. The slider script change broke the slider, so xSpeed undid it. The full-size slider images are on the unfixable list and need resizing in the theme. I can fetch the home page for a quick look, but open it in a browser too, because fetching cannot show script errors.
```

## How it works

1. **See where the site stands**: The agent reads get_score_history for the last stored scores and list_modules for which modules exist on that site and what state they are in. Neither changes anything.
2. **Preview with dry_run**: optimize_site with dry_run: true returns the plan: each change and its tier, what would be skipped (already on, or needing a higher aggressiveness) and what it cannot fix. Nothing is applied. The tool description tells the agent to prefer this before the first real run on a site you have not optimized before.
3. **Apply it**: optimize_site without dry_run applies the plan. aggressiveness is safe (removals and server-side changes only), standard (the default) or aggressive, which includes settings known to break some themes and should be opted into deliberately. A run can take up to about 2 minutes per site.
4. **Look at the site afterwards**: When changes were applied, the result carries verify_urls and a note. The site checks its own HTML and reverts anything that breaks it, but it cannot run JavaScript, so verified: true does not prove the page works in a browser. The Hub tells the agent to open those URLs and check the page renders and the console is clean, or to tell you which URLs to check.
5. **Reach for a number only if you named one**: target_score (1 to 100, Pro sites only) turns one pass into repeated rounds toward that score, up to max_rounds, with 3 as the most per site. Each round is a real PageSpeed measurement and up to about 2 minutes. The result says why it stopped, and diminishing returns means what is left is outside what caching can reach.
6. **Critical CSS on Pro sites**: generate_critical_css generates above-the-fold CSS so the first screen can paint without waiting for the full stylesheets. It needs the Pro Critical CSS module on that site, and the site answers with an unknown-tool error without it. Pages are rebuilt with it on their next build, so the agent purges the cache afterwards.

## Reference

| | |
| --- | --- |
| Main tool | optimize_site (write): measure, apply one setting at a time, verify, undo what breaks, re-measure |
| Preview | dry_run: true returns the plan and changes nothing |
| aggressiveness | safe, standard (default) or aggressive |
| Every site at once | site: "all" or a list of handles, one result per site, sites run one after another; the Hub's confirm-once instruction does not name optimize_site, so your client's prompt is the gate |
| Time | Up to about 2 minutes per site |
| target_score | 1 to 100; needs Pro on the site; without it the site runs one pass and says so |
| max_rounds | Up to 3 per site; only sent along with target_score; 12 rounds in total per call |
| Wide fan-out with a target | Each site gets fewer rounds, and the result carries a note saying so |
| Result fields | applied, skipped, reverted, unfixable, score, verified, rounds; verify_urls after a run that changed something |
| Already tuned site | Returns "everything is already on" plus what it cannot fix; that is an answer, not a failure |
| Critical CSS | generate_critical_css (write), Pro Critical CSS module required; purge_cache afterwards |
| Read-only connection | optimize_site and generate_critical_css are refused; dry_run is still a write call, so it is refused too. Applies to the connection token with Read-only everywhere on and to a Viewer sign-in, not to other OAuth sign-ins |

## Rules

- Run dry_run first. optimize_site changes live site settings as soon as your connection allows writes. The tool description tells the agent to preview first on a site that has not been optimized, but that is guidance, so your client's approval prompt and a read-only connection (the connection token with Read-only everywhere on, or a Viewer sign-in) are the real gates.
- Keep aggressive for a deliberate choice. It includes settings known to break some themes, and the agent should say so before using it.
- After a run that changed something, open the pages in verify_urls. The HTML checks cannot run JavaScript, so a page can pass them and still be broken in a browser. Do not call a run safe because verified is true.
- Relay the unfixable list. When a site is already tuned, the honest answer is that caching is done and the rest is page weight, hotlinked images or DOM size. The agent should not retry the tool or claim a gain it did not make.
- Only ask for target_score when you want the site driven to a number. Each round costs a real PageSpeed measurement, and a plain "make it faster" is one pass.

## Good to know with Codex

Codex asks by default about MCP calls that advertise side effects or a destructive annotation, and the Hub's tool definitions declare neither. A quiet terminal therefore does not mean a safe pass: the preview and the real pass can both run without a question. Set the Hub server to the prompt approval mode and Codex asks before each call, dry run included. The approval policy never, the yolo flag and an auto-approving reviewer take you out of the loop, and a per-tool approve setting on optimize_site covers the real pass as well as the preview. Codex's tool timeout also defaults to 60 seconds and a pass can take up to about two minutes per site, so raise it before you run one. A fetch from the shell cannot catch the JavaScript errors that verify_urls exists to find.

## More prompts for this job

They work in any client connected to xSpeed Hub.

- Ask xSpeed Hub to preview what optimize_site would change on shop with a safe pass. Do not apply anything.
- Use xSpeed Hub to optimize the blog site with the standard pass, then give me the pages to check by hand.
- With xSpeed Hub, get docs to a mobile PageSpeed score of 90 if you can, and tell me why it stopped if it does not get there.
- Use xSpeed Hub to show me what optimize_site would do on every site, as a dry run, and list which sites have the most left to change.
- Use xSpeed Hub to generate critical CSS for shop, then purge the cache so the pages are rebuilt with it.
- With xSpeed Hub, optimize shop, then compare the new PageSpeed score with the last stored one.
- Using xSpeed Hub, what could optimize_site not fix on the shop site?

## Frequently asked questions

### Can Codex see whether an optimization pass broke my site?

Only partly. It can fetch the verify URLs and read the HTML, which is the same check the plugin already ran. A broken script shows only in a real browser, so open the pages yourself with the console visible.

### Does Codex ask before it runs optimize_site?

Not by default. Codex prompts for MCP calls that advertise side effects or a destructive annotation, and the Hub's tools declare neither. Set the Hub server to the prompt approval mode and Codex asks before each call. The Hub runs the pass as soon as your connection allows writes, so that setting and a read-only connection (the connection token with Read-only everywhere on, or a Viewer sign-in) are the gates that matter. Ask for dry_run first either way.

### What does optimize_site actually do?

It measures the site, applies the recommended xSpeed settings one at a time, checks that the page still renders after each change, and undoes any change that breaks it. It then reports what was applied, skipped and reverted, and what it could not fix. It reaches caching and asset delivery only.

### Should I run a dry run first?

Yes, especially on a site you have not optimized before. dry_run: true returns the plan, what would be skipped and what cannot be fixed, and changes nothing. The tool description tells the agent to prefer it, but nothing forces it, so say so in your prompt if you want a preview.

### Can I tell it to get my site to a score of 90?

Yes, with target_score, on a site that has xSpeed Pro. It repeats measure, apply and re-measure for up to 3 rounds per site and stops early when rounds stop helping, saying why. On a Free site the score target is ignored and you get a single pass with a note that no iterative tuner is installed.

### Why did it say everything is already on?

That is a real answer. The settings it can apply were already enabled, so there was nothing to change. The result also lists what it could not fix, such as page weight, images hosted on another domain or DOM size, and those need changes outside a caching plugin.

### Does the agent check that my pages still work?

The site checks its own HTML after each change and reverts anything that breaks it, but it cannot run JavaScript. After a run that changed something, the Hub tells the agent to open the returned verify_urls and check the page renders and the console is clean, or to give you the URLs to check yourself.

### Does generate_critical_css work on a Free site?

No. It needs the Pro Critical CSS module on that site, and without it the site answers with an unknown-tool error. On a Pro site, purge the cache afterwards, because pages already cached were built without the critical CSS.

## Raise the PageSpeed score with other agents

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

## More with Codex

- [Purge the WordPress cache with Codex](https://xspeedcache.com/agent/codex/purge-cache/)
- [Find out why WordPress pages are not cached with Codex](https://xspeedcache.com/agent/codex/troubleshoot-cache/)
- [Scan a website for speed problems with Codex](https://xspeedcache.com/agent/codex/speed-scan/)
- [Run and track PageSpeed tests with Codex](https://xspeedcache.com/agent/codex/pagespeed-tests/)
- [Tune WordPress cache settings with Codex](https://xspeedcache.com/agent/codex/cache-settings/)
- [Warm the WordPress cache with Codex](https://xspeedcache.com/agent/codex/preload-cache/)
- [Set up the Redis object cache with Codex](https://xspeedcache.com/agent/codex/object-cache/)
- [Manage Cloudflare caching with Codex](https://xspeedcache.com/agent/codex/cloudflare/)
- [Manage every WordPress site at once with Codex](https://xspeedcache.com/agent/codex/fleet/)

## Documentation

- How to generate Critical CSS: https://xspeedcache.com/docs/critical-css/
- Performance recommendations: https://xspeedcache.com/docs/performance-recommendations/
- How to run a speed test: https://xspeedcache.com/docs/external-score/
- Free vs Pro: what is included: https://xspeedcache.com/docs/free-vs-pro/