> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pluxx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

Use Pluxx in Codex when you want deterministic CLI-first packaging, native Codex plugin metadata, and strict review passes.

## What Codex Consumes

Pluxx builds the Codex target into `dist/codex/`. Codex consumes:

* `.codex-plugin/plugin.json`
* `skills/`
* `.mcp.json`
* `hooks/hooks.json` when the source plugin defines hooks or runtime readiness gates
* `AGENTS.md`
* `.codex/hooks.generated.json` as a hook translation companion
* `.codex/readiness.generated.json` as readiness/debug guidance for bundled hook flows
* `.codex/permissions.generated.json` as a companion mirror, not native enforcement
* optional `.codex/config.generated.toml` as a generated starter snippet for the live-proven per-tool MCP approval path

Codex does not currently document plugin-packaged slash commands as a first-class surface, so the main Codex user-facing contract is the plugin manifest, skills, MCP config, bundled hooks where configured, and `AGENTS.md`.

## Build And Install

```bash theme={null}
npx @orchid-labs/pluxx build --target codex --install
```

If you already built the bundle, install it directly:

```bash theme={null}
npx @orchid-labs/pluxx install --target codex
```

Pluxx installs Codex plugins into:

* plugin directory: `~/.codex/plugins/<plugin>`
* local marketplace entry: `~/.agents/plugins/marketplace.json`

If the plugin defines local hook commands, add `--trust` or confirm the trust prompt during install.

## Companion Lifecycle

The Codex path is intentionally explicit:

1. `pluxx build --target codex` generates the bundle and companion files.
2. `pluxx install --target codex` installs the bundle, but Codex may still need `Plugins > Refresh` or a restart to pick up the active copy.
3. `pluxx codex apply --consumer <installed-bundle> --project-root <project>` merges external active-config prerequisites such as `[features].hooks = true` and generated per-tool approval stanzas.
4. `pluxx verify-install --target codex` checks the installed bundle, cache freshness, trust/config prerequisites, and companion-merge gaps.

That apply step is important because Pluxx does not pretend bundle companions are self-enforcing runtime state:

* `hooks/hooks.json` is bundled, while `.codex/hooks.generated.json` and `.codex/readiness.generated.json` stay as debug/explainability companions.
* `.codex/config.generated.toml` is a starter snippet for active config, not an auto-loaded permissions layer.
* `.codex/permissions.generated.json` remains an advisory mirror for broader permission intent.

## Agent-Driven Refinement

Build and install are deterministic. Codex only does model work when you explicitly run an agent pass:

```bash theme={null}
npx @orchid-labs/pluxx agent prepare
npx @orchid-labs/pluxx agent run review --runner codex --no-verify
```

Use Codex for:

* review passes
* taxonomy refinement
* instruction rewrites

## Codex-Specific Caveats

* In Codex, use the plugin through `@pluxx`, `skills/`, and `AGENTS.md`. Do not rely on plugin slash commands as a documented Codex surface.
* Codex supports project/user hook config and plugin-bundled hooks. Pluxx bundles translated plugin hooks at `hooks/hooks.json` and mirrors the translation in `.codex/hooks.generated.json`.
* Plugin-bundled Codex hooks still require `[features].hooks = true`, enabled plugin state, user review, project trust, and runtime support. Treat that as a prerequisite, not proof that a hook actually fired.
* `.codex/permissions.generated.json` is a generated mirror of canonical permissions rules. It helps you wire equivalent Codex policy, but Codex does not enforce that file automatically.
* Codex MCP auth output is limited to the formats the current Codex plugin schema can express: `bearer_token_env_var`, `env_http_headers`, and `http_headers`.