# Warm the WordPress cache with OpenCode

> Warming the WordPress cache with OpenCode means asking it, in the terminal session you code in, to start the xSpeed preloader on a site through xSpeed Hub and to read back how far the crawl has got.

Page: https://xspeedcache.com/agent/opencode/preload-cache/
Last updated: October 2026

OpenCode is open in your project, and the deploy you just ran has left the live site with an empty cache. You type which site to warm. OpenCode calls list_sites to match the handle and then start_preloader on it, and the plugin on that site starts crawling the sitemap in the background, a few URLs at a time. The next visitors land on pages that are already stored.

To follow the crawl, ask for progress. OpenCode calls get_preloader_status, a read that says whether a run is active and how many URLs are done. If the crawl needs to end, ask for stop_preloader. Pages already warmed stay cached, so stopping only ends the work and loses none of it. Sign-in to the Hub is a separate step you do once in the browser, after which OpenCode keeps the credentials it receives.

OpenCode checks MCP tools against its permission rules under the prefixed name, such as xspeedhub_start_preloader, and most permissions default to allow. With no rule of yours in place, a start runs without a prompt. Add "xspeedhub_*": "ask" first and then "xspeedhub_get_*": "allow", because the last matching rule wins, and the status read runs quietly while the two writes ask. A rule that names a tool covers every call of it, so it cannot tell a start on one site from a start on all of them. The Hub has no confirmation of its own, and its ask-once instruction for a call across every site is guidance to the agent, not a lock. A deny rule holds even under opencode --auto. A short session also works well: one prompt to start the crawl, one to read the status, and the terminal scrollback is your record of what ran.

## Set up OpenCode 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 your config

Put this block in your global config, or in opencode.json at a project root to scope it to that project. OpenCode reads both JSON and JSONC. No other field is needed: when the Hub answers 401, OpenCode starts the OAuth flow and registers itself through dynamic client registration.

File: `~/.config/opencode/opencode.json`

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "xspeedhub": {
      "type": "remote",
      "url": "https://app.xspeedcache.com/xspeed/mcp"
    }
  }
}
```

### 3. Sign in with opencode mcp auth

Run this once. It opens a browser page on xSpeed Hub where you sign in and approve access. There is no token to paste; OpenCode stores the credentials it receives. Run opencode mcp list to see the server and its auth status, and opencode mcp debug xspeedhub if the connection fails.

```bash
opencode mcp auth xspeedhub
```

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

### 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. OpenCode checks MCP tools against its permission rules under the prefixed name, such as xspeedhub_purge_cache, and most permissions default to allow. With no rule of yours in place, a Hub write tool runs without a prompt. Add rules to change that: "xspeedhub_*": "ask" first, then "xspeedhub_get_*": "allow" and "xspeedhub_list_*": "allow", because the last matching rule wins. A deny rule holds even under opencode --auto, which approves everything that is not denied. The Hub itself has no confirmation step, so these rules and read-only access are the gates. For read-only access, send the connection token with Read-only everywhere on, or sign in as a Viewer member.

## Prompts

- Use xspeedhub to start the preloader on shop and give me the status once it is running.
- Use xspeedhub: is the preloader on blog still running? Report the number of pages done.
- Use xspeedhub to warm blog and docs only, one after the other, and tell me which one finishes first.

## Example session

```
You: Deploy done. Use xspeedhub to start the preloader on blog and docs.
  → start_preloader(site: blog) [changes site]: Queued 130 URLs from the sitemap; pages are fetched in the background
  → start_preloader(site: docs) [changes site]: Queued 95 URLs from the sitemap; pages are fetched in the background
Agent: Both crawls are running. I started them one after the other so the servers did not take a burst at once.
You: Status on both in a minute.
  → get_preloader_status(site: blog) [read-only]: Running, 88 of 130 URLs warmed
  → get_preloader_status(site: docs) [read-only]: Running, 35 of 95 URLs warmed
Agent: Both are still running: blog has 88 of 130 URLs warm and docs has 35 of 95. Pages not warmed yet are built on their first visit.
```

## How it works

1. **Check the cache and the preloader**: get_cache_status tells the agent whether page caching is on, because there is nothing to fill when it is off. get_preloader_status shows whether a crawl is already running, so the agent does not start a second one.
2. **Make sure the preloader is switched on**: The preloader module is off on a fresh install, and the site refuses start_preloader until it is on. The agent can read the module with get_settings and, if you agree, switch it on with update_settings on the preloader module. The Hub tells the agent to briefly confirm intent before an update_settings call, but that is guidance to the agent, not a lock.
3. **Start the crawl**: start_preloader makes the site read its sitemap, follow any nested sitemap indexes, drop URLs that your cache exclusion rules skip, and queue the rest. The call returns once the queue is built; the pages are then fetched in the background, a few per run. For every site at once the agent passes site: "all", and the Hub starts the sites one after another with a one-second pause.
4. **Watch the progress**: get_preloader_status reports whether a crawl is running, how many URLs it has processed out of the total, the last URL it visited and the most recent errors. It works on one site at a time, so for several sites the agent calls it once per site.
5. **Read what failed**: A page that answers 403 or 406 usually means a server firewall is blocking the warmer by its user-agent, not that the page is broken. The status message names the user-agent to allow. A crawl that queues no URLs is reported as an error with the reason, not as a success.
6. **Stop it if the server struggles**: stop_preloader ends a running crawl. It is safe mid-run: pages already warmed stay cached. The agent can stop one site or every site in the workspace.

## Reference

| | |
| --- | --- |
| Start and stop | start_preloader and stop_preloader (write) |
| Progress | get_preloader_status (read): running or not, processed out of total, last URL, recent errors |
| What gets crawled | The sitemap (the WordPress one at /wp-sitemap.xml unless you set another), nested indexes followed, excluded URLs skipped |
| Needs | The preloader module switched on (it is off by default) and page caching on |
| Pages per run | 5 by default, 1 to 50, set in the preloader module |
| Schedule setting | manual, hourly, daily or weekly, set in the preloader module |
| Every site at once | start_preloader and stop_preloader accept site: "all"; get_preloader_status does not |
| Fan-out pacing | Sites start one after another with a 1 second pause, one result per site |
| Warmer user-agent | xSpeed-Warmer/1.0, the string a firewall rule would need to allow |
| Stopping | Safe mid-run; warmed pages stay cached |
| Read-only access | A Viewer member's sign-in, or the connection token with Read-only everywhere on: start_preloader and stop_preloader are refused; get_preloader_status works. An OAuth sign-in by anyone else gets the scopes the client asks for. |
| Confirmation | None on the Hub; your client's prompt is the gate |

## Rules

- Warm after a purge, not instead of one. The Hub tells the agent that starting the preloader after a purge saves the next visitor from paying for the rebuild.
- A crawl requests every page in the sitemap, so it adds load to the origin. Start with one site, and on a small host keep Pages per run low or stop the crawl if the site slows.
- start_preloader and stop_preloader are write tools. The Hub calls the preloader low-risk and only asks the agent to confirm when the target site is unclear or the call covers every site, so your client's approval prompt and read-only access (a Viewer sign-in, or the connection token with Read-only everywhere on) are the gates that matter.
- A fan-out only starts the crawls. Check each site with get_preloader_status afterwards, and treat some sites failing to start as a partial result, not a failure of the whole call.

## Good to know with OpenCode

OpenCode starts from permissive defaults. Until you add an ask or deny rule for xspeedhub_ tools, treat start_preloader and stop_preloader as able to run on the model's say-so, on any site the agent names. A blanket allow on xspeedhub_start_preloader also lets a start across all your sites through without a prompt, and then only the Hub's instruction to the agent stands between you and a workspace-wide crawl. That instruction is guidance, not a lock. Use a deny rule for a tool you never want called.

## More prompts for this job

They work in any client connected to xSpeed Hub.

- Use xSpeed Hub to start the preloader on shop and tell me how many URLs it queued.
- Using xSpeed Hub, how far through its crawl is blog? Show processed against total and any errors.
- With xSpeed Hub, purge the cache on docs, then warm it again.
- Use xSpeed Hub to start the preloader on every site in my workspace and tell me which ones refused.
- Use xSpeed Hub to stop the preloader on shop. It is slowing the server down.
- The preloader on shop says it is disabled. Use xSpeed Hub to turn the module on, then start the crawl.
- Using xSpeed Hub, which of my sites has no running crawl and a low hit ratio?

## Frequently asked questions

### How do I keep OpenCode from starting crawls without asking?

Add a rule that sets every tool whose name starts with xspeedhub_ to ask, then allow rules for the names that start with xspeedhub_get_ and xspeedhub_list_. OpenCode applies the last matching rule, so the catch-all goes first. Without it most permissions default to allow and a start runs unprompted. A read-only sign-in adds a second gate, either a Viewer member or the connection token with Read-only everywhere on, because the Hub then refuses every write tool.

### Does OpenCode work with the Hub through a terminal only?

Yes. OpenCode runs in your terminal and calls the Hub over the network, so you do not need a shell on the web server. The crawl itself runs inside the WordPress site, through WP-Cron.

### Why does start_preloader say the preloader is disabled?

The preloader module is off by default on a new install, and the site refuses to start a crawl until it is on. The agent can switch it on with update_settings on the preloader module, or you can turn it on in the xSpeed Cache panel in wp-admin. Page caching also has to be on, because the crawl exists to fill that cache.

### What does the preloader actually warm?

It reads the site's sitemap, which is the WordPress one at /wp-sitemap.xml unless you set a different sitemap URL, follows nested sitemap indexes and skips any URL your cache exclusion rules leave out. If the sitemap cannot be read, the site falls back to a list built from its own content and says so. If nothing at all is queued, the call reports an error with the reason.

### Can I warm every site with one prompt?

Yes. The agent passes site: "all" to start_preloader and the Hub starts the crawl on every site in the workspace one after another, returning a result per site. The Hub tells the agent to confirm that with you once first. The call only starts the crawls, so progress is read afterwards with get_preloader_status, one site at a time.

### Will warming slow my site down?

A crawl fetches your own pages, a few per run, so it adds load while it runs. The Pages per run setting controls how many, from 1 to 50 with a default of 5. If a site struggles, stop_preloader ends the crawl and the pages already warmed stay cached.

### Why do some pages fail with HTTP 403 or 406?

Those codes are what bad-bot firewall rules usually answer with, and they mean the warmer was judged by its user-agent, not that the page is missing. The warmer identifies itself as xSpeed-Warmer/1.0. Allow that user-agent in the server rule, or change it with the xspeed_preloader_user_agent filter, and run the crawl again.

### Can the agent keep my cache warm on a schedule?

The preloader has its own Schedule setting in WordPress: manual, hourly, daily or weekly. An agent can change it with update_settings. The Hub itself has no scheduler for agent prompts, so a prompt only runs when you send it or when your AI client runs it on a timer.

## Warm the cache with other agents

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

## More with OpenCode

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

## Documentation

- How to warm your cache ahead of visitors: https://xspeedcache.com/docs/preloader/
- How to crawl your sitemap: https://xspeedcache.com/docs/crawl-now/
- How to enable Page Cache: https://xspeedcache.com/docs/page-cache/
- Managing your fleet with xSpeed Hub: https://xspeedcache.com/docs/managing-your-fleet-with-xspeed-hub/