New blog: ProcessWire and AI

[szabesz]

17 hours ago, ryan said:

so may be better to start with site/modules/AgentTools/agents/ dir and install to "/.agents/..." (with the period, if necessary). 

This is a good workaround, I think, especially if the target directory can be configured in the module's settings.
.agent/ in the site root could be the default path. BTW, some AI agent tools support both the .agent/ location and have their own preference, like Cline suggests .cline/. I use .agent/ with Cline, and it works well. 

[szabesz]

16 hours ago, wbmnfktr said:

Another option could be using the ~/.agents/ folder but here as well, not all agents support this yet.

And when they do, they treat it as the "global context", while /.agent/ is the "project context". At least that's what Cline does, so ProcessWire should not automatically touch ~/.agents/ and should warn about such an action in the first place.

see: https://docs.cline.bot/customization/skills#skills

Quote:

"You can also create skills manually by creating the directory structure in your file system. Place skill directories in .cline/skills/ (workspace) or ~/.cline/skills/ (global) and Cline will detect them automatically."

Since Cline supports both .cline/skills/ and ~/.cline/skills/ the same is true for storing skills in .agent folders as well.

[zilli]

@ryan It seems Claude is your real co-worker now—does that mean we can expect major developments sooner? I’m thinking of things like official nginx support, additional databases, organizing template files into subdirectories, and so on.

[adrian]

Just now, zilli said:

additional databases

I actually played around and got Claude to build an DB abstraction layer for PW that would allow using Postgres etc. Seems like there is definitely potential on this front.

[ukyo]

Hi @ryan and the ProcessWire community,

Thank you for starting this amazing discussion. Like many of you, I've been deeply exploring how to make AI agents more effective within the ProcessWire ecosystem. Hearing about the new Agent Tools and the API.md initiative is incredibly exciting!

ProcessWire’s predictability and clear architecture make it exceptionally pattern-friendly for AI agents. Building on this exact philosophy, I have been developing two complementary open-source packages: processwire-console and processwire-boost.

I wanted to share my architecture and findings, as they align perfectly with the goals discussed here.

1. API.md vs. AGENTS.md (Data Documentation vs. Orchestration)

@ryan your idea of adding API.md files to Fieldtype modules is brilliant and absolutely necessary. It solves the issue of the AI not knowing the exact CRUD syntax for specific module APIs.

However, as @szabesz noted regarding directory structures (.agents/ vs global contexts), managing when the AI reads this context is equally critical. If we feed everything to the AI at once, we waste tokens and dilute the context window.

I see API.md and AGENTS.md as completely complementary:

• API.md (The Knowledge): Native, module-level API documentation focusing purely on syntax and dataset interaction.
• AGENTS.md / map.json (The Librarian & Routing): Placed in the project root, this acts as a trigger-based router. Instead of holding documentation, it lists installed modules and triggers (e.g., "Use when working with HTMX components... read site/modules/Htmx/AGENTS.md" or "Working with Repeater? read site/modules/FieldtypeRepeater/API.md").
• mcp.json: The configuration for integrating ProcessWire's context securely directly into Model Context Protocol (MCP) servers locally.

By combining ProcessWire's native API.md documents with a root-level AGENTS.md / map.json router, we can keep the AI deeply focused. It drastically reduces token usage and limits hallucinations because the AI only reads the specific API.md when it is actively working on that module's scope.

2. Giving AI "Hands": The Console & Migrations
While having readable documentation is half the battle, the other half is allowing the AI to safely interact with the system.

I see that AgentTools natively introduces a very cool migration runner (--at-migrations-apply) and a dedicated CLI file for agents. This is a massive step forward to prevent AI from executing dangerous ad-hoc scripts.

To build on this paradigm, my processwire-console package reimagines this CLI experience utilizing a full Symfony Console architecture. This gives both developers and AI agents strict, typed, and predictable commands, along with a dedicated migration architecture. Instead of editing a single agent script, the AI can seamlessly run independent commands like:

php vendor/bin/wire make:migration AddBlogFields
php vendor/bin/wire migrate:status
php vendor/bin/wire migrate

This provides a Laravel/Symfony-style schema migration system that AI agents understand natively. It allows them to scaffold entire schemas predictably without breaking the production environment.

• processwire-boost: To give the AI safe, read-only oversight, I integrated an MCP (Model Context Protocol) server over JSON-RPC. Agents can natively execute tools like pw_schema_read (to understand the exact templates/fields currently installed) or pw_query to fetch ProcessWire data securely before deciding how to proceed.

Repositories & Working Examples

If you're interested in giving these tools a spin or looking at how the AI components communicate with each other, they are open-source here:

• processwire-boost: https://github.com/trk/processwire-boost
• processwire-console: https://github.com/trk/processwire-console

For a real-world example of a module that seamlessly integrates with this AI context architecture, you can check out the Htmx module. It not only includes its own localized AGENTS.md, but it also actively extends processwire-console by injecting its own CLI commands. For example, AI agents can scaffold native UI components directly from the terminal:

php vendor/bin/wire make:htmx-ui Card

Htmx Module: https://github.com/trk/Htmx

 

@ryan your approach with API.md in the core modules is the final missing piece. When ProcessWire natively exposes its capabilities clearly through text, architectures like processwire-boost with intelligent context indexing will allow agents to seamlessly crawl, understand, and reliably act upon the CMS with unprecedented accuracy.

[zilli]

2 hours ago, adrian said:

I actually played around and got Claude to build an DB abstraction layer for PW that would allow using Postgres etc. Seems like there is definitely potential on this front.

Is a new module coming up? 🙂

[adrian]

Just now, zilli said:

Is a new module coming up? 🙂

No plans on that from me - I was just seeing if Claude could do it - I think it would be something that would require core modifications and maybe modules that plugged into the core abstraction layer for each DB.

[zilli]

@adrian noted. For me, the DB abstraction would open a lot of doors for us, special if we could use SQLite. I really want to make an app/desktop using PW and NativePHP.

[ryan]

@ukyo Thanks for your awesome work with those modules, really impressive what you are building, and it's a big help for improving the AI friendliness of ProcessWire. The AgentTools module readme is now linking to your boost project as well. 

Quote

your idea of adding API.md files to Fieldtype modules is brilliant and absolutely necessary. It solves the issue of the AI not knowing the exact CRUD syntax for specific module APIs.

Glad you like the API.md files. Admittedly it was not my idea, but I asked Claude what would be helpful and he said these API.md files, plus an abbreviated sitemap json file so that it can get a big picture overview of a PW installation at a glance. That sitemap feature was actually added to the AgentTools module today. Several API.md files have been added to the core today as well. For Fieldtypes that don't have their own directory, they are in a combined /wire/modules/Fieldtype/API.md file. We're also adding dedicated Field classes specific to each Fieldtype, which will improve field documentation but also allow for custom field API methods separate from the Fieldtype (where useful).