Agent Code

Onumia Agent Code is a real WordPress plugin that exists for one reason: to give agents a single, predictable place to add custom functionality to your site. Rather than letting an agent reach into an arbitrary theme or production plugin, Onumia channels every code change through this one plugin, where it can be previewed in isolation and promoted deliberately.

Why A Dedicated Plugin

When an agent needs to extend WordPress, it has to write code somewhere. Letting it edit any file in any theme or plugin is the fast path to an unreviewable mess: changes scatter across the codebase, conflicts are hard to reason about, and there is no clean boundary between what an agent wrote and what shipped with a third-party package.

Onumia Agent Code removes that ambiguity. Everything an agent authors lives in one plugin, so reviewing a change means reviewing one well-defined surface. This is the foundation for the rest of the workflow: because the code lives in a known place, Onumia can run a sandbox copy of it behind a preview and merge an approved copy into your live repository through Git.

In practice, Agent Code is where you would expect small, site-specific server logic to go. Shortcodes, filters, actions, REST endpoints, admin utilities, helper functions, and lightweight third-party integrations all fit naturally here. It is the home for the custom WordPress behavior an agent builds on your behalf.

How Sandboxes Use Agent Code

Every sandbox carries its own editable checkout of Agent Code. When an agent writes code for a task, it edits the sandbox copy, never the live plugin directly. The live WordPress site continues to run the approved version while the sandbox preview runs the sandbox’s version, so you can see new behavior working before deciding whether it should ship.

A sandbox preview activates the sandbox copy by loading its plugin entrypoint, onumia-agent-code.php, from the sandbox’s Agent Code path. This happens only inside that sandbox’s preview. Live visitors who are not in a preview always get the live plugin.

Configuring The Live Repository

Promotion needs a destination. Onumia promotes Agent Code into a configured live Git repository, so before code can move from a sandbox to live you tell Onumia where that repository lives and which branch is canonical.

The simplest approach is two PHP constants:

define('ONUMIA_AGENT_CODE_REPOSITORY', '/absolute/path/to/onumia-agent-code');
define('ONUMIA_AGENT_CODE_LIVE_BRANCH', 'main');

If your deployment resolves these values dynamically rather than from constants, use the matching filters instead:

add_filter('onumia/agent_code/repository_path', fn (?string $path): string => '/absolute/path/to/onumia-agent-code');
add_filter('onumia/agent_code/live_branch', fn (string $branch): string => 'main');

The live branch defaults to main, and Onumia validates the branch name before using it. If you never configure a repository, Onumia still creates a sandbox Agent Code copy so agents can write and preview code, but any attempt to promote that code reports that the repository is not configured rather than failing silently.

How Promotion Works

Promoting Agent Code is a Git operation, and it is deliberately conservative. Onumia first confirms that a repository is configured and that both the live repository and the sandbox checkout are valid Git repositories. It then inspects the sandbox checkout to find which files actually changed.

You can run promotion as a dry run before committing to anything. A dry run reports the configured live branch, the sandbox branch (named onumia/<sandbox-id>), the list of changed files, and whether a commit and merge would occur. It writes nothing.

A live promotion stages the sandbox changes, commits them on the sandbox branch, checks out the live branch in the live repository, and merges the sandbox branch into it. If that merge is not clean, Onumia reports the conflicting paths instead of overwriting anything; you resolve the conflict deliberately rather than letting an agent paper over it. Unresolved or unmerged files in the sandbox checkout block promotion outright.

Promotion is gated by the promote_code capability, so only users you trust with shipping code can move Agent Code to live.

The Current Boundary

The first version of Onumia’s code workflow is scoped to Agent Code, and that scope is intentional. Editing arbitrary themes and plugins from a sandbox is not the user-facing workflow yet, because doing it safely requires additional review, compatibility, and promotion policy that Agent Code does not need. Keeping agent-written code in one plugin gives you a reviewable, promotable surface today while leaving room to widen the boundary later.