Agent Tools (AI) module

[ryan]

Enables AI coding agents to access ProcessWire’s API. Also provides a content migration system.

This module provides a way for Claude Code (or other AI helpers) to have full access to the ProcessWire API via a command-line interface (CLI). Once connected to your site, you can ask Claude to create and modify pages, templates and fields, or do anything that can be done with the ProcessWire API. It's even possible for an entire site to be managed by Claude without the need for ProcessWire's admin control panel, though we're not suggesting that just yet.

While working with Claude Code, I asked what would be helpful for them in working with ProcessWire, and this module is the result. Claude needed a way to quickly access the ProcessWire API from the command line, and this module provides 3 distinct ways for Claude to do so.

Claude collaborated with me on the development of the AgentTools module, and the accompanying ProcessAgentTools module was developed entirely by Claude Code.

Admittedly, a big part of the purpose of this module is also to help me learn AI-assisted development, as I'm still quite new to it, but learning quickly.

This module aims to add several agent tools over time, but this first version is also somewhat of a proof of concept. Its first feature is basic migrations system, described further in this document.

Please note that this module should be considered very much in 'beta test' at this stage. If you do use it in production (such as the migrations feature) always test locally and have backups of everything that can be restored easily. While I've not run into any cases where I had to restore anything, just the nature of the module means that you should use extra caution.

Continue reading in the GitHub README

Agent Tools in the modules directory

 

 

 

[szabesz]

9 hours ago, ryan said:

This module aims to add several agent tools over time

Can't wait! Thanks a million, as always, Ryan!

[wbmnfktr]

Just created a new test project and added the module. 

One thing I noticed immediately was that in my DDEV environment I needed to prefix the commands in order to run them in the actual container.

// non-DDEV environment
php index.php --at-eval 'echo wire()->pages->count() . " pages\n";'

// DDEV environment
ddev exec php index.php --at-eval 'echo wire()->pages->count() . " pages\n";'

 

[wbmnfktr]

Ran into this issue here in another project using the latest version from the module directory.

Quote

Warning: include_once(/var/www/html/site/modules/AgentTools/AgentToolsSitemap.php): Failed to open stream: No such file or directory in /var/www/html/site/modules/AgentTools/AgentTools.module.php on line 243

Warning: include_once(): Failed opening '/var/www/html/site/modules/AgentTools/AgentToolsSitemap.php' for inclusion (include_path='.:/usr/share/php') in /var/www/html/site/modules/AgentTools/AgentTools.module.php on line 243

The file AgentToolsSitemap.php in the module directory is actually named AgentToolsSiteMap.php (capital M) and also renamed the class.

I renamed the file and it seems to work for now.

 

Also ran (not me, the agent) into some other issue. 

Spoiler

AgentTools Issues

--at-sitemap-generate not accessible from --at-eval

Problem

The sitemap can only be generated via the dedicated CLI flag:

php index.php --at-sitemap-generate    # works

But calling it from --at-eval fails:

php index.php --at-eval 'wire("at")->sitemap()->generate();'
# ERROR: Method AgentTools::sitemap does not exist or is not callable in this context

Root cause

$at->sitemap is a property, not a method. AgentTools::get('sitemap') returns an AgentToolsSitemap instance via the helper system (line 316–319 of AgentTools.module.php). But PHP's method syntax $at->sitemap() looks for an actual sitemap() method on the AgentTools class, which doesn't exist.

The correct eval call requires chaining the property access with the method call:

// Works:
wire('at')->sitemap->generate();

// Fails — treats sitemap as a method call:
wire('at')->sitemap()->generate();

Why this matters

AI agents frequently use --at-eval for quick API calls. The sitemap is documented as a first-step orientation tool, so agents will naturally try to call it from eval. Without a clear API path, they hit the error and then see the full help output (which confusingly lists --at-sitemap-generate as a CLI flag, not an API method).

Suggested fix

Either (or both):

1. Add a sitemap() method to AgentTools that returns the helper instance — this makes wire('at')->sitemap()->generate() work naturally from eval:

   public function sitemap() {
       return $this->getHelper('sitemap');
   }
   

2. Document the correct eval syntax in agent_cli.md and AGENTS.md — use property access, not method call:

   php index.php --at-eval 'wire("at")->sitemap->generate();'
   

Option 1 is cleaner since migrations has the same property-only pattern and would benefit from the same treatment.

Environment

• AgentTools v2 (ProcessWire module)
• ProcessWire 3.0.247
• PHP 8.4, DDEV

---

pw-at.sh wrapper does not support sitemap-generate

Problem

The wrapper script (.agents/skills/processwire-agenttools/scripts/pw-at.sh) only passes through a fixed set of subcommands:

eval, eval-b64, stdin, stdin-b64, cli, migrations-apply, migrations-list, migrations-test

Any other command exits with the usage message. This means sitemap-generate cannot be invoked through the wrapper:

bash .agents/skills/processwire-agenttools/scripts/pw-at.sh sitemap-generate
# prints usage, exits 1

Agents must fall back to calling ddev exec php index.php --at-sitemap-generate directly, which breaks the "always use the wrapper" convention documented in AGENTS.md.

Suggested fix

Add sitemap-generate (and any future helper CLI actions) to the wrapper's case statement. One approach:

# In the argument validation case:
sitemap-generate|skills-install)
  [[ $# -eq 0 ]] || { echo "$mode does not accept positional arguments" >&2; exit 1; }
  ;;

# In the execution case:
sitemap-generate)
  run_php "--at-sitemap-generate"
  ;;
skills-install)
  run_php "--at-skills-install"
  ;;

Or make the wrapper generic: pass any unrecognized subcommand through as --at-<subcommand> to let AgentTools handle validation server-side.