Inside the product

The site model is the contract.

AgentShell's theme has no hard-coded page templates. It has three zones, a block vocabulary and a design-token map — all of them data. The tools read and write that data; the shell renders it. Four rules make the whole thing coherent.

The path a call takes

01

Agent

Any MCP client: Claude Code, pi, a script. Newline-delimited JSON-RPC over stdio.

tools/list · tools/call
02

Daemon

A PHP CLI proxy. It adds Basic auth, applies a timeout, forwards the message.

agentshell-mcp-daemon
03

Plugin

Routes the REST endpoint, authenticates the actor, checks capabilities, audits the call.

wp-json/agentshell-mcp/v1/mcp
04

Theme

Renders the configuration: zones, slots, blocks, tokens, widgets.

agentshell_config

One storage key. The theme and both plugins read and write a single option, agentshell_config. Zones, design tokens, layout, widget registrations and the custom stylesheet live in that one object, which is why a transaction can buffer the entire site change as one atomic write.

Rule 01

Three zones, five block types.

The header and the footer are tri-slot: a left, a centre and a right slot, each holding blocks. The main zone is a vertical composition. Five block types fill both shapes.

Block typeWhat it rendersWhere it is allowed
wp_loopThe WordPress content loop — posts, pages, whatever the query returned.Any zone.
wp_coreA core WordPress component: site_title, site_tagline, site_logo, nav_menu, search_form.Any zone.
widgetAn entry from the bilateral widget registry, by id.Any zone.
json_blockRaw HTML you supply. Scripts, style tags, inline handlers and style attributes are stripped before it is stored.Any zone.
wp_widget_areaA registered classic WordPress sidebar.Any zone.

The configuration that produced this page's header, navigation and footer is a single JSON object. Nothing in it is a reference to a template file.

{
  "id": "header",
  "slots": {
    "left":   [ { "type": "json_block", "content": "<a class="as-brand"…" },
                   { "type": "wp_core", "id": "nav_menu" } ],
    "center": [],
    "right":  [ { "type": "wp_core", "id": "search_form" } ]
  }
}

Rule 02

The registry is bilateral.

Widgets come from two places at once. The theme ships stable file widgets declared in widgets/.index.json; agents register their own into the configuration. A configuration entry with the same id wins. The registry you see through the tools is always the merge — never one source alone.

File widgets

Stable, versioned, reviewed

A PHP file returning { id, name, libs, template, init_js, css }, declared in the index. Ships with the theme; an agent cannot delete it, only disable it.

Config widgets

Written at runtime

Registered with agentshell_register_widget, stored in the configuration, and removable with agentshell_remove_widget. These are the ones an agent owns.

Lifecycle

Enable, disable, remove

Disabling hides a widget while keeping its registration. Removing is asymmetric on purpose: only configuration-registered widgets can be removed.

Rule 03

Payloads arrive as data-*.

A widget's payload is never fetched. Scalars become one data-* attribute per field; structured payloads become one JSON attribute, conventionally data-agentshell-data. There is no third option, and no exception for “just this one call”.

<!-- the template: a shell, no logic -->
<div data-widget="tool-atlas"
     data-agentshell-data='{ "families": ["content","design","history"] }'></div>

<!-- the script: reads its own element, nothing else -->
window.AgentshellWidgets['tool-atlas'] = {
  init: function (el) {
    var payload = JSON.parse(el.dataset.agentshellData);
    // …
  }
};
  • No fetch() — not for the REST API, not for anything.
  • No <script type="application/json"> — wp_kses_post strips it.
  • Interactive components that need a shadow root use a custom element, prefixed mpm-.
  • Server-rendered data arrives by colocation with wp_loop, never by a request.

Rule 04

Two tracks for interactive components.

Track 1 · Interactive

Self-contained applications

A calculator, a visualiser, a simulator. No WordPress data dependency: it holds its own state and reads only its own data-* attributes. Choose this when a point-in-time snapshot of the data is acceptable.

Track 2 · Decorator

Progressive enhancement

The component enhances server-rendered content and must stay correct as that content changes between page loads. It finds its source by walking up to the zone scope and taking the nearest preceding block in that zone — never by scanning the document for arbitrary elements.

Decision rule. If the component has to stay right as the underlying content changes, it is a decorator. Otherwise it is a self-contained application. When it is ambiguous, take the less powerful track.

The filter under the tool table on the capabilities page is a Track 2 decorator: it enhances a table that WordPress rendered, in place, inside the zone it was placed in.

Next

What happens when the agent gets it wrong.

Leases, staged configuration, a durable journal, verified compensation and an audit trail — the parts of AgentShell that exist because agents make mistakes.