WP Coding Agents

Composable coding agents for WordPress-powered workspaces.

wp-coding-agents turns a WordPress install into the home base for an AI coding agent. WordPress provides the durable operating layer, Data Machine composes the agent's memory and instructions, a coding runtime executes work, and optional bridges or orchestrators connect the agent to humans and lab environments.

The goal is a focused agent context: each installed component contributes the guidance it owns, and unavailable components stay out of the prompt.

Who It Is For

Use wp-coding-agents when you want:

• A personal or team coding agent with persistent identity, memory, and site-aware tools.
• A local development agent attached to an existing WordPress Studio, MAMP, or manual install.
• An always-on VPS agent that can respond through chat and run scheduled work.
• A generic integration layer that can compose multiple runtimes, bridges, and orchestration tools without hardcoding every workflow into one prompt.

It is not a single bundled agent product. It is the wiring layer that installs and aligns the pieces of a WordPress-native coding-agent stack.

How It Works

Human
  │
  ├─ terminal
  ├─ Discord / chat bridge
  └─ automation / dispatch
        │
        ▼
Coding runtime
  ├─ OpenCode
  └─ Claude Code
        │
        ▼
WordPress + Data Machine
  ├─ agent identity and memory
  ├─ composed AGENTS.md guidance
  ├─ abilities exposed through WordPress
  ├─ flows, jobs, and scheduled work
  └─ optional developer/orchestration extensions

Data Machine is the always-present composition layer. It owns the persistent agent files and generated guidance surface. wp-coding-agents installs the selected runtime and optional integrations, then registers only the guidance those integrations actually provide.

The Prompt Model

The agent should know only what it can use.

• Data Machine is always present and composes AGENTS.md, SOUL.md, MEMORY.md, USER.md, and shared site guidance.
• Coding runtimes add only their runtime-specific configuration, such as OpenCode instructions or Claude Code @ includes.
• Chat bridges describe the human communication surface when that bridge is selected.
• Developer orchestration layers add guidance only when installed and verified.
• Unavailable tools do not get stub instructions, fallback recipes, or negative constraints.

For example, a Kimaki install should know Kimaki is the Discord surface. It should not learn generic Kimaki worktree, tunnel, or session-fanout recipes when those responsibilities belong to other installed components. Likewise, Homeboy guidance appears only when Homeboy is available, and workspace/worktree guidance comes from the Data Machine Code layer.

What It Enables

Local Agent

Run an agent from an existing local WordPress site and keep its context grounded in that site.

EXISTING_WP=~/Studio/my-site ./setup.sh --local
cd ~/Studio/my-site && opencode

Chat-Connected Agent

Connect the coding runtime to a human chat surface for planning, status, file uploads, and review loops.

EXISTING_WP=~/Studio/my-site ./setup.sh --local --chat kimaki
cd ~/Studio/my-site && kimaki

Always-On VPS Agent

Install WordPress, Data Machine, the runtime, and a chat bridge on a dedicated server.

SITE_DOMAIN=example.com ./setup.sh

Repo-Aware Developer Workflows

Use Data Machine Code workspace management and optional orchestration tools to keep repository work isolated, reviewable, and tied back to the WordPress agent context.

EXISTING_WP=~/Studio/my-site ./setup.sh --local --with-homeboy

When an optional orchestrator is available, its own presence-gated AGENTS section explains the supported workflow. When it is absent, the prompt does not mention its commands.

Components

Component	Role	Availability
WordPress	Site runtime, plugin host, WP-CLI surface	Existing local install or installed on VPS
Data Machine	Agent identity, memory, composed guidance, abilities, flows, jobs	Always installed
OpenCode	Coding runtime	Selected or auto-detected
Claude Code	Coding runtime	Selected or auto-detected
Data Machine Code	Workspace, git, GitHub, and worktree integration	Installed with the Data Machine stack
Kimaki	Discord bridge for OpenCode sessions	Optional chat bridge
cc-connect	Multi-platform bridge, commonly used with Claude Code	Optional chat bridge
opencode-telegram	Telegram bridge for OpenCode	Optional chat bridge
Homeboy	Optional repo-aware task/lab orchestration layer	Enabled with --with-homeboy when available
AI Provider for Claude Code	WP AI Client provider backed by Claude Code OAuth credentials	Installed when Claude Code is selected or detected

Installation

Local

Use an existing WordPress install.

git clone https://github.com/Extra-Chill/wp-coding-agents.git
cd wp-coding-agents

EXISTING_WP=~/Studio/my-site ./setup.sh --local

Select a runtime explicitly when needed:

EXISTING_WP=~/Studio/my-site ./setup.sh --local --runtime opencode
EXISTING_WP=~/Studio/my-site ./setup.sh --local --runtime claude-code

VPS

Run setup from the server.

git clone https://github.com/Extra-Chill/wp-coding-agents.git
cd wp-coding-agents

SITE_DOMAIN=example.com ./setup.sh

For agent-assisted setup, give your local coding agent the setup entrypoint:

operator-entrypoints/wp-coding-agents-setup/setup.md

Common Setup Options

Flag	Description
--runtime <name>	Coding runtime: opencode or claude-code. Auto-detected when omitted.
--local	Local machine mode. Skips server infrastructure.
--existing	Add to an existing WordPress install.
--wp-path <path>	WordPress root path. Implies --existing.
--agent-slug <slug>	Override the Data Machine agent slug.
--chat <bridge>	Chat bridge: kimaki, cc-connect, or telegram.
--no-chat	Skip chat bridge setup.
--with-homeboy	Enable optional Homeboy project/lab integration when available.
--with-ai-gateway	Enable optional WP AI Gateway setup for OpenCode runtimes.
--ai-gateway-provider <id>	WordPress AI Client backend provider for the gateway route (default: openai).
--ai-gateway-model <id>	Backend model for the gateway route (default: gpt-4o-mini).
--ai-gateway-opencode-model <id>	OpenCode-facing gateway model ID (default: site-default).
--rotate-ai-gateway-token	Mint a replacement gateway token instead of reusing .opencode/wp-ai-gateway.env.
--multisite	Configure WordPress multisite.
--subdomain	Use subdomain multisite.
--no-skills	Skip installing bundled agent skills.
--dry-run	Print planned actions without applying them.

Run ./setup.sh --help for the complete setup surface.

Runtime And Bridge Notes

OpenCode

OpenCode uses opencode.json with Data Machine-composed instruction files. Kimaki is the default chat bridge for OpenCode when chat is enabled.

Pass --with-ai-gateway to opt OpenCode into this site's WP AI Gateway endpoint. Setup installs the gateway/provider stack, configures the backend route via WP-CLI, mints (or reuses) a gateway token, and writes an OpenAI-compatible provider.wp-ai-gateway entry so clients receive only the gateway token while upstream credentials stay in WordPress. Native OpenCode auth is untouched unless gateway mode is opted in.

EXISTING_WP=~/Studio/my-site ./setup.sh --local --runtime opencode \
  --with-ai-gateway --ai-gateway-provider openai --ai-gateway-model gpt-4o-mini

Claude Code

Claude Code uses CLAUDE.md with generated @ includes. A SessionStart hook refreshes the Data Machine memory includes for each session.

When Claude Code is selected or detected, wp-coding-agents installs the carried ai-provider-for-claude-code plugin so WordPress AI Client consumers can use the local Claude Code OAuth-backed provider when appropriate.

Kimaki

Kimaki is the Discord surface for OpenCode. Managed installs replace Kimaki's generic runtime prompt with a small bridge prompt so orchestration, workspace, tunnel, and preview guidance can come from the installed components that own those capabilities.

Kimaki-specific OpenCode plugins are synced into Kimaki's config directory and restored across package updates. The managed-plugin rig verifies that contract:

bash tests/kimaki-managed-plugin-rig.sh

cc-connect

cc-connect is the default bridge for Claude Code. It writes a project config pointing at the WordPress site root and can run under launchd or systemd depending on install mode.

Telegram

Telegram support uses opencode-telegram. Provide TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USER_ID during setup.

Data Machine Memory

Data Machine manages the agent's persistent files:

File	Scope	Purpose
SITE.md	Site	Generated WordPress context
RULES.md	Site	Shared behavioral rules
SOUL.md	Agent	Agent identity and voice
MEMORY.md	Agent	Persistent project knowledge
USER.md	User	Human profile and preferences

The selected runtime reads the composed files at session start. The agent can update memory through Data Machine instead of relying on runtime-specific memory features.

Abilities And Dispatch

Data Machine exposes tools through WordPress abilities. wp-coding-agents adds the local CLI transport that lets Data Machine send messages through installed chat bridges via the agents/dispatch-message contract.

Bridge channel registrations are conditional: only installed bridges register channels, and the generated guidance reflects only those channels.

Verification

Useful local checks:

bash tests/agents-md-guidance.sh
bash tests/homeboy-agents-md.sh
bash tests/kimaki-managed-plugin-rig.sh
node tests/effective-prompt/run.mjs --verbose

Use setup output and operator entrypoints for environment-specific verification commands. The generated summary is the source of truth for service names, paths, and bridge restart commands.

Upgrades

Installed agents receive an upgrade-wp-coding-agents skill. The skill runs upgrade.sh, preserves user state, syncs managed bridge/runtime files, and prints verification and restart commands for the detected environment.

Run ./upgrade.sh --help for upgrade flags.

Requirements

VPS

• Ubuntu/Debian-style Linux server
• Node.js 18+
• PHP 8.0+
• MySQL or MariaDB
• nginx
• WP-CLI

Local

• macOS or Linux desktop
• Existing WordPress install
• Node.js 18+
• WP-CLI or WordPress Studio's studio wp wrapper

Related Projects

• Data Machine — WordPress-native agent memory, abilities, flows, and jobs.
• Data Machine Code — Repository, workspace, git, and GitHub integration for Data Machine.
• Homeboy — Optional orchestration/lab layer for repo-aware coding workflows.
• Kimaki — Discord bridge used by OpenCode installs.

Contributing

Issues and PRs are welcome.

License

MIT — see LICENSE.

---

Built by Extra Chill.