Documentation
Everything you need to install, configure, and use SmartFix.
Getting started
Installation
Install SmartFix from the WordPress plugin directory or upload the ZIP file manually.
Option A: From WordPress admin
- Go to Plugins → Add New
- Search for “SmartFix”
- Click Install Now, then Activate
Option B: Via WP-CLI
$ wp plugin install smartfix --activate
Option C: Manual upload
- Download
smartfix.zipfrom WordPress.org - Go to Plugins → Add New → Upload Plugin
- Upload the ZIP and activate
First run
After activation, SmartFix automatically registers your site with the analysis backend. No API key or account required.
You'll see the SmartFix menu item in your admin sidebar (shield icon). Click it, then click “Run Scan.”
Running scans
Click the “Run Scan” button on the SmartFix admin page. The scan process:
- Local scan (1–3s): Reads PHP files from all active plugins, extracts hooks, assets, post types, REST routes.
- Upload to backend (<1s): Sends extracted data to
smartfixwp.com/api/plugin/report. - Analysis (2–6s): Rule-based detection, known conflict database, and AI analysis.
- Results displayed: Conflicts appear in your admin panel, sorted by severity.
What gets sent to the server
// Exact payload structure
{
"plugins": [{
"slug": "plugin-name",
"hooks": [{"hook": "init", "priority": 10}],
"assets": [{"handle": "select2"}]
}]
}
No PHP source code. Only extracted metadata. No user data, no post content, no credentials.
Understanding results
Severity scale
Conflict types
| Type | Detection | Typical severity |
|---|---|---|
| Hook priority collision | Rule-based | 4–9 |
| Duplicate asset | Rule-based (handle fingerprint) | 5 |
| Post type collision | Rule-based | 8 |
| REST route collision | Rule-based | 6 |
| Cron collision | Rule-based | 4–6 |
| DB query conflict (Pro+) | Rule-based | 5–7 |
| Output conflict | AI-assisted | 5–8 |
| Resource conflict | AI-assisted | 4–7 |
| PHP error | Error log tailing | 5–9 |
| Known conflict | Data-driven (crowd-sourced DB) | Varies |
| Vulnerability conflict (Pro+) | Data-driven (CVE correlation) | 7–10 |
| Gateway conflict (Pro+) | WooCommerce deep scan | 7–9 |
| Checkout conflict (Pro+) | WooCommerce deep scan | 6–9 |
Auto-Fix Engine
Pro & Agency plans
When SmartFix detects a conflict with a known fix, it can apply a safe, reversible runtime shim. Fixes use standard WordPress APIs and never edit third-party plugin files.
How it works
- Pre-check — Verifies the fix is applicable.
- Apply — Registers the fix. Compatibility layer loads it on next page load.
- Verify — SmartFix checks that the fix is working.
- Rollback — Available at any time with one click.
Available executors
| Executor | What it does | Addresses | Sensitivity |
|---|---|---|---|
dequeue_script | Dequeues duplicate jQuery, Select2, Slick, etc. | Duplicate asset | Low |
dequeue_style | Dequeues duplicate Bootstrap, Font Awesome, Google Fonts. | Duplicate asset | Low |
reprioritize_hook | Changes a colliding hook callback to a safer priority. | Hook priority collision | Elevated |
modify_script_registration | Adds jQuery as a dependency / moves render-blocking scripts to footer. | Resource conflict | Elevated |
add_inline_script | Injects jQuery.noConflict() or similar compatibility shim. | Output / resource conflict | Elevated |
suppress_admin_output | Removes a conflicting admin notice callback. | Output conflict (admin) | Low |
reschedule_cron | Staggers colliding WP-Cron events so they stop piling up on the same tick. | Cron collision | Low |
reprioritize_woo_hook | Reorders colliding WooCommerce hook callbacks (cart, pricing, stock). | Hook collision (Woo) | Elevated |
dequeue_checkout_script | Dequeues a duplicate/conflicting script on the WooCommerce checkout. | Checkout conflict | Elevated |
Safety model
Level 1 — Safe auto-fix
Deterministic, reversible, uses only WordPress core APIs.
Level 2 — Approval required
Modifies hook execution order. Requires admin review.
Level 3 — Recommend only
Cannot be safely automated. Provides explanation only.
Confidence tracking
SmartFix tracks success rates and rollback counts for every strategy. If reliability drops below thresholds, the strategy is automatically paused.
Verification & rollback
If a fix fails verification 3 consecutive times, SmartFix automatically removes it. Manual rollback is instant and always available.
Post-update protection
Pro & Agency plans
When you update a plugin, theme, or WordPress core, SmartFix automatically runs a conflict scan within 60 seconds. Fixes targeting the updated plugin are automatically expired.
Bring Your Own Key (BYOK)
BYOK Pro & BYOK Agency plans
Use your own OpenAI or Anthropic API key for AI-powered conflict analysis at a reduced rate. Keys are encrypted with AES-256-GCM before storage.
- Subscribe to a BYOK plan
- Go to the BYOK tab in SmartFix
- Select provider, paste key, save
- SmartFix validates with a test call before saving
Dismissing conflicts
Click the × button on any conflict to dismiss it. To un-dismiss: delete the smartfix_dismissed_conflicts option, or deactivate and reactivate SmartFix.
API reference
These endpoints power the internal plugin-to-backend communication — they are not a public API. Listed here for transparency and for custom integrations that reuse the same site key.
/api/plugin/register Creates site record. Returns site key.
/api/plugin/report Sends plugin data, receives conflict analysis.
/api/plugin/status Returns latest scan results.
/api/plugin/dashboard Returns aggregated dashboard data.
/api/plugin/fixes Returns available fix strategies.
/api/plugin/fixes/apply Records fix application event.
/api/plugin/fixes/rollback Records fix rollback event.
All endpoints require X-Site-Key header (except /register).
Troubleshooting
"Site not registered" error
SmartFix auto-registers on first admin page load. If it fails, reload the SmartFix admin page. Registration retries every 5 minutes.
Scan takes too long or times out
Sites with 50+ plugins may take longer. Increase max_execution_time to 120s.
No conflicts found (expected some)
SmartFix is conservative. Only same-priority collisions on critical hooks are reported.
Fix shows "Verify failed"
The affected script may not load on the current admin page. Try visiting a frontend page first. Click Rollback if it persists.
Fix shows "Currently paused"
A strategy can be paused if it has too many failures across sites. You can still apply it manually.
Plugin files not found
SmartFix looks in WP_PLUGIN_DIR. Symlinked or non-standard locations may not be found.
FAQ
Does SmartFix modify any plugin files?
No. SmartFix is completely read-only for scanning. The Auto-Fix Engine applies runtime shims using WordPress APIs (wp_dequeue_script, wp_add_inline_script, etc.) but never writes to any plugin files.
Is it safe to use on production?
Yes. Scans are read-only admin operations. Auto-Fix uses only standard WordPress APIs, is always reversible, and auto-expires when plugins update.
What does "Behavior change possible" mean?
Some fixes change script loading behavior. This label means the fix is working correctly but you should verify your site looks right. If anything seems off, click Rollback.
Can a fix break my site?
Extremely unlikely. All Level 1 fixes are deterministic and reversible. If a fix fails verification 3 times, it is automatically rolled back.
What happens to fixes when I update a plugin?
Fixes targeting that plugin are automatically expired. This prevents stale fixes from applying to a new version.
What data do you collect?
Plugin names, versions, hook registrations, and asset handles. No user data, no post content, no credentials.
What about mu-plugins?
Currently, SmartFix only scans plugins in the standard wp-content/plugins/ directory. Mu-plugins and drop-ins are not scanned yet.
Can I use SmartFix with WP-CLI?
Not yet. A wp smartfix scan command is planned for a future version.