If you’re using Claude Code, Cursor, Codex, Gemini CLI, or another AI coding assistant, you can give it the ability to profile WordPress endpoints, discover APIs, manage debug settings, and run query analysis — all through natural conversation.
This guide covers the setup and what to expect.
Run this from your project directory:
npx skills add WP-Debug-Toolkit/wpdt-cliThis installs the WP Debug Toolkit CLI skill into your agent’s skill directory. The skill includes:
wp isn’t directly available — see why that matters)After installation, you don’t need to configure anything else. The agent will use the skill automatically when relevant.
Once the skill is installed, you can make requests in natural language. The agent translates them into the right CLI commands.
The agent handles the CLI syntax, output parsing, and environment detection. You focus on what you want to know.
The quick examples above are one-shot commands. The real power shows up when you chain commands together in a conversation to investigate something specific.
You’re building a plugin and want to know what it does to query performance on a specific page or API route.
“Profile GET /wp/v2/posts and break down the queries by component. I want to see what my plugin adds.”
The agent runs wp dbtk api call GET /wp/v2/posts --profile and parses the profile output. It shows you the total query count, time, and a component breakdown — so you can see exactly how many queries came from your plugin vs. WordPress core vs. WooCommerce.
“Now deactivate my plugin and profile the same endpoint again so we can compare.”
The agent deactivates the plugin with wp plugin deactivate your-plugin, runs the same profiled call, and gives you a before/after comparison.
Profiling a single endpoint is useful, but sometimes you need to capture what happens during a full user flow — adding items to a cart, going through checkout, saving a post in the editor. You can’t profile that with a single CLI call because the queries happen across multiple page loads in the browser.
“Start a query recording tagged ‘checkout-flow’ so I can test something in the browser.”
The agent runs wp dbtk query-log start --tag=checkout-flow. Recording is now active. You go to the browser, add products to the cart, go through checkout — every database query across every page load is captured. Recordings auto-stop after 1 hour if not stopped manually.
“OK I’m done. Stop the recording.”
The agent runs wp dbtk query-log stop. The recording stops and the queries are saved.
“Show me a summary of what happened during the recording — queries per page, duplicates, performance scores.”
The agent runs wp dbtk query-log read --tag=checkout-flow --summary and shows a per-page breakdown: URL, query count, slow queries, duplicate groups, generation time, peak memory, and a performance score for each page load.
“How’s memory usage looking across those pages?”
The agent runs wp dbtk query-log read --tag=checkout-flow --memory and shows memory stats per page load: peak MB, current MB, limit MB, percentage used, and flags any high-memory requests.
“Now filter the recording to only show queries from my plugin and any N+1 patterns.”
At this point the agent can direct you to the standalone viewer with the right filters applied, or you can keep working in the terminal — asking it to look for specific patterns in the captured data.
“The WooCommerce orders page feels slow. Profile GET /wc/v3/orders and show me the 5 slowest queries.”
The agent profiles the endpoint and pulls out the slowest queries from the profile data. You see the SQL, execution time, and which component triggered each one.
“That third query looks like an N+1 — it’s running the same SELECT for every order. Can you check if there’s an N+1 pattern?”
The agent looks at the duplicate/N+1 data in the profile output and confirms whether the same query template is being repeated with different parameters.
“Profile it again with –profile=queries and give me the full query list as JSON so I can look at it myself.”
The agent runs the call with --profile=queries --format=json and gives you the raw output.
“Profile GET /wp/v2/posts with –profile=queries. Save that somewhere — I’m about to make a change.”
The agent runs the profile and holds the result in conversation context.
You make your code change.
“Profile the same endpoint again and compare. Did the query count go down?”
The agent runs the same call, compares the two results, and reports what changed — total queries, total time, any new slow queries, any queries that disappeared.
You’ve just started working on a site with WooCommerce, LearnDash, or another plugin and you want to understand what APIs are available.
“Discover all the REST API endpoints on this site and show me anything related to subscriptions.”
The agent runs wp dbtk api discover to scan all registered routes, then wp dbtk api search subscriptions to filter. You get a table of matching endpoints with their methods and descriptions.
“Show me the parameters for that renewal endpoint.”
The agent runs wp dbtk api show /wc/v1/subscriptions (or whatever the route is) and shows the full parameter list, types, and descriptions.
“Call it with some test parameters and profile it.”
The agent calls the endpoint with --profile and you see both the response data and the performance characteristics — before you’ve written a single line of code against it.
If you’re building features or fixing bugs with an AI assistant, you can use recordings to make sure your changes aren’t introducing performance problems as you go.
“Start a query recording tagged ‘before-fix’ — I’m going to test the checkout flow in the browser.”
You browse through the flow, then come back:
“Stop the recording and show me the summary. Any slow queries or duplicates?”
The agent stops the recording and runs --summary to give you the page-level overview — query counts, timing, memory, and performance scores for each page you hit. If something looks off, you dig in:
“Filter that recording to only show queries from my plugin. Are there any N+1 patterns or duplicates?”
Now you make your code change. Then you do it again:
“Start a new recording tagged ‘after-fix’ — I’ll test the same flow.”
You run through the same pages, stop the recording, and ask:
“Compare the two recordings. Did the query count go down? Any new slow queries?”
The agent pulls both tags and compares the numbers. This way you catch regressions immediately instead of discovering them in production. It’s a good habit to build into your workflow — record before, record after, compare.
When you ask “profile the products endpoint,” the agent:
bash .agents/skills/wpdt-cli/scripts/wp dbtk api call GET /wc/v3/products --profileYou’ll see the command in your agent’s tool output. The response includes both the API data and the performance profile.
The agent says wp is not found or gets a database error:
This is the most common issue. It means the agent’s terminal doesn’t have access to your local development tool’s PHP and MySQL. The wrapper script handles this automatically for Local by Flywheel. If it’s not working:
bash .agents/skills/wpdt-cli/scripts/wp --probe — this shows what environment was detectedThe agent doesn’t seem to know about WPDT commands:
The skill might not be installed. Run npx skills add WP-Debug-Toolkit/wpdt-cli from your project directory and start a new agent session.
The agent runs commands but gets permission errors (401/403):
The command needs to run as an authenticated WordPress user. Ask the agent to add --user=1 (or whatever your admin user ID is) to the command.
Profiling shows 0 queries:
This can happen if the endpoint returns a cached response or doesn’t trigger database queries. Try a different endpoint, or try with parameters that force a fresh database lookup (e.g., --params='{"per_page":10}').
If you open a Local by Flywheel site shell (the terminal icon in the Local app), wp dbtk works without any setup — Local’s shell has the right PHP binary and MySQL socket in its environment.
But AI coding assistants don’t run inside that site shell. They run in your regular terminal, which doesn’t have access to Local’s PHP or MySQL socket. The same applies to MAMP, Docker, and other tools that manage their own PHP/MySQL runtimes.
The wrapper script detects which environment you’re in (currently supports Local by Flywheel and standard WP-CLI installations) and constructs the correct invocation. You and your agent never need to think about PHP paths or socket locations.
The skill follows the Agent Skills open standard and works with:
.agents/skills/ convention