By the end of this page you know what every tool group lets an agent do, what each one needs before it can be switched on, and which groups to leave off.
Every tool belongs to one group, and every group has its own switch on the Settings tab under Tool groups. The switches apply to every client, whichever way it connects. A group that is off does not exist for any client: its tools are not listed and cannot be called.
The screen shows the groups in three sets.
| Set | Groups |
|---|---|
| Block theme | Theme files, Site Editor templates, Global styles, Patterns, Search and replace in content |
| Site | Browse, Site administration, Abilities |
| Beyond the theme | Read files, Write files, HTTP requests, Run PHP |
Next to each group’s name the screen shows how many tools it has. When a group cannot work on this site, its checkbox is disabled and the reason is printed under it.
How to read a tool
The Tools tab lists every tool, group by group, with a pill for the group (On, Off or Unavailable) and two badges per tool.
- Read-only, Write or Destructive. A destructive tool asks for confirmation before it runs: in the browser while Confirm destructive tools is on, and in the client itself for a remote client.
- Browser + HTTP or Browser only. A browser-only tool needs a tab and is never offered to a remote client.
Each row also has an Agent description: the text the agent reads to decide how to use the tool.
Block theme
These are the groups the plugin is built around. All of them start off.
Theme files
11 tools. Needs the edit_theme_options and edit_themes capabilities, the same ones the theme file editor in wp-admin needs. WordPress removes edit_themes when DISALLOW_FILE_EDIT or DISALLOW_FILE_MODS is set, and on a multisite network only a Super Admin holds it.
The tools work inside the active theme’s folder, on .html, .css, .js and .scss files and the root theme.json. They never write PHP.
- Read:
btm.theme-list-files,btm.theme-read-file,btm.theme-search - Write:
btm.theme-create-file,btm.theme-update-file,btm.theme-apply-changes,btm.theme-delete-file - Undo:
btm.theme-list-change-sets,btm.theme-revert-change-set,btm.theme-list-backups,btm.theme-restore-file
See Edit theme files: change sets, backups and undo.
Site Editor templates
9 tools. Needs edit_theme_options and an active block theme. The tools edit templates and template parts the way the Site Editor saves them, in the database.
btm.template-list, btm.template-read, btm.template-revisions, btm.template-create, btm.template-update, btm.template-restore-revision, btm.template-reset, btm.template-delete, btm.template-save-to-theme. The last one writes a file, so it also needs Theme files switched on.
Global styles
5 tools. Needs edit_theme_options and an active block theme. The tools read and change the styles and settings you would otherwise edit in the Site Editor’s Styles panel: btm.styles-read, btm.styles-update, btm.styles-revisions, btm.styles-restore-revision, btm.styles-reset.
See Global styles.
Patterns
7 tools. Needs edit_theme_options and an active block theme. The tools list and read every pattern, and create and change your own patterns: btm.pattern-list, btm.pattern-read, btm.pattern-create, btm.pattern-update, btm.pattern-revisions, btm.pattern-restore-revision, btm.pattern-delete.
See Patterns.
Search and replace in content
2 tools. Needs edit_others_posts and edit_theme_options. btm.content-search finds text or a CSS class in saved posts, pages, templates and patterns. btm.content-replace changes it, in two steps, with a revision saved before every write.
See Search and replace in content.
Site
Small groups for finding the way around a site. All three start on.
Browse
5 tools, no extra requirement.
btm.site-info: site addresses, WordPress and PHP versions, and which groups are on.btm.site-list: the sites the current user can reach. One row on a single site.btm.browse-navigate,btm.browse-current-url,btm.browse-open-tab: move the browser tab. Browser only.
Site administration
1 tool, btm.site-rename, which changes the site’s display name. Needs manage_options.
Abilities
One tool per Ability that plugins on your site have registered with the WordPress Abilities API and exposed. The tool takes the Ability’s name with the slash turned into a dot: my-plugin/get-thing becomes my-plugin.get-thing.
An Ability becomes a tool when it is registered with show_in_rest, or when its own mcp meta sets public to true. Expose non-REST abilities, the switch directly under Abilities, turns every other registered Ability into a tool too. It starts off.
An Ability tool asks for confirmation unless the Ability declares itself read-only or not destructive.
Beyond the theme
The screen introduces this set with: “These reach past the theme: other files on the server, any request your account can make, and running code. Leave them off unless you need them.” All four start off.
Read files
3 tools: btm.files-read, btm.files-list, btm.files-exists. Needs manage_options, and a Super Admin account on a multisite network. Paths are confined to wp-content.
Write files
4 tools: btm.files-write, btm.files-mkdir, btm.files-delete, btm.files-delete-directory. The plugin treats writing a file in wp-content as running code, so this group needs a constant in wp-config.php as well as its switch. Deletes are permanent: there is no backup and no change set here.
HTTP requests
1 tool, btm.request, browser only. It sends requests to your own site with your browser session’s cookies. With this group on, the agent can make any request your account can make on the site, wp-admin screens included. That is the same as handing it your logged-in session, so switch it on only when you want an agent driving the whole site.
Requests that write are refused for wp-admin, wp-login.php, xmlrpc.php, the plugin’s own routes and Ability runs, and every other write asks for confirmation first.
Run PHP
1 tool, btm.php-execute, which runs PHP with WordPress loaded. Needs a constant in wp-config.php as well as its switch.
For both constants, see Allow file writes or running PHP.
A sensible starting point
For theme work, switch on Theme files and Site Editor templates, and add Search and replace in content when a change has to reach saved content too. Leave everything under Beyond the theme off.