Cavalry Codex Plugin

Connect Codex to Cavalry's native local MCP server to inspect compositions, build procedural motion graphics, and edit existing keyframe timing.

This independent community plugin forwards Cavalry's own MCP tools through a local SSE-to-stdio adapter. It also adds three structured motion tools for planning and applying stagger, retime, and loop closure edits. No cloud server or API key is needed for the local connection.

Motion actions

Use codex_motion_catalog to see the action scopes. codex_motion_plan reads the current composition and returns a plan ID; codex_motion_apply rechecks the scene before editing. A plan expires after ten minutes or one apply attempt. The actions use the selected layers in selection order unless layer IDs are supplied.

Stagger and retime preserve the keyframe values and easing. They reject timing collisions or moves outside the composition. Loop closure checks only the selected numeric Attributes; inspect the full composition for other motion and visual seams. For repeated elements and procedural systems, use Cavalry's native Duplicator and behaviour nodes.

Related MCP server: cavalry-mcp

Requirements

• macOS with Cavalry installed, open, and its native MCP server enabled.

• Node.js 20 or newer and npm.

• Python 3 and a recent Codex CLI with codex plugin add, available on PATH.

• Codex desktop for the plugin UI.

Install globally

git clone https://github.com/ebuberpg-prog/cavalry-codex-plugin.git
cd cavalry-codex-plugin
npm ci --ignore-scripts
python3 scripts/install-global.py

The installer copies the package and dependencies into ~/plugins/cavalry, adds it to the existing personal marketplace at ~/.agents/plugins/marketplace.json, and installs/enables cavalry@personal. Other marketplace entries are preserved, and a timestamped catalog backup is saved before updating it. Git history, environment files, and logs are excluded from the installed copy.

Restart Codex and open a new chat. Keep Cavalry open and enable Preferences → Enable MCP Server. The default port is 6768. Cavalry may ask whether ChatGPT or Codex can connect and run scripts for the session; allow the connection you initiated.

Try: “Use Cavalry to inspect my current composition.”

Verify and update

npm run check
npm run verify
npm run verify:motion

npm run verify performs the native handshake, discovers tools, reads the preamble, compiles a harmless script, and executes only console.log. It does not edit artwork. npm run verify:motion creates two temporary Null layers, checks all three actions and easing preservation, and removes those layers afterward. It requires an open composition. The tested native server exposed 17 tools; this plugin adds three motion tools.

For updates:

git pull --ff-only
npm ci --ignore-scripts
python3 scripts/install-global.py

Restart Codex afterward. For local development, edit this checkout, check the connection, and rerun the installer to refresh the global copy. node_modules is ignored by Git and installed from the lockfile.

Connection details

The adapter connects only to http://127.0.0.1:6768/sse by default. To use a different app port, pass CAVALRY_MCP_PORT in the MCP process environment. For a command-line verification, use CAVALRY_MCP_PORT=YOUR_PORT npm run verify.

The adapter provides the X-Cavalry-MCP-Client-Name, version, and fingerprint headers required by Cavalry. The stable fingerprint is a client identifier, not a credential. Cavalry controls session approval. Tool definitions, messages, results, and application instructions pass through without rewriting them.

The bundled skill reads read_preamble before execution and uses native documentation and script preflight checks. Normal user authorization and the application's restrictions continue to apply.

Package contents

• .codex-plugin/plugin.json: plugin identity, icon, and skill/MCP declarations.

• .mcp.json: local transport launch configuration.

• scripts/bridge.mjs: transport adapter and motion-tool routing using the pinned official MCP SDK.

• scripts/motion-runtime.mjs: scene-side planning, keyframe edits, and verification.

• scripts/motion-tools.mjs: motion tool definitions and session-scoped plans.

• scripts/install-global.py: personal marketplace installer.

• scripts/verify.mjs: non-mutating smoke check.

• scripts/verify-motion.mjs: reversible live motion check.

• skills/cavalry/SKILL.md: Cavalry workflow guidance.

The package follows OpenAI's plugin format. Plugin code, authored documentation, and the original plugin icon are MIT-licensed. See NOTICE.md for the independence notice.