Skip to content

codex-plugin-setup.md

Latest commit

 

History

History
105 lines (75 loc) · 3.93 KB

codex-plugin-setup.md

File metadata and controls

105 lines (75 loc) · 3.93 KB
Raw

Codex Plugin Setup

IBR is viable as a Codex plugin when Codex can discover the plugin root, load .codex-plugin/plugin.json, and expose compact Codex routing skills. Those skills drive the ibr CLI. The MCP server is dormant by default and is not started unless you opt in — see optional-mcp/README.md.

What Codex Loads

Codex uses:

  • .codex-plugin/plugin.json for plugin identity, marketplace metadata, and skills.
  • .codex-plugin/skills/ for the agent-facing design, validation, and native routing guidance.
  • references/ for detailed UI/UX reference files used by the compact Codex skills.

Codex does not load Claude slash-command routing from commands/, Claude hooks from hooks/, or Claude-style agent frontmatter from agents/. The larger shared skills/ directory remains the source library for Claude/source workflows; the Codex manifest intentionally points at the compact .codex-plugin/skills/ layer to keep activation costs low.

Install This Checkout Locally

Run from the repository root:

npm run build
npm run plugin:install-codex

The installer creates:

  • ~/plugins/ibr as a slim local plugin bundle generated from this checkout.
  • ~/.agents/plugins/marketplace.json with a local marketplace entry:
{
  "name": "ibr",
  "source": {
    "source": "local",
    "path": "./plugins/ibr"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Coding"
}

Restart Codex after installing so it reloads the local marketplace.

The bundle owns its CLI; it does not install an unscoped npm package or global binary. Verify the deterministic bundle-local path:

IBR_BIN="$HOME/plugins/ibr/dist/bin/ibr.js"
node "$IBR_BIN" --version

Codex skills resolve the equivalent path from their installed SKILL.md location. Do not use npx ibr: ibr is an unrelated unscoped npm package.

If ~/plugins/ibr or the marketplace entry already points somewhere else, re-run intentionally with:

npm run plugin:install-codex -- --force

Validate

Use local checks before relying on the plugin:

python3 -m json.tool .codex-plugin/plugin.json
npm run build

For a static Codex-plugin quality pass, run Plugin Eval when available:

node /path/to/plugin-eval/scripts/plugin-eval.js analyze ~/plugins/ibr --format markdown

Evaluate the generated bundle, not the source checkout. The source repo includes Claude commands, long-form skills, docs, and development artifacts that are intentionally not part of the slim Codex plugin runtime.

Expected hard requirements:

  • Manifest has interface.websiteURL, privacyPolicyURL, termsOfServiceURL, and defaultPrompt.
  • skills points to ./.codex-plugin/skills.
  • The manifest declares no mcpServers key — the MCP server is dormant by default.
  • Installed skills include design, ui-ux-guidance, validate, and native.
  • Installed references include references/web-design/.
  • If MCP is opted in via optional-mcp/codex-mcp.json, its command resolves to dist/mcp/server.js after build.

Use From Codex

Use the plugin by naming the installed plugin or one of its skills:

$ibr Plan this UI with IBR.
$ibr Scan this UI with IBR.
$ibr Validate this design intent.

The primary Codex path is skills plus the CLI:

  • Start design and implementation work with design.
  • Use ui-ux-guidance for the current IBR UI/UX rules: Calm Precision, web archetypes, target roles, imagegen gates, states, mobile, and data visualization.
  • Validate web UI with validate.
  • Validate simulator or macOS UI with native.
  • Record structured evidence after a host Computer Use action with ibr evidence:record <file|-> --json; see docs/external-action-evidence.md.
  • Use node "$IBR_BIN" scan, start, check, observe, interact, flow, native:scan, and scan:macos for live evidence.
  • Use MCP tool equivalents only after explicitly enabling optional-mcp/codex-mcp.json and restarting Codex.