📈 ThemeMiles SEO Agent — Free User Guide
A complete walkthrough of every screen, setting, and feature included in the free version of ThemeMiles SEO Agent. No coding required — just install, configure once, and let the plugin scan your site.
1. What is ThemeMiles SEO Agent?
ThemeMiles SEO Agent is a WordPress plugin by ThemeMiles that automatically scans every published post, page, and product on your site for SEO problems — and tells you exactly what to fix, in order of business impact.
It works alongside your existing SEO plugin (Yoast SEO, Rank Math, or AIOSEO) rather than replacing it. ThemeMiles SEO Agent reads the SEO metadata those plugins write and audits it for completeness and quality.
🔍 Automated Site Audit
Scans up to 50 posts per batch across posts, pages, and WooCommerce products. Runs on a schedule or on demand.
🧠 SEO Brain Priority Scoring
Issues are ranked 0–100 by business impact so you know what to fix first, not just what's broken.
🏥 Site Health Score
A single 0–100 score that reflects your overall SEO health, updated after every audit run.
🔌 SEO Plugin Compatible
Detects Yoast SEO, Rank Math, and AIOSEO automatically. No manual configuration of field names needed.
The free plugin covers detection and reporting. ThemeMiles SEO Agent Pro adds AI-generated fixes, one-click apply, rollback history, Google Search Console integration, Core Web Vitals monitoring, and more. See full comparison →
2. Requirements
- WordPress: 6.3 or later
- PHP: 8.1 or later
- SEO plugin (recommended): Yoast SEO, Rank Math, or AIOSEO — at least one must be active for meta-title and meta-description checks to work. The audit still runs without one, but those checks will report no data.
- WooCommerce (optional): Product pages are automatically included in audits if WooCommerce is active.
Do not activate both ThemeMiles SEO Agent (free) and ThemeMiles SEO Agent Pro at the same time. The Pro plugin detects the free plugin and shows an admin notice until you deactivate it.
3. Installation
Download thememiles-seo-agent.zip from
WordPress.org
or from your ThemeMiles account dashboard.
In your WordPress admin, go to Plugins → Add New → Upload Plugin. Click Choose File, select the zip you downloaded, then click Install Now.
After installation completes, click Activate Plugin. WordPress redirects you back to the Plugins list.
After activation you will see an ThemeMiles SEO Agent entry in the WordPress left-hand admin menu, identified by a line chart icon (📈). The onboarding wizard opens automatically on the first page load.
4. Onboarding Wizard
The first time you activate ThemeMiles SEO Agent, an onboarding wizard appears as an overlay on any admin page. It walks you through 4 short steps. You can close it at any time — your progress is saved.
The wizard confirms which SEO plugin was detected (Yoast SEO, Rank Math, or AIOSEO). If none is detected, it suggests installing one before running the audit.
This step asks for an AI API key. Free users can skip this step — the audit engine does not require AI to detect issues. An API key is only needed by Pro users who want AI-generated fixes.
If you later upgrade to Pro, you can enter your API key at any time in ThemeMiles SEO Agent → Settings → AI Configuration.
Choose how often ThemeMiles SEO Agent should automatically re-scan your site. Options are Daily, Weekly, and Monthly. Free users default to Weekly. You can also choose a preferred time (e.g. 2:00 AM) to avoid peak traffic hours.
The final step confirms your setup and offers a Run First Audit Now button. Click it to immediately kick off your first full site scan. Alternatively click Done to dismiss the wizard and run the audit later from the dashboard.
5. The Dashboard
Navigate to ThemeMiles SEO Agent → Dashboard to reach the main overview screen. It contains two widgets that give you an instant snapshot of your site's SEO health.
The Dashboard — your SEO command center.
5.1 Audit Summary Widget
The top widget shows a compact health snapshot:
- SVG Health Gauge — a circular arc that fills proportionally to your SEO health score (0–100).
- Issue count boxes — three colored boxes showing how many Critical, Major, and Minor issues were found in the last audit.
- Last audit timestamp — shows when the most recent audit completed.
- Run Audit button — triggers an on-demand audit without leaving the dashboard. A spinner appears while it runs and the widget refreshes automatically when complete.
Audit Summary Widget — health gauge and issue counts at a glance.
5.2 SEO Brain Widget
The SEO Brain widget lists your top 5 highest-priority open issues ranked by business impact score. Each card shows:
- A rank number (1–5) with a color-coded background (red = urgent, amber = this week, blue = when possible).
- The post title — clicking it opens that post in the WordPress editor.
- The issue type badge (e.g., "Meta Title", "Alt Text") and the priority score (0–100).
- A Fix with AI button (free users) that opens the Pro upgrade prompt.
The header shows three summary counters: Fix Now, This Week, and When Possible.
SEO Brain Widget — top 5 priority issues sorted by business impact.
6. Running Your First Audit
You can trigger an audit from three places:
- The Onboarding Wizard (Step 4)
- The Run Audit button on the Audit Summary Dashboard widget
- The Run Audit Now button on the Audit Results page
Go to ThemeMiles SEO Agent → Audit Results and click the Run Audit Now button in the top-right corner of the page.
The audit runs in the background. A progress bar and status message ("Scanning posts… 50 / 120") appear at the top of the page. The UI polls every 3 seconds and refreshes automatically when the audit finishes. Auditing 100 posts typically takes 15–30 seconds depending on server speed.
Once complete, the page switches to the results view showing your SEO Health Score, a summary bar, and the full issue table. See Section 7 for a full breakdown.
After your first audit completes, a First Run Modal appears showing your current health score alongside an estimated score if you fixed all AI-fixable issues with Pro. It also compares Free vs Pro features side-by-side. This modal only appears once (stored in your browser's localStorage).
7. Audit Results Page
Go to ThemeMiles SEO Agent → Audit Results at any time to see the full issue list from the most recent audit.
The Audit Results page — health score, summary, filters, and every issue.
7.1 Health Gauge
The large SVG arc gauge at the top shows your overall SEO Health Score (0–100). The colour changes based on the score:
- Green (70–100) — Good health, minor issues only.
- Amber (40–69) — Moderate issues that need attention.
- Red (0–39) — Critical issues are hurting your rankings.
7.2 Brain Summary Bar
Below the gauge, three pill counters show how issues are distributed across priority tiers:
- Fix Immediately — Issues with a priority score above 70. These are hurting your rankings right now.
- Fix This Week — Priority score 40–70. Important but not urgent.
- Fix When Possible — Priority score below 40. Low-hanging fruit.
7.3 Filters
Use the filter bar to narrow down the issue list:
Show only Critical, Major, or Minor issues. Default shows all.
Filter by type, e.g. only "Missing Meta Description" or only "Thin Content" issues.
Show only "Fix Immediately", "Fix This Week", or "Fix When Possible" issues.
Show Open, Fixed, or Ignored issues.
Search by post title to find all issues for a specific page or article.
7.4 Issue Table
The table lists all detected issues, 25 per page, sorted by priority score (highest first by default). Each row shows:
- Post Title — links directly to that post's edit screen in WordPress.
- Issue Type — the category of SEO problem (e.g. "Meta Title", "Thin Content").
- Severity badge — Critical, Major, or Minor.
- Priority Score — 0–100 score with a colored indicator.
- Status — Open, Fixed, or Ignored.
- Fix with AI button — free users see the Pro upgrade prompt when clicked.
Click the ▶ expand arrow on any row to see the detailed breakdown: current field value, character length, threshold, and what needs to change.
| POST | ISSUE TYPE | SEVERITY | SCORE | ACTION |
|---|---|---|---|---|
| ▶ Best Running Shoes 2024 | Meta Title | Critical | 91 | Fix with AI |
| ▼ Top 10 Hiking Trails | Meta Description | Critical | 87 | Fix with AI |
|
Current Value
"Check out our guide to hiking." (32 chars)
Required Length
50 – 160 characters
⚠️ Meta description is too short. Google may auto-generate one from page content instead.
|
||||
| ▶ Beginner Yoga Guide | Alt Text | Major | 74 | Fix with AI |
Expand any row to see the current value and what's wrong with it.
8. Understanding Issue Types
ThemeMiles SEO Agent runs 12 SEO checks on every published post, page, and product. Here is what each check looks for and what it means:
| Issue Type | Severity | What it checks | How to fix it |
|---|---|---|---|
| Meta Title | Critical | Title is missing, under 30 characters, or over 65 characters. | Edit the post. In your SEO plugin's panel, write a title between 30–65 characters that includes your focus keyword. |
| Meta Description | Critical | Description is missing, under 50 characters, or over 160 characters. | Write a clear meta description of 50–160 characters. Include the main keyword naturally. |
| Duplicate Meta Description | Major | Two or more pages share the exact same meta description text. | Rewrite the description for each page so it is unique. Google may ignore duplicate descriptions. |
| Focus Keyword Missing | Major | No focus/target keyword is set in your SEO plugin for this post. | Open the SEO plugin panel for this post and enter the primary keyword this page should rank for. |
| Image Alt Text | Major | One or more images in the post content or attached to the post have no alt text. | Edit each image in the WordPress Media Library and add a descriptive alt text. For content images, edit the image block in the post editor. |
| Schema Markup | Major | No JSON-LD schema markup (structured data) is found on the page — neither in content nor from the SEO plugin. | Enable schema in your SEO plugin for this post type (e.g., Article, Product, FAQ). Rank Math and Yoast both handle this in their meta boxes. |
| OG Tags Missing | Minor | Open Graph title or description is empty — these control how the page appears when shared on Facebook, LinkedIn, etc. | In your SEO plugin's Social tab, add a custom OG title and description. If not set, most SEO plugins fall back to the meta title/description. |
| Thin Content | Major | Post content is under 300 words. Google considers thin content low-quality. | Expand the post with more useful, relevant information. Aim for at least 300–500 words for informational content. |
| Duplicate Title / H1 | Minor | The WordPress post title and the H1 heading in the content are identical — this wastes a heading-hierarchy opportunity. | Make the H1 in your content slightly different from the post title (or remove the manual H1 and let the theme generate it from the post title). |
| Missing Canonical URL | Minor | No canonical URL is set for the page. | Most SEO plugins set the canonical automatically. If yours does not, manually enter the canonical URL in the Advanced / Technical SEO tab of your SEO plugin. |
| Broken Internal Links | Minor | One or more internal links in the post content return a 404 status when fetched (up to 10 links checked per post). | Edit the post, find the broken links, and either update the URL or remove the link. |
| Keyword Not in Title | Minor | The focus keyword you set is not found anywhere in the meta title. | Update the meta title to include the focus keyword, ideally near the beginning. |
9. Understanding Your SEO Health Score
The health score is a single number from 0 to 100 that represents the overall SEO quality of all your published content. It starts at 100 and penalties are applied per issue:
- Critical issues: −1.0 point each
- Major issues: −0.35 points each
- Minor issues: −0.1 points each
For example: 5 critical + 10 major + 20 minor issues = 5×1.0 + 10×0.35 + 20×0.1 = 9.5 penalty → Score = 90.
Focus on Critical issues first — each one you fix recovers 1 full health point. Fixing 10 minor issues gives the same improvement as fixing just 1 critical issue.
10. Fix Queue Page (Free Preview)
Navigate to ThemeMiles SEO Agent → Fix Queue.
Free users see an upgrade preview of this feature rather than the full AI fix queue. The page shows:
- Stats banner — your total open issue count, how many are AI-fixable, and the estimated AI cost at ~$0.0003 per fix.
- PRO feature checklist — what you get when you upgrade (AI suggestions, diff view, bulk approve, auto-fix scheduling, rollback history).
- 3 real issue preview cards — your actual current field values are shown on the left; the right column shows the AI-suggested fix blurred behind a lock icon so you can see the format without seeing the content.
- "+N more issues" row — indicates how many additional fixable issues are waiting for you in Pro.
Free users see a preview — real current values on the left, AI fixes locked on the right.
AI-generated fixes, one-click apply, inline editing, bulk approve/reject, and auto-fix scheduling are all available with ThemeMiles SEO Agent Pro. Upgrade →
11. Fix History Page
Navigate to ThemeMiles SEO Agent → Fix History.
This page is exclusively available to Pro users. Free users see a simple upgrade prompt explaining what the feature does.
What Pro users see here: A full timeline of every AI fix ever applied, grouped by audit run, with before/after diff, ranking impact at 7 and 14 days (via Google Search Console data), and one-click rollback.
Fix history, rollback by fix, rollback by entire audit run, and ranking impact tracking require ThemeMiles SEO Agent Pro.
12. Settings
Go to ThemeMiles SEO Agent → Settings to configure the plugin. Changes save automatically when you click Save Changes.
12.1 AI Configuration Pro
Choose between OpenAI, Anthropic, or Groq. Groq is the fastest and often cheapest for simple SEO copy tasks.
Settings → AI Configuration → Provider
Enter your provider's secret API key. The key is stored securely server-side and never exposed to the browser. Free users can leave this blank — it is only needed for AI fix generation (Pro).
Settings → AI Configuration → API Key
The AI model to use. For OpenAI the default is gpt-4o-mini. The Test Connection button verifies your key and model work correctly.
Settings → AI Configuration → Model
12.2 Audit Schedule Free
How often the plugin should automatically re-scan your site. Options: Daily, Weekly (recommended for most sites), Monthly.
Settings → Audit Schedule → Frequency
The time of day (24-hour format) the audit should run. Defaults to 02:00 to avoid peak hours. The audit runs via WordPress Cron — it triggers on the next page load after the scheduled time.
Settings → Audit Schedule → Time
WordPress Cron runs only when someone visits your site. On very low-traffic sites, audits may run slightly later than scheduled. To fix this, use a real cron job or a plugin like WP Crontrol that can trigger cron via a server cron task.
12.3 Email Reports Free
Toggle on to receive an email summary after each scheduled audit. The email includes your health score, issue counts, and a link to the Audit Results page.
Settings → Email Reports → Enable Reports
The email address to send reports to. Defaults to your WordPress admin email. You can change it to any address.
Settings → Email Reports → Email Address
How often to email the report: Weekly or Monthly. This is independent of the audit frequency — you can audit daily but email a summary only weekly.
Settings → Email Reports → Frequency
12.4 Auto-Fix Rules Pro
These toggles control which field types the AI is allowed to fix automatically without your review. Free users see these controls but they have no effect — they only activate when an AI provider is connected (Pro).
Allow AI to automatically rewrite missing or out-of-range meta titles.
Allow AI to automatically rewrite missing or out-of-range meta descriptions.
Allow AI to automatically generate missing Open Graph titles and descriptions.
Allow AI to suggest focus keywords for posts that have none set.
12.5 YMYL Safety Free
When enabled (default: on), ThemeMiles SEO Agent marks pages as Your Money or Your Life (YMYL) if they are about health, finance, legal, or safety topics — based on URL slug, taxonomy terms, and keyword density. In Pro, YMYL pages are never auto-fixed; they are held in "Pending Review" so a human approves every AI suggestion before it goes live.
Settings → Safety → YMYL Safety Mode
It is strongly recommended to leave YMYL Safety on, especially for health, financial, or legal content. Google's quality raters apply stricter standards to these page types and inaccurate AI-generated content on YMYL pages can cause ranking drops.
13. SEO Plugin Integration
ThemeMiles SEO Agent automatically detects which SEO plugin is active on your site and reads the correct meta fields from the database. No manual configuration is needed.
| SEO Plugin | Detected automatically? | Fields supported |
|---|---|---|
| Yoast SEO | ✅ Yes | Meta title, meta description, focus keyword, OG title, OG description, canonical URL |
| Rank Math | ✅ Yes | Meta title, meta description, focus keyword, OG title, OG description, canonical URL |
| AIOSEO | ✅ Yes | Meta title, meta description, OG title, OG description, canonical URL |
| None detected | — | Image alt text, schema markup, thin content, broken links, and H1 checks still run. Meta/keyword checks report "no data". |
The detected SEO plugin is shown on the Dashboard and in the onboarding wizard. If you switch SEO plugins, deactivate the old one and activate the new one — ThemeMiles SEO Agent detects the change automatically on the next page load.
14. Audit Schedule Details
ThemeMiles SEO Agent uses Action Scheduler (the same library used by WooCommerce) to run reliable background jobs. When you set a schedule, the plugin registers a recurring action that fires at the chosen interval.
How scheduled audits work
- You set a frequency (weekly) and time (02:00) in Settings.
- The plugin schedules a background job to fire weekly at 02:00.
- WordPress Cron fires it on the next site visit at or after that time.
- Posts are scanned in batches of 50 to avoid memory limits.
- After all posts are scanned, priority scores are recalculated.
- If email reports are enabled, a summary is sent to your report email.
Changing the schedule
Go to Settings → Audit Schedule, change the frequency or time, and click Save Changes. The plugin cancels the old recurring action and schedules a new one immediately.
Triggering an audit manually
You can always run an audit on demand from the Dashboard (Run Audit button in the Audit Summary widget) or from the Audit Results page header. Manual audits do not affect the scheduled audit timing.
15. Free vs Pro Feature Comparison
| Feature | Free | Pro |
|---|---|---|
| Automated site audit (12 checks) | ✓ | ✓ |
| SEO Health Score (0–100) | ✓ | ✓ |
| Priority scoring (SEO Brain) | ✓ | ✓ |
| Audit Results page with filters | ✓ | ✓ |
| Scheduled audits (weekly) | ✓ | ✓ |
| Email audit reports | ✓ | ✓ |
| Yoast / Rank Math / AIOSEO integration | ✓ | ✓ |
| YMYL safety detection | ✓ | ✓ |
| AI-generated fix suggestions | ✗ | ✓ |
| One-click apply fixes | ✗ | ✓ |
| Bulk approve / reject fixes | ✗ | ✓ |
| Fix rollback (undo any change) | ✗ | ✓ |
| Fix History with impact tracking | ✗ | ✓ |
| Google Search Console integration | ✗ | ✓ |
| Core Web Vitals monitoring | ✗ | ✓ |
| GEO / AEO readiness scoring | ✗ | ✓ |
| Schema auto-generation (FAQ, HowTo, Product) | ✗ | ✓ |
| Competitor analysis | ✗ | ✓ |
| Autonomous mode (fully automated fixes) | ✗ | ✓ |
| Nightly summary emails (Pro digest) | ✗ | ✓ |
| Agency Dashboard (multi-site) | ✗ | Business+ plan |
16. Frequently Asked Questions
Will ThemeMiles SEO Agent replace my Yoast SEO / Rank Math plugin?
No. ThemeMiles SEO Agent works alongside your existing SEO plugin. It reads the meta fields those plugins write and audits them for quality. You still need Yoast, Rank Math, or AIOSEO to actually store and output your SEO metadata.
My audit shows "no data" for meta title / description. Why?
No SEO plugin was detected, or the detected plugin's meta key was empty for that post. Make sure Yoast SEO, Rank Math, or AIOSEO is active and that you have set meta titles and descriptions for your posts.
How long does an audit take?
Approximately 1–2 seconds per batch of 50 posts for standard checks. A site with 200 posts typically finishes in under 15 seconds. The broken-link check adds a few extra seconds per post since it makes HTTP requests.
Can I run an audit more than once per day on the free plan?
Yes. The audit schedule controls automatic runs. You can always click Run Audit Now from the dashboard or Audit Results page to trigger an on-demand audit at any time, regardless of schedule.
Does the audit affect my site's performance?
Minimally. The audit is designed to run in low-traffic hours (default 2:00 AM) and processes posts in batches of 50 to avoid exhausting PHP memory. The broken-link check caps at 10 links per post to limit outbound requests.
My post was fixed manually but the issue is still showing as "Open". How do I mark it resolved?
Run another audit. The plugin re-checks every field on every post during each audit run and automatically marks issues as Fixed if the problem is no longer present. You do not need to mark issues manually.
Can I use ThemeMiles SEO Agent on a staging site?
Yes. Install and activate it exactly the same way. Note that scheduled audits depend on WordPress Cron, which only fires on page visits — staging sites with no real traffic may need a real server cron to trigger it on schedule.
What is the difference between "severity" and "priority score"?
Severity (Critical / Major / Minor) is a fixed classification based on the type of SEO issue. Priority Score (0–100) is a dynamic ranking that also considers the post's traffic, search position, and overall importance to your site. A Minor issue on your #1 traffic page will have a higher priority score than a Critical issue on a rarely-visited page.
How do I uninstall ThemeMiles SEO Agent?
Deactivate and delete the plugin from Plugins → Installed Plugins.
The uninstall routine automatically removes all database tables
(wp_autoseo_issues, wp_autoseo_fixes,
wp_autoseo_snapshots, wp_autoseo_audit_runs) and all
plugin options and transients from the database. No data is left behind.
Where can I get support?
Free users can open a support thread on the WordPress.org support forum. Pro users receive priority email support at thememiles.com/support.