Installation & Setup

@maestria/codex is a skills-only Codex plugin projection. It does not write AGENTS.md, modify Codex configuration, register models, add MCP servers, or install hooks.

Prerequisites

Codex CLI 0.145.0 or a later version whose plugin and skills behavior you have reverified.
Node.js 22+ and npm on PATH for the Maestria CLI and npm package staging.

Install through Maestria

npx maestria install codex

The CLI downloads the published @maestria/codex package, creates a local marketplace at ~/.cache/maestria/codex-marketplace, and invokes:

codex plugin marketplace add ~/.cache/maestria/codex-marketplace
codex plugin add maestria@maestria

The actual plugin cache and enabled state belong to Codex. The staging directory contains the published package used to refresh the local marketplace.

Verify the installation

Check the host status
Terminal window
```
npx maestria check codex
```
List the installed plugin
Terminal window
```
codex plugin list --json
```
Look for maestria@maestria with installed: true.
Start a fresh Codex session

Plugin discovery is session-sensitive. Start a new session and confirm the $maestria:* skills are available.
Exercise the projection

Try $maestria:adventurer on an unfamiliar area, $maestria:builder for a focused change, and $maestria:reviewer after implementation. Confirm that the reviewer reports independently and that read-only boundaries are treated as guidance, not tool enforcement.

Update and remove

npx maestria update codex
npx maestria uninstall codex

Codex CLI does not expose a separate plugin update command in the supported surface. The Maestria CLI refreshes the staged npm package, removes maestria@maestria, and adds it again.

Exact version pinning is not supported through npx maestria update codex --version ....

Validation without installation

From the repository checkout, validate the package layout with the Codex plugin-creator validator:

python3 /path/to/plugin-creator/scripts/validate_plugin.py packages/codex

The validator path is installation-specific. The command checks the manifest and packaged layout; it does not prove that a live Codex session activates every skill.