Automate MODX with Claude Code: Full Site Control Over SSH

MODX Revolution is powerful, but it is click-heavy. Every template tweak, every new article, every TV assignment routes through the Manager UI. If you run multiple MODX sites or publish content frequently, those clicks add up fast. An open-source Claude Code skill lets you hand all of that to Claude and drive your entire MODX site from the terminal over SSH. MIT licensed, zero server-side dependencies beyond PHP and runuser, works with any MODX 3.x install.

What the Skill Does

The skill deploys a small PHP CLI bridge to your server at <web_root>/cli/modx-cli.php. Every operation is a JSON object piped over SSH into that bridge, which dispatches into the MODX ORM and returns JSON. Claude handles the JSON construction, the SSH transport, and the response parsing. You just tell it what you want in plain language.

The bridge exposes full CRUD for every core MODX element:

Beyond the bridge, the skill ships a self-contained MODX knowledge library. Claude learns the tag syntax, naming conventions, reserved field names, and how common extras like pdoTools, MIGX, FormIt, Collections, and SeoSuite work. This means Claude can write a working MODX template or chunk in one session without you explaining what Automate MODX with Claude Code: Full Site Control Over SSH means or why needs the exclamation mark for uncached calls.

Prerequisites

Before you start, make sure you have:

• MODX Revolution 3.x (3.0 or newer) installed on the target server
• SSH key-based access to the server as a user who can runuser to the PHP user (commonly root)
• PHP 8.1+ on the server
• runuser utility (part of util-linux, standard on Debian, Ubuntu, RHEL, and most managed hosts)
• Claude Code installed on your local machine

Getting Started

The fastest path: open Claude Code in your project directory and prompt it with the GitHub repo link and your site.

"Install https://github.com/karamble/claude-skill-modx and use it to manage
my MODX site at example.com"

Claude will clone the repo, run the installer, then walk you through the configuration. It asks for your SSH hostname, the SSH user, the PHP user MODX runs as, and the web root path. Once it has those details, it writes the credentials to a local config file, deploys the bridge to your server, and runs a ping smoke test to verify the connection.

That is it. On every subsequent session in the same project directory, Claude auto-detects the site from a small .modx-site.yaml pointer file and starts working immediately. No re-authentication, no re-deployment.

For manual installation without prompting Claude, the repo ships a standalone installer:

git clone https://github.com/karamble/claude-skill-modx.git /tmp/claude-skill-modx
cd /tmp/claude-skill-modx
./install.sh

This copies the skill files into ~/.claude/skills/modx/. Nothing else on your system is touched. The bridge deployment and site configuration happen on first use.

How the Bridge Works

The bridge is a single PHP file that bootstraps MODX in API mode and listens for JSON commands on stdin. It runs on the server, never exposed to HTTP. Three layers keep it locked down:

1. A PHP_SAPI !== 'cli' guard that kills the script instantly if reached via a web request
2. An .htaccess deny-all rule in the /cli/ directory
3. File permissions set to mode 0640, owned by the PHP user

All actions execute as the configured PHP user via runuser, never as root. This ensures MODX cache files keep correct ownership and no privilege escalation occurs.

A quick connectivity test:

echo '{"action":"ping"}' | ~/.claude/skills/modx/scripts/invoke.sh

Returns something like:

{
    "ok": true,
    "bridge_version": "0.1.0",
    "modx": "3.2.0-pl",
    "site_name": "My Site",
    "php": "8.3.6",
    "user": "web44"
}

If user matches your configured PHP user and modx shows the right version, you are ready to go.

Real-World Workflows

You do not need to write JSON by hand. Claude constructs the payloads from natural language. But knowing what is possible helps you ask for the right things.

Publish a New Article

Tell Claude "Create a new article in the News section about XYZ" and it will construct something like this behind the scenes:

jq -n --rawfile content article.html '{
    action: "resource_create",
    fields: {
        pagetitle: "Your Article Title",
        alias: "your-article-title",
        parent: 2,
        template: 3,
        published: true,
        publishedon: "2026-04-10 12:00:00",
        hidemenu: true,
        show_in_tree: 0,
        content: $content
    },
    tvs: {
        articleimage: "assets/images/news/your-article.webp",
        tags: "AI"
    }
}' | ~/.claude/skills/modx/scripts/invoke.sh

Claude follows up with a cache clear and curls the live URL to verify the page renders correctly.

Update a Chunk

Chunks are the reusable HTML fragments in MODX. To push a new version from a local file:

jq -n --rawfile content header.html '{
    action: "chunk_update",
    name: "site-header",
    content: $content
}' | ~/.claude/skills/modx/scripts/invoke.sh

Claude always clears the cache after element mutations, since MODX caches compiled elements aggressively.

Assign a TV to a Template

Two actions, done in sequence:

echo '{"action":"tv_assign_template","tv":"articleimage","template":"BlogArticle1"}' \
  | ~/.claude/skills/modx/scripts/invoke.sh

echo '{"action":"cache_clear"}' | ~/.claude/skills/modx/scripts/invoke.sh

What Claude Learns

Most AI assistants choke on MODX because its template syntax is unusual. The tag grammar, the difference between (resource fields) and (snippet/chunk placeholders), the :output_filter chains, cached vs. uncached calls: these are not patterns a general-purpose LLM has seen enough to get right consistently.

The skill ships three reference files that Claude loads automatically:

• modx-tag-syntax.md: the complete grammar for snippet calls, chunk calls, resource fields, placeholders, system settings, links, output filters, and comments
• modx-naming.md: naming conventions for templates, chunks, snippets, TVs, and resource aliases, plus the list of reserved field names you must never use as TV names
• modx-extras.md: how the most common extras work (pdoTools, MIGX, FormIt, Collections, Tagger, SeoSuite, Login, and more), with usage patterns and gotchas

The result: Claude writes valid MODX templates, chunks, and snippet calls on the first try. It knows that https://singularitybyte.com/ is a system setting, that midjourney-university/sref-codes/red-wire.html generates a link to resource 123, and that needs the ! prefix when you want uncached output in a listing.

Security Model

The bridge assumes anyone with the configured SSH access has equal or greater power over the server already. It does not add privilege. It exists to give that access a clean API surface instead of a Manager UI. The four-layer defense:

1. .htaccess returns 403 for any HTTP request to the /cli/ directory
2. PHP_SAPI guard inside the bridge kills execution if somehow reached via the web
3. File mode 0640 owned by the PHP user, not world-readable
4. runuser drops to the PHP user for every action, so cache files keep correct ownership and no root-level PHP execution occurs

The full threat model is documented in the repo at docs/SECURITY.md.

Get Started

Open Claude Code, paste the repo URL, tell it which MODX site you want to manage. Five minutes from now you will have a working bridge and your first resource created from the terminal. No Manager clicks required.

Repo: github.com/karamble/claude-skill-modx