This guide connects your own AI assistant to your WordPress site. The fully guided core flow covers Claude Code, Claude Desktop, Codex, and ChatGPT. The WordPress backend additionally generates configurations for Cursor, Windsurf, Visual Studio Code, Gemini CLI, OpenCode, Cline, Roo Code, Kilo Code, Zed, GitHub Copilot, Amazon Q, and Antigravity. Once connected, the assistant can create blog posts and landing pages, and hardened WPAgently write paths check their changed values. Budget about 25 minutes.
Two things up front, so you can relax:
First, your content and WordPress logins stay exclusively with you. WPAgently runs on your own computer and site. Only license activation and the daily license check call Polar's license API directly, and native plugin updates read a static release manifest from wpagently.com. Neither request transmits content or WordPress credentials.
Second, the guide is split into six short steps. After each one, there's a line telling you how to know it worked. If a step feels too technical, it isn't. Just copy the commands exactly as they appear here into your terminal (the black window where you type commands). You don't need to understand any of it to run it correctly.
What you need before you start
These things should be in place before you begin. You probably already have most of them.
- WordPress 6.9+. As of version 6.9, the so-called Abilities API is included in the WordPress core. That's the interface the WPAgently add-on plugin uses later to talk to your site. You can find your WordPress version in the backend (bottom right, or under "Tools > Site Health").
- Pretty permalinks active (Settings > Permalinks, any option other than "Plain"). Permalinks are the structure of your URLs. A brand-new WordPress installation uses "Plain" by default, and in that state the technical interface the assistant connects through isn't reachable. This is by far the most common failure on the first try, and it's fixed in two clicks: open Settings > Permalinks, pick any other option, save.
- HTTPS on your site, meaning an address that starts with
https://. Browser OAuth, Application Passwords, and external clients such as Claude Code or Codex require it. Only a truly local installation atlocalhostor127.0.0.1may use HTTP for tests. If you need an Application Password there, also setWP_ENVIRONMENT_TYPEtolocal(see step 2). - PHP 8.1+. PHP is the programming language WordPress runs on; your version is also listed under "Tools > Site Health". Check whether your hosting offers a PHP upgrade before uploading the ZIP. WordPress correctly blocks the plugin upload on older PHP versions so an incompatible plugin cannot be installed. For a local test instance, additionally the PHP extension
pdo_sqlite. - Node.js 20 or newer on your computer. Node.js is the environment the small WPAgently program (the CLI from step 3) runs in. To check whether you have it, run
node --versionin your terminal. - Your own access to a compatible AI provider and one of two working paths. The fully documented external path uses Claude Code, Claude Desktop, Codex, or ChatGPT as an MCP client. Guided connection files are also available for Cursor, Windsurf, Visual Studio Code, Gemini CLI, OpenCode, Cline, Roo Code, Kilo Code, Zed, GitHub Copilot, Amazon Q, and Antigravity. ChatGPT requires a plan that supports custom apps in developer mode. Full write tools are currently available only in Business, Enterprise, and Edu workspaces. Alternatively, on WordPress 7.0 or newer you can use the integrated chat with an AI provider configured under Settings > Connectors. In both cases, WPAgently is the safety layer rather than the AI provider itself.
By the way, you don't need to install anything for the MCP Adapter (wordpress/mcp-adapter). MCP is the shared language AI assistants use to talk to external tools like your WordPress site. The add-on plugin from step 1 already includes this adapter, so no separate third-party plugin is required.
Step 1: install the Companion plugin (about 5 minutes)
Install and activate the wp-agent-companion plugin on your site, exactly the way you install any other WordPress plugin. "Activate" simply means switching the plugin on in the WordPress backend so it starts working.
This Companion plugin (companion = helper) is the heart of the setup on the WordPress side. It registers a set of "abilities" with WordPress. An ability is a clearly bounded, verified action the assistant is allowed to perform, for example "create a post from Markdown." After activation, these abilities, among others, are registered:
wp-agent/create-post-from-markdown(the verified ARTICLE pipeline's only writer for new article content; updates are currentlymanual_only)wp-agent/upsert-pattern(landing pages built from individual sections)wp-agent/get-seo-meta(read SEO fields in a provider-neutral shape;set-seo-metacurrently only preflights and returns HTTP 409 withmanual_onlybefore any provider mutation)wp-agent/render-verify(read-only: checks effective rendering, block structure, and the documented provider traps)wp-agent/refresh-hooks(catches up on follow-up work WordPress otherwise only does on an editor save: permalink rules, post cache, sitemap)wp-agent/write-theme-file(writes a file into the active theme, only.html,.json, and.css)wp-agent/disable-power(emergency off-switch for the separate power plugin)
This guide is bundled with Skills 0.4.86 and describes the Companion 0.4.117 and Power 0.6.35 release set. Its evidenced scope contains 414 registered Companion abilities, 317 in the recommended Content profile, 440 combined Companion and Power schemas, 414 Companion tools, and 34 reviewed public paths. Free provides exactly 34 tightly bounded core abilities without a licence key, site limit, or call limit. This documentation describes capability boundaries only. It does not assert a promotion, public availability, or a particular sales or update channel. The activity log and connection setup card are administrative and onboarding features, not abilities. It also does not claim an MCP pre-execution approval hook. New Pods models and missing Pods fields fail closed with HTTP 409 before mutation. Code Snippets single use has no ability and remains a later Power path. Elementor migration still produces a preview only. Content-model migration creates only new ACF-to-ACPT Lite definitions and transfers no field values. Beaver Lite exposes no native user templates, so those paths fail closed. Its primitive global-settings map is a separate, real provider path. GenerateBlocks deliberately writes neither rich text nor arbitrary plain text. The commercial Meta Box Settings Pages value runtime and other licensed or proprietary gaps are not externally certified. Power can upload and inspect extension archives in a bounded way, but it does not extract, install, update, overwrite, or activate a generic extension. Deferred extensions are listed in the roadmap.
The complete current list is in the Abilities reference.
After plugin activation, WPAgently Free is immediately available. No account or licence key is required. If you bought an annual licence, open Tools > WPAgently Licence, paste the licence key supplied by Polar, and select “Activate licence.” The activation counts this exact website against your plan's site limit and expands the same installation to the complete Companion surface. The Power plugin must also be installed and activated separately. Its own server-side gates remain closed until you deliberately unlock them. A temporary Polar outage does not immediately block a previously confirmed paid licence. The cached proof is accepted for at most seven days. Free remains available independently.
After plugin activation, the plugin automatically sets up its own MCP server at <site>/wp-json/wp-agent/mcp. Open WPAgently > Overview to inspect the master switch, access status, active ability profile, and concrete diagnostics. The setup card checks PHP, WordPress, HTTPS, staging prerequisites, and the connection path, then gives the next safe step without exposing credentials. The Read only profile connects an agent without exposing write tools. The additional domain lock belongs to the paid licence.
For the current builder catalog, use the reference only. It records the evidenced boundaries of the Companion 0.4.117 and Power 0.6.35 release set, bundled with Skills 0.4.86. It does not assert promotion or availability. The Content profile remains usable without the broader Design or Full access profile.
For dynamic builder data, always follow the schema from tools/list. Native block attributes and supports use the closed, integrity-bound {format,json,sha256,bytes} envelope. Elementor and Beaver Builder documents deliberately use the separate {json,sha256,bytes} envelope. Do not send raw JSON objects to these fields. Values that exceed the relevant provider-path boundary or do not fit its public contract are rejected, not silently truncated.
On WordPress 7.0 or newer, you can also use the integrated chat under WPAgently > Chat and Preview. First configure your own AI provider under Settings > Connectors. The chat researches only through approved read-only Abilities. Write suggestions appear as a plan and run as the selected Editor only after you approve each action individually. Messages and retrieved site data go directly from WordPress to your AI provider, not through a WPAgently AI proxy. The preview accepts only paths on the same site and disables page scripts and forms. Use Select element to click a visible part of the page and attach it as bounded context to your next message. The selection never executes the CSS selector and is explicitly treated by the model as untrusted website content.
For visible work in the Gutenberg or Elementor editor, open WPAgently > Live Editor, choose the dedicated Editor user, and start the workspace. The assistant can then use the existing MCP connection to open pages and use their confirmed editor workspace. Gutenberg changes first exist only in the browser and become persistent only through the separately approved save command. After your individual approval, Elementor changes run through the verified server-side Elementor path with conflict protection, revision, and readback verification. Close the session when the work is finished. Bricks, Breakdance, and Oxygen still have no confirmed visual runtime workspace.
Done when: the plugin shows as “Active” and Tools > WPAgently Licence reports “Free active” or “Paid.” Everything else is verified automatically in step 5.
Step 2: create a dedicated Editor bot (about 3 minutes)
Open WPAgently > Connect agent and select “Create dedicated agent user.” The plugin creates an Editor with a random internal login password. We call this separate user the “bot user.” The assistant works through this account, never through your own. You can revoke the bot's access without locking yourself out.
The bot gets the Editor role, never Administrator. If your WordPress backend runs in German, this role is called "Redakteur" in the UI (the technical name stays editor, which is exactly what WPAgently checks). An admin account in the wrong hands would be the worst-case damage, so WPAgently refuses to do any work as soon as the bot carries admin rights. That's deliberate, and it protects you.
Application Passwords require HTTPS. An Application Password is a special WordPress password just for programs and tools, separate from your normal login, that you can revoke at any time. If your instance runs locally without an SSL certificate (that is, without https://), add this to the wp-config.php file instead:
define( 'WP_ENVIRONMENT_TYPE', 'local' );Without one of the two conditions (HTTPS or this line), the "Application Passwords" menu item doesn't even appear in the profile.
For an OAuth-capable client, copy only the displayed MCP URL under WPAgently > Connect agent. The client opens the WordPress login on first connection. Select the new Editor there and approve access. No password is written to a configuration file.
Only when your client does not support OAuth should you select the Editor under “Application Password fallback” and download the matching configuration once. The plugin creates a separate Application Password and never stores its plaintext. Never commit the downloaded file. You can revoke the connection later in the agent user's profile.
The CLI does not need another Application Password. Its recommended flow in step 4 uses browser OAuth. You select this exact Editor on the consent screen and approve access. Another Application Password remains an explicit fallback only when browser OAuth cannot work in your environment.
If WPForms is active, three separate permissions for forms, entries, and writes appear further down. Form reading is prepared automatically for a newly created agent user, but this does not expose any tools by itself. Entry access always stays off because submissions may contain personal data. Writes additionally require WPForms' own toggle under WPForms > Tools > AI MCP and the corresponding group under WPAgently > Overview. The agent remains an Editor throughout. No Administrator capability is added. The three permissions apply only at WPAgently's MCP endpoint. Normal WPForms admin, AJAX, and foreign REST surfaces remain closed.
If Ninja Forms is active, four separate permissions appear for form reads, sensitive submissions, form changes, and email delivery. Only form reading is prepared for a newly created agent user. The active WPAgently profile remains a separate gate for the tools themselves. Submissions, writes, and email delivery must each be enabled explicitly. The broad Ninja Forms capability nf_edit_forms is mediated only during a matching call at WPAgently's MCP endpoint and is never persisted on the user account. Eight risky deletion, settings, secret, and submission paths remain fully blocked.
Done when: the agent user has the Editor role and you either copied the OAuth MCP URL or downloaded the fallback configuration once.
Step 3: install the CLI (about 2 minutes)
Now the small WPAgently program comes onto your own computer. It's called a CLI (command-line tool), a program you don't click but start by typing a command in your terminal. This CLI is the remote control you'll use to set everything up and check it.
The wp-agent CLI ships as a Node package in the delivered archive wp-agent-<version>.tgz (<version> stands for the version number, which appears in the file name of your download). Install it globally directly from this archive:
npm install -g wp-agent-<version>.tgzThen verify the installation:
wp-agent --helpThe output must list the available commands, including login, logout, preflight, abilities, doctor, article, and landing. If you see this list, the CLI is installed.
On Windows, the CLI automatically recognizes a native wp.exe and the usual WP-CLI or Local wp.bat and wp.cmd launchers. It never executes batch files through cmd.exe. When the official adjacent wp-cli.phar exists, WPAgently launches PHP and the PHAR directly. If WP-CLI or PHP is not on PATH, set their absolute paths in PowerShell:
$env:WP_AGENT_WP_CLI_BIN = "C:\path\to\wp.bat"
$env:WP_AGENT_PHP_BIN = "C:\path\to\php.exe"WP_AGENT_WP_CLI_BIN may point to wp.exe or wp-cli.phar instead. These variables apply only to local backup and restore runs that use WP_AGENT_WP_PATH. Remote backups and normal REST or MCP connections do not require a local WP-CLI installation.
By default, the CLI's own output (help text, error messages, prompts) is in German. To get English output instead, pass --locale en (alias --lang en) on any command, or export WP_AGENT_LOCALE=en in your shell so it applies to every invocation. A CLI flag always wins over the environment variable, and both fall back to German (de) if unset. This setting controls only the CLI's own messages, not the language of the content an agent generates through the pipelines.
Done when: wp-agent --help shows the command list instead of an error like "command not found".
Step 4: connect the CLI through the browser (about 3 minutes)
First, store only the base address of your site in the shell. Do not include /wp-json or a trailing slash:
export WP_AGENT_SITE="https://your-domain.tld"Then start the login:
wp-agent login --site "$WP_AGENT_SITE"The CLI registers its own public OAuth client, opens your browser, and waits locally for the response. Sign in to the WordPress backend, select the Editor from step 2, and approve access. The CLI then stores a short-lived access token and a rotating refresh token in your private local configuration directory. On macOS and Linux, only your user can read the directory and file. Neither your WordPress password nor the Editor's password is given to or stored by the CLI.
By default, a site stores at most 200 OAuth clients, pending sign-ins, and active connections. Large installations can adjust this server-side through wpagent_companion_oauth_max_clients. Valid values are integers from 1 through 10,000. Invalid values fall back to 200. Increasing the limit grows option storage and should be done only for a concrete capacity need.
If the browser cannot open automatically, wp-agent login --site "$WP_AGENT_SITE" --no-open prints the consent URL for manual opening. wp-agent logout --site "$WP_AGENT_SITE" revokes server access and removes the local record. Use --force only if the server is permanently unreachable. It removes the local record without claiming to have revoked the server grant.
Application Passwords remain available as a fallback. Set WP_AGENT_USER and WP_AGENT_APP_PASSWORD, or pass --user and --app-password. Explicit password credentials take precedence over stored OAuth credentials. Credential flags can be visible in process lists and shell history. The CLI does not load a .env file automatically.
wp-agent init is not required for normal CLI login. By default, it creates static MCP connection files for Claude Code, Codex, Cursor, Windsurf, Visual Studio Code, Gemini CLI, OpenCode, Cline, Roo Code, Kilo Code, Zed, GitHub Copilot, Amazon Q, and Antigravity and requires a separate username and Application Password for that purpose. Claude Code and Codex additionally support the user-wide OAuth registration in step 6, which needs no WordPress password. In this guided flow, you already downloaded the appropriate client file directly from WordPress in step 2.
Done when: wp-agent login reports a successful connection. The CLI automatically renews expiring tokens from then on.
Step 5: smoke test (about 6 minutes)
Now the big moment: we run one full check to see whether everything works together. "Smoke test" is just a common term for "switch it on briefly and see if it smokes," in other words a quick sanity check.
First, run the all-around check:
wp-agent doctorThe command performs seven checks: reachability, authentication, bot role, license, central Companion control, core abilities, and MCP. The connection is ready only when all seven report OK. If a prerequisite fails, wp-agent doctor marks dependent checks as not run. An unreachable control endpoint can therefore never appear green as an empty but supposedly complete ability or MCP list.
For a targeted individual check, wp-agent preflight (bot role only) and wp-agent abilities (ability list only, each marked readonly [R] = read-only or write [W]) are also available.
Finally, you create a first test draft from a tiny text file. Create it, for example, with printf (a command that simply writes text into a file):
printf '## Smoke test\n\nA paragraph with **bold** text and a list:\n\n- one\n- two\n' > test.mdGenerate the test article from it:
wp-agent article --markdown-file test.md --title "Smoke Test" --slug smoke-testThe result must report freeform: 0 in English CLI output. If you kept the default German CLI output, the same marker appears as Freiform: 0, with Freiform=0 in the render line. This means the formatting was cleanly converted into real WordPress blocks and nothing ended up in the old, broken editor view. The post automatically stays a draft, so you won't accidentally publish anything.
This smoke test deliberately produces a minimal article. A complete first post with a featured image and a subsequent SEO read is created via the wp-article skill (Claude Code) or the matching flags (--image, --alt, --seo-title, --seo-description, see wp-agent article --help). With Companion 0.4.30 or newer, the article pipeline automatically streams local featured images through the short-lived direct upload. With older Companion versions, it keeps using the previous Core REST upload as a compatible fallback. Public image URLs are downloaded after every redirect target has passed the SSRF checks again. Rank Math, Yoast, AIOSEO, or SEOPress must be active for SEO fields. set-seo-meta validates the input, reads the state freshly, and currently returns HTTP 409 with manual_only across providers before any mutation. Make desired changes in the SEO plugin manually and read them again through get-seo-meta.
The article and landing pipelines also require the flat remote_create and manual_only_update write semantics from tools/list, together with the general manual_only annotation. Companion versions that do not provide these metadata fields are not treated as compatible for combined pipelines: the CLI fails closed before the first remote mutation because it cannot safely detect a later manual-only 409 writer. This affects existing Markdown updates as well as SEO and status steps. Individual Abilities remain usable according to the schema installed with them. For pipelines, the CLI and Companion must therefore come from a semantically compatible release line.
Done when: wp-agent doctor reports OK seven times and the test article lands as a draft with freeform: 0 or Freiform: 0 in your WordPress. A --publish invocation currently does not change status automatically because set-post-status fails closed with manual_only. Publish or change status manually in WordPress after review. From here on, the connection is up.
Step 6: connect the agent (about 4 minutes)
Now add the connection file downloaded in step 2 to your assistant. It is separate from the CLI's OAuth login.
For Claude Code, .mcp.json is directly usable: place the file in your project directory. Claude Code detects the MCP server from it automatically on the next start. Alternatively, register the same site once in user scope without a static WordPress password:
wp-agent init --agent claude --scope user --site "$WP_AGENT_SITE" --i-approveThe command invokes the installed Claude CLI without an Authorization header. It does not overwrite an existing user entry with the same name. Then open /mcp in Claude Code and complete OAuth in the browser. If you deliberately need a project-local file instead, wp-agent init --agent claude still creates .mcp.json with a separate Application Password.
Codex can also be registered user-wide without a static WordPress password:
wp-agent init --agent codex --scope user --site "$WP_AGENT_SITE" --i-approveThe command checks an existing entry with the same name first and does not overwrite a different or secret-bound configuration. After creating an entry, it reads the saved endpoint back exactly. Then run the codex mcp login <name> command shown in the output. WPAgently does not open a browser without asking.
For Claude Desktop, do not use wp-agent init. In WordPress, open WPAgently > Connect agent, select Claude Desktop, and download the site-specific .mcpb file. Open it locally with Claude Desktop and approve the extension. The .mcpb contains a dedicated, revocable WordPress Application Password, so treat it as a secret. A direct remote entry from .mcp.json does not work in Claude Desktop.
For Codex, paste codex-mcp-wp-agent.toml into ~/.codex/config.toml or the .codex/config.toml of a trusted project. Codex connects directly to WordPress through Streamable HTTP. The generated block sets default_tools_approval_mode = "writes", so write tools require confirmation. No local bridge process or extra npm dependency is needed. Here too, wp-agent init --agent codex is only an alternative way to create the file with a separate Application Password.
The CLI also creates the same client-specific connection files for Cursor, Windsurf, Visual Studio Code, Gemini CLI, OpenCode, Cline, Roo Code, Kilo Code, Zed, GitHub Copilot, Amazon Q, and Antigravity. Use wp-agent init --agent cursor, windsurf, vscode, gemini-cli, opencode, cline, roo-code, kilo-code, zed, github-copilot, amazon-q, or antigravity. wp-agent init --agent all writes all fourteen supported MCP variants to the selected output directory. Merge mcpServers from the GitHub Copilot file into ~/.copilot/mcp-config.json, .mcp.json, or .github/mcp.json. For Amazon Q, use ~/.aws/amazonq/default.json or .amazonq/default.json. Depending on the installed Antigravity version, use ~/.gemini/config/mcp_config.json or ~/.gemini/antigravity/mcp_config.json. Open MCP Servers > Manage MCP Servers > View raw config to find the path that your installation actually uses. Merge the Cline file into ~/.cline/mcp.json or the extension's MCP settings file, the Roo file into the global mcp_settings.json or .roo/mcp.json, the Kilo file into ~/.config/kilo/kilo.json or .kilo/kilo.json, and context_servers from the Zed file into your Zed settings. These files contain the Application Password and therefore use private file mode 0600. Merge the relevant entry into the existing client configuration instead of overwriting unrelated server entries.
For ChatGPT, work on the web and open the Apps area. Depending on the plan, it appears in personal settings or workspace settings. In Business, only an admin or owner can enable developer mode and deploy a custom app. In Enterprise and Edu, the person creating the app needs the permission assigned by an administrator. Enter the MCP URL shown under WPAgently > Connect agent, select OAuth authentication, scan the tools, and complete the WordPress consent flow in the browser. ChatGPT connects directly to your WordPress site. Local MCP servers are not supported. Under ChatGPT's current rules, full write tools require a Business, Enterprise, or Edu workspace. ChatGPT Pro currently limits custom MCP connections to read and fetch operations.
Then confirm in the respective assistant that tools/list shows the wp-agent-* tools (tools/list is the list of tools the assistant knows from your site). wp-agent doctor in step 5 already verified this server-side; here you're only making sure the assistant itself connects cleanly. After that, wp-site-context-en selectively loads site context, the design profile, matching site skills, and relevant memories. If one design direction is active, the skill additionally loads its voice, rules, avoid patterns, and validated profile. Inactive directions remain unused. The execution skills wp-article-en, wp-landing-en, wp-reference-en, and wp-content-en guide the verified workflows. wp-feedback-en prepares a reproducible, privacy-conscious report for user review when something fails and never sends data automatically.
The skills themselves come from the included skills bundle wp-agent-skills-<version>.zip. Replace <version> with the version number from your download. The ZIP contains a dependency-free installer. The first run previews the plan. After your approval, the second applies the complete skill set as one transaction for Claude and Codex. If one skill fails, skills installed or replaced earlier in that run are rolled back:
unzip wp-agent-skills-<version>.zip -d wp-agent-skills-bundle
node wp-agent-skills-bundle/skills/install.mjs --agent both --locale en
node wp-agent-skills-bundle/skills/install.mjs --agent both --locale en --i-approveIdentical existing skills are skipped. Different local versions remain untouched unless you deliberately add --replace. The Power skill is never installed implicitly. Add --include-power when you deliberately want it. For a manual installation, the six English standard skills map to these paths:
mkdir -p ~/.claude/skills/wp-article-en ~/.claude/skills/wp-landing-en ~/.claude/skills/wp-reference-en ~/.claude/skills/wp-content-en ~/.claude/skills/wp-site-context-en ~/.claude/skills/wp-feedback-en
cp -R wp-agent-skills-bundle/skills/en/wp-article/. ~/.claude/skills/wp-article-en/
cp -R wp-agent-skills-bundle/skills/en/wp-landing/. ~/.claude/skills/wp-landing-en/
cp -R wp-agent-skills-bundle/skills/en/wp-reference/. ~/.claude/skills/wp-reference-en/
cp -R wp-agent-skills-bundle/skills/en/wp-content/. ~/.claude/skills/wp-content-en/
cp -R wp-agent-skills-bundle/skills/en/wp-site-context/. ~/.claude/skills/wp-site-context-en/
cp -R wp-agent-skills-bundle/skills/en/wp-feedback/. ~/.claude/skills/wp-feedback-en/The target paths must also include ~/.claude/skills/wp-site-context-en and ~/.claude/skills/wp-feedback-en. The installer uses ~/.codex/skills for Codex. The included docs/en/AGENTS.wp-agent.md and docs/en/agents/codex-content.md remain available as a fallback for clients without skill support. Without this bundle, the agent does not know these workflows, even if the MCP connection itself is already up.
Done when: your assistant shows the wp-agent-* tools in tools/list and knows the copied skills. From now on you can ask it to build a real article or landing page. Hardened write paths check their changed values in the background.
Diagnostics
You can also run an external connection diagnosis under WPAgently > Connect agent. Without sending credentials, WordPress requests its public REST API, MCP endpoint, and OAuth metadata through the normal website address. This reveals many CDN, firewall, and security-plugin blocks that a purely internal check cannot see. Detected intermediaries and known active security plugins are shown as hints, not automatically blamed as the cause. If a connection that was used successfully later loses authentication, WPAgently also warns administrators and links directly to this diagnosis.
The seven checks of wp-agent doctor (see step 5) in detail. The command runs through them in order and reports OK or ERROR per check with a plain-text hint. If one comes back red, here's the cause:
- Reachability: is the site reachable at WP_AGENT_SITE, and does the technical interface at
/wp-jsonrespond with the expected data (JSON)? Most common beginner mistake: with "Plain" permalinks,/wp-json/returns the homepage as HTML instead of the expected data. This check detects that and gives you a permalink hint instead of falsely showing green. Fix: enable pretty permalinks (Settings > Permalinks). - Auth: does the stored OAuth grant sign in the selected Editor correctly? The CLI refreshes a token before it expires. A failure usually means the server grant was revoked. Run
wp-agent logout --site "$WP_AGENT_SITE" --force, thenwp-agent login --site "$WP_AGENT_SITE". With the password fallback, check the username and Application Password instead. - Bot role: does the bot carry the Editor role and not Administrator? This is the same check as
wp-agent preflight; admin rights are a hard stop, and that's deliberate. - License: is the local license proof valid and within the permitted offline grace period?
- Control: are the master switch, domain lock, and ability profile valid, with no failed server-side diagnostics?
- Abilities: are all abilities enabled by the control center registered? If any are missing, inspect the profile and master switch under
WPAgently > Overview. - MCP: does the server at
<site>/wp-json/wp-agent/mcprespond cleanly, and doestools/listcontain the tools for every ability enabled by the control center? If the server is missing despite the plugin being active, the plugin was shipped incompletely and needs to be rebuilt.
For a targeted individual check, wp-agent preflight (check 3) and wp-agent abilities (check 6) repeat the same aspect in isolation. wp-agent login establishes CLI access but is not one of the seven Doctor checks. wp-agent init also tests nothing. It only writes optional static connection files (see step 4).
The overall architecture is described in the architecture documentation.
Troubleshooting: the five silent failures
There are five places where naive AI setups regularly fail silently. WPAgently catches them and makes the failure visible before unnoticed damage occurs:
- The article suddenly shows up unformatted (the Classic Editor fallback,
core/freeform) - The SEO change stops visibly with HTTP 409 and
manual_onlybefore any provider field changes - Google never hears about the new post (sitemap or cache doesn't update)
- Images open a security hole, or alt text and featured image are missing
- The same article lands on your site twice on a second run
Symptom, cause, and fix for each of these five failures (including the exact messages WPAgently aborts with) are covered in detail in troubleshooting, part 1. It also covers special cases of individual features (WooCommerce, ACF, Contact Form 7, Fluent Forms, Gravity Forms, WPForms, Ninja Forms, page builder detection, part 2) and the read-only tools you can use yourself to check what's stored on a post (part 3).
Optional: power/developer mode
This guide sets up only the verified core (wp-agent-companion), and for blog posts and landing pages that is the only path you need. For direct access to files, database, and PHP execution, there is a second, completely separate, and off-by-default plugin, wp-agent-power. It is a deliberate, separate decision and not part of the standard setup. If the terms mean nothing to you, you very likely don't need this mode.
Anyone who wants to use power mode additionally installs dist/wp-agent-power-<version>.zip. Enable the master and only the required stages under Tools > WPAgently Power. Then wp-agent power init verifies the server state and creates the local session after explicit confirmation. The complete gates, remote backup and restore paths, and limitations are covered in the Power documentation, section 16.
The wp-power-en skill also lives in the skills bundle, but is deliberately never installed by default. Install it only when you intend to use this mode:
node wp-agent-skills-bundle/skills/install.mjs --agent both --locale en --include-power
node wp-agent-skills-bundle/skills/install.mjs --agent both --locale en --include-power --i-approveFor Codex, add the included section docs/en/agents/codex-power.md to your AGENTS.md only if you deliberately intend to use this mode.