# 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.

**Pinned support boundary:** The projection was verified against Codex CLI `0.145.0` on 2026-08-13. Reverify the host
  marketplace and skills behavior when upgrading Codex. Codex desktop parity is not claimed.

## 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

```bash
npx maestria install codex
```

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

```bash
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

1. **Check the host status**

   ```bash
   npx maestria check codex
   ```

2. **List the installed plugin**

   ```bash
   codex plugin list --json
   ```

   Look for `maestria@maestria` with `installed: true`.

3. **Start a fresh Codex session**

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

4. **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

```bash
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:

```bash
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.