Skip to content
OctoPress Docs
Install Free Get Pro
OctoPress Pro Pro

Plugin and theme development

Use Development Planner for read-only plans and Builder for scoped file changes, validation and code execution.

The WordPress Development extension adds two agents: Development Planner inspects projects and proposes plans without writes or execution, while Builder implements plugins, themes and integrations. Builder's tools can change files and run code, so read this page before you switch them on.

Set up a project#

Development tools work inside a working root: the project's folder, or wp-content when the chat has no project.

  1. Create a project and choose a working root. Pick an existing plugin, theme or MU plugin, a custom path such as plugins/my-plugin, or Create new to scaffold a WordPress plugin or Block theme. See Projects.
  2. Start a chat in that project with Builder or Development Planner.

Paths in tool calls are relative to the working root. Absolute paths and .. are rejected. If the project's folder disappears, file tools fail with a clear error until you fix the root.

Tools#

Group Tools Approval
Files List project files, Read project file, Search files No
Files Write project file, Replace in project file, Create project directory, Apply project patch Yes
Validation PHP Syntax Lint, npm Build, npm Typecheck No
Shell Run shell command Yes. Disabled by default.
Code Runner Run PHP code (WordPress loaded) Yes

To use Run shell command, switch it on in Settings → Tools and make sure the Shell runtime is active in Runtime.

Shell commands and PHP code are not sandboxed. They run with the permissions of your web server's PHP user, and approved code can reach anything that user can. Use them on staging sites, read every approval, and avoid Approve all for these tools.

A good loop#

  1. Explore: ask Octo to summarize the project (starter card Explore this project).
  2. Plan: use Development Planner for non-trivial development and review the plan, then confirm the handoff to Builder. See Questions, plans and handoffs.
  3. Edit: Builder proposes file changes; each write shows the target path and waits for approval.
  4. Validate: lint and build (starter card Lint and build) and let Builder fix what fails.

Development skills#

Pro includes skills for the tools above, codebase exploration, plugin development, UI design, dependency management, validation and tests, and extending OctoPress itself. See Agents and skills reference. Developers can read the full tool contract in docs/code-tools.md in the plugin repository.

Notes#

  • Dependency installs (npm or Composer) are not available as tools. Run them yourself.
  • Octo can use npm run build and npm run typecheck only if the project defines those scripts.

    Type to search.