# Find out why WordPress pages are not cached with Hermes Agent

> Finding out why pages are not cached with Hermes Agent means asking an always-on agent to read xSpeed health checks through xSpeed Hub, one site at a time, and to tell a failed check from one that could not finish.

Page: https://xspeedcache.com/agent/hermes-agent/troubleshoot-cache/
Last updated: October 2026

Hermes Agent keeps running and has cron jobs, so a cache check can be a morning report instead of something you remember to do. You write the job as a prompt: for each of my sites, read the cache status and the health report, and list anything that is not fine.

get_health takes one site per call and does not accept every site at once. So the job reads list_sites first, then loops through the sites. In the example, one site's health report says xSpeed could not verify the nginx static rewrite. That is not a failure. The check did not finish, and a site that already has the snippet in place may be working fine. run_benchmark confirms that the cached request is a hit, and the agent files the item as not a fault. Without that rule in your prompt, a model may well report it as broken.

A cron run has nobody watching, so settle the approval question in the prompt and in the server entry, not in the moment. At the default trust setting Hermes adds no prompt for the Hub. With trust set to untrusted it asks before every Hub call, reads included, because the Hub does not mark its tools read-only, and a scheduled run has nobody to answer. So give the entry a tools include list of the read tools the report needs. Give the prompt a plain output format, such as one line per site with its status and one line for each open item. A report in a fixed shape is quick to read in the morning and easy to compare between days, and it keeps the model from rewriting a warning into something it did not say. Ask it to quote each warning exactly.

## Set up Hermes Agent 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 config.yaml

Add this entry under mcp_servers. auth: oauth tells Hermes to handle discovery, dynamic client registration, PKCE and token refresh itself. If you edit the file from inside a running session, Hermes reloads its MCP connections with a 30 second timeout, which is too short for a browser sign-in, so finish the entry and then run the login in the next step.

File: `~/.hermes/config.yaml`

```yaml
mcp_servers:
  xspeedhub:
    url: "https://app.xspeedcache.com/xspeed/mcp"
    auth: oauth
```

### 3. Sign in with hermes mcp login

Run this once. Hermes prints an authorization URL, opens your browser where it can, and waits for the callback on a local loopback port. Sign in to xSpeed Hub and approve. There is no token to paste; Hermes caches the credentials it receives under ~/.hermes/mcp-tokens. On a remote host, paste the redirect URL back into the terminal when Hermes asks, or forward the callback port over SSH.

```bash
hermes mcp login xspeedhub
hermes mcp test xspeedhub
```

Full setup: https://xspeedcache.com/agent/hermes-agent/

### 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. A Hermes server entry has a trust setting. The default, full, adds no approval prompt for that server's tools, and the approvals setting covers dangerous shell commands, not MCP tools. Set trust: untrusted on the xspeedhub entry and Hermes asks before every call to a tool that lacks a readOnlyHint of true. The Hub does not mark its tools that way, so with untrusted every Hub call asks, reads included. To remove writes instead of prompting, set tools.include on the entry to the read tools; the filter takes globs and include wins over exclude. The Hub itself has no confirmation step.

## Prompts

- Write a cron job that uses xSpeed Hub to read list_sites, then get_health for each site, and lists anything that is not a pass. Read tools only.
- In the morning xSpeed Hub report, say whether each warning is a failed check or one that could not finish.
- Using xSpeed Hub, run the benchmark for any site with a warning and note whether the cached request hit.

## Example session

```
You: Morning report: use xSpeed Hub to read the health of every site and list anything that is not fine.
  → list_sites [read-only]: 2 sites: shop, blog
  → get_health(site: shop) [read-only]: all environment checks pass
  → get_health(site: blog) [read-only]: xSpeed could not verify the nginx static rewrite; other checks pass
  → run_benchmark(site: blog) [read-only]: home page: 489 ms uncached, 71 ms cached, cached request was a hit
Agent: Report: shop is healthy. blog has one open item, and it is not a fault: the nginx rewrite check did not finish, and the benchmark shows blog hits the cache. If the nginx snippet is already in your server block, it may be working. Nothing to fix.
```

## How it works

1. **Start with the quick summary**: get_cache_status returns whether page caching is on, the stats (cached pages, size, hit ratio, last purge) and the web server xSpeed detected. It is a glance. If caching is off, or the hit ratio is far below what you expect, the agent moves on to the diagnostic.
2. **Run the diagnostic**: get_health is the tool for troubleshooting. It returns the environment checks with pass or warn tones (the advanced-cache.php drop-in, the WP_CACHE constant, rewrite rules, PHP and WordPress versions, caching plugin conflicts), the cache stats, 24 hourly hit and miss buckets and a 30-day hit-ratio series. The Hub tells the agent to use it, not get_cache_status, when you are troubleshooting rather than glancing.
3. **Time cached against uncached**: run_benchmark requests the home page once with the cache bypassed and once normally, after a warm-up request, and returns the timings. If the second request still is not a cache hit, the page cache is not serving the home page, and the result says so. It measures xSpeed's own response time. It does not return a Lighthouse score.
4. **Read what the checks mean**: A warn is a lead, not always a fault. A static-file rewrite warning, for example, can mean the nginx snippet is not in your server config yet, or that xSpeed could not verify it, which is not evidence the config is wrong. The agent reads the detail line and tells you which one it is.
5. **Fix it or hand it over**: If caching is simply off, toggle_cache turns it on. If another caching plugin owns the drop-in, the site refuses to enable xSpeed and says why; removing the other plugin is yours to do. If nothing explains it, contact_support emails xSpeed support with the agent's summary, after the agent has confirmed the message with you.

## Reference

| | |
| --- | --- |
| Quick check | get_cache_status (read): cache on or off, stats, detected web server |
| Diagnostic | get_health (read): environment checks, 24 hourly buckets, 30-day hit-ratio series, recent activity |
| One site per call | get_health does not accept site: "all"; call it for each site you care about |
| Benchmark | run_benchmark (read): home page only, cache bypassed against cache served, timings in milliseconds |
| Benchmark on every site | run_benchmark accepts site: "all" or a list of handles, one result per site |
| Benchmark history | get_benchmark_history reads past runs and the settings changes on the same timeline |
| Pro suggestions | get_pro_audit (read): which Pro features would help this site, from its settings and stats |
| Hit ratio scope | Counts requests that reach your server; pages answered by a CDN or Cloudflare edge are not counted |
| Support | contact_support emails xSpeed support with your account email and site list attached; classed read |
| Turning caching on | toggle_cache (write); refused by the site when another plugin owns the cache drop-in |

## Rules

- Diagnose with the read tools first. get_cache_status, get_health, run_benchmark and get_pro_audit change nothing on the site, so a read-only connection can run all of them. For clients that send the connection token, that means Read-only everywhere on; an OAuth sign-in gets the scopes the client asks for, unless the member is a Viewer.
- Do not answer a PageSpeed question with run_benchmark. It measures cached against uncached response time and returns no Lighthouse score; for a score, use the speed test or scan jobs.
- toggle_cache is a write. It runs as soon as your connection allows writes, and the Hub tells the agent to confirm the target site first. That is guidance to the agent, so your client's approval prompt is the gate that matters.
- contact_support sends a real email. The Hub tells the agent to confirm the message with you before sending, but the tool is classed read, so even a read-only connection can send one.
- The agent cannot edit your server configuration or another plugin's settings. When a check needs an nginx snippet or a conflicting plugin removed, it tells you what to do and you do it.

## Good to know with Hermes Agent

A cron job that covers every site is one list_sites call plus one get_health per site, well inside the Hub's limit of 600 calls per minute for an account. The risk is not volume but the prompt. If the job can purge or toggle, a mistaken diagnosis becomes a change. Write it as read-only, leave contact_support out of the include list, limit the job to the Hub's own toolset, and use the connection token with Read-only everywhere on if you want the Hub to refuse writes for you.

## More prompts for this job

They work in any client connected to xSpeed Hub.

- Using xSpeed Hub, why is the cache hit ratio so low on shop? Run the full health check and tell me the most likely cause.
- Using xSpeed Hub, is page caching actually working on blog? Benchmark cached against uncached and tell me if the second request was a hit.
- xSpeed Hub's get_health on docs shows a warning about the static-file rewrite. What does it mean and do I need to act?
- Use xSpeed Hub to check whether another caching plugin is conflicting with xSpeed on shop.
- Caching looks off on the staging site. Use xSpeed Hub to turn it on and tell me if the site refuses.
- Using xSpeed Hub, which Pro features would help the shop site, based on how it is set up now?
- With xSpeed Hub, compare the last few benchmark runs on blog and tell me whether my settings changes helped.

## Frequently asked questions

### Can Hermes Agent check the health of all my WordPress sites in one call?

No. get_health works on one site at a time. Hermes Agent reads list_sites and then calls get_health for each site in turn, which is fine for a scheduled report because the Hub allows 600 calls per minute per account.

### What does it mean when xSpeed could not verify the nginx rewrite?

The check did not complete, which is not evidence that your configuration is wrong. If you already added the snippet, it may be working. Ask Hermes Agent to run the benchmark to see whether the cached request is a hit.

### Why are my WordPress pages not being cached?

The common causes are that page caching is switched off, the advanced-cache.php drop-in or the WP_CACHE constant in wp-config.php is missing, another caching plugin owns the drop-in, or the pages set cookies or headers that make them uncacheable. An agent can read all of these from get_health through xSpeed Hub and tell you which one applies to your site.

### What is the difference between get_cache_status and get_health?

get_cache_status is a quick summary: whether caching is on, the stats and the detected web server. get_health is the diagnostic. It adds the environment checks with pass or warn tones, 24 hourly hit and miss buckets and a 30-day hit-ratio series. The Hub tells the agent to use get_health when you are troubleshooting.

### Does run_benchmark give me a PageSpeed score?

No. run_benchmark measures how fast your own cache answers compared with an uncached request for the home page. For a Lighthouse score, ask for a speed test or a speed scan instead.

### Can the agent check every site at once?

Only partly. run_benchmark accepts every site in one call. get_cache_status and get_health take one site per call, and get_health does not accept site: "all", so for a fleet the agent calls them site by site or you use the Hub dashboard for the rollup.

### Will troubleshooting change anything on my site?

Not with the diagnostic tools. They are read tools and change nothing. Changes only happen if the agent calls a write tool such as toggle_cache, which runs once your connection allows writes, so your AI client's approval prompt and a read-only connection (the connection token with Read-only everywhere on, or a Viewer sign-in) are the gates.

## Find out why pages are not cached with other agents

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

## More with Hermes Agent

- [Purge the WordPress cache with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/purge-cache/)
- [Scan a website for speed problems with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/speed-scan/)
- [Run and track PageSpeed tests with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/pagespeed-tests/)
- [Raise a WordPress site's PageSpeed score with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/optimize-site/)
- [Tune WordPress cache settings with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/cache-settings/)
- [Warm the WordPress cache with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/preload-cache/)
- [Set up the Redis object cache with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/object-cache/)
- [Manage Cloudflare caching with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/cloudflare/)
- [Manage every WordPress site at once with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/fleet/)

## Documentation

- How to read your cache diagnostics: https://xspeedcache.com/docs/cache-diagnostics/
- Understanding cache hits and misses: https://xspeedcache.com/docs/hits-and-misses/
- How to check your site health: https://xspeedcache.com/docs/health/
- Common problems and troubleshooting: https://xspeedcache.com/docs/common-problems-and-troubleshooting/
- How to enable Page Cache: https://xspeedcache.com/docs/page-cache/