Skip to main content
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

If you already built the bundle, install it directly:
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:
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.