Codex Support

BrainBrew supports Codex as a first-class runtime with a Codex-specific setup path. The integration uses Codex-native mechanisms where available and keeps Claude Code and opencode behavior on their stronger native paths.

What Is Included

• A dedicated Codex plugin package under plugin-codex/.
• Plugin-native prompt commands under plugin-codex/commands/.
• Plugin-native Codex agent guidance under plugin-codex/agents/.
• Curated Codex-safe BrainBrew skills under plugin-codex/skills/.
• Packaged MCP server under plugin-codex/mcp/.
• Global hook integration through ~/.codex/hooks.json.
• Global skill sync into ~/.codex/skills.
• Workflow recipe skills generated from BrainBrew templates.
• Role skills converted from template agents.
• Diagnostics through brainbrew codex status.

What Is Not Included

• Automatic chain execution as a state machine.
• Claude-only SubagentStart or SubagentStop lifecycle hooks.
• Plugin-local active skills.
• Generic Claude Code or OpenCode migration. Use OpenAI's curated migrate-to-codex skill for that.
• Claude/opencode MCP setup tools such as the shared init MCP tool.

Codex uses BrainBrew workflows as recipes and guidance. Use them to structure handoffs and quality gates, but do not expect Claude-style hook enforcement for every chain step.

Setup

Install the BrainBrew plugin from the Codex marketplace:

/plugins marketplace add brainbrewlabs/brainbrew-devkit
/plugins install brainbrew-devkit

For local development before the marketplace is published, add this repository as a local marketplace source:

/plugins marketplace add /Users/phungminh/Code/brainbrew-devkit
/plugins install brainbrew-devkit

Then enable BrainBrew's Codex runtime support:

brainbrew codex init
brainbrew codex sync-brainbrew-skills
brainbrew codex status

Your ~/.codex/config.toml should include:

hooks = true

plugin_hooks = false is acceptable. BrainBrew installs its supported hook entries globally.

Plugin-Native Assets

After plugin install, Codex can discover BrainBrew assets directly from the plugin package:

Asset	Path	Purpose
Commands	plugin-codex/commands/brainbrew-*.md	Prompt shortcuts for setup, BrainBrew-owned skill sync, diagnostics, chain-run guidance, and template bumping
Agents	plugin-codex/agents/openai.yaml, plugin-codex/agents/brainbrew-codex-*.md	Codex-facing role guidance for setup coordination and diagnostics
Skills	plugin-codex/skills/brainbrew-*	Curated setup, workflow, and MCP guidance that is safe for Codex
MCP	plugin-codex/mcp/mcp-server.cjs	Packaged MCP server for manual codex mcp add registration

These assets do not replace the global sync step. brainbrew codex sync-brainbrew-skills still projects template skills, template agents, and workflow YAML into ~/.codex/skills so Codex can trigger them reliably across projects.

BrainBrew DevKit does not perform generic Claude Code or OpenCode migration. For generic Claude Code to Codex migration, use OpenAI's curated migrate-to-codex skill. BrainBrew Codex commands only install and validate BrainBrew-owned workflow and runtime assets.

Commands

Plugin-native Codex prompt commands:

Command	Purpose
/brainbrew:init	Run brainbrew codex init
/brainbrew:sync-brainbrew-skills	Run brainbrew codex sync-brainbrew-skills
/brainbrew:status	Run brainbrew codex status and optionally MCP diagnostics
/brainbrew:chain-run develop	Follow or MCP-run a BrainBrew workflow recipe
/brainbrew:template-bump develop	Use MCP template_bump to set up a workflow template

brainbrew codex init

Creates ~/.codex if needed, checks ~/.codex/config.toml, backs up ~/.codex/hooks.json, and merges BrainBrew-owned hook entries for the Codex-supported hook events:

• SessionStart
• UserPromptSubmit
• PreToolUse
• PermissionRequest
• PostToolUse
• Stop

Existing non-BrainBrew hooks are preserved.

brainbrew codex sync-brainbrew-skills

Projects Codex-safe BrainBrew-owned skills into ~/.codex/skills. It also converts BrainBrew template agents into role skills and BrainBrew template YAML files into workflow recipe skills.

User skills are not overwritten unless they were previously generated by BrainBrew or are listed in the BrainBrew skills manifest at ~/.codex/brainbrew/skills-manifest.json.

brainbrew codex status

Reports config, hook, runner, and skill health:

• whether ~/.codex/config.toml exists
• whether hooks = true is present
• plugin_hooks status
• ~/.codex/hooks.json status
• BrainBrew hook count
• unsupported hook names
• runner path status
• installed BrainBrew skill count
• stale or missing generated skills
• project BrainBrew state status

MCP

BrainBrew's Codex-safe MCP server is packaged at:

plugin-codex/mcp/mcp-server.cjs

For the Codex beta, MCP registration is explicit instead of auto-loaded from the plugin manifest. This avoids relying on unverified plugin-root variable expansion in Codex MCP configs. Claude Code and opencode continue to use the existing shared MCP server and ${CLAUDE_PLUGIN_ROOT} entry in plugin/.mcp.json.

The Codex MCP server is intentionally separate from the shared Claude/opencode MCP server. It does not expose Claude/opencode setup tools such as init, and it does not write .claude/settings.json.

In Codex, check whether BrainBrew is already registered:

codex mcp list

If it is missing, register it manually with the installed Codex plugin package path:

codex mcp add brainbrew -- node <installed-codex-plugin-root>/mcp/mcp-server.cjs

For local development from this repository, use:

codex mcp add brainbrew -- node ./plugin-codex/mcp/mcp-server.cjs

Then verify:

codex mcp get brainbrew

Do not put secrets directly in .mcp.json. Use Codex MCP environment options for server-specific credentials when needed.

When registered, BrainBrew exposes these MCP workflow tools to Codex:

• chain_list
• chain_run
• chain_switch
• chain_validate
• template_bump
• template_list

Troubleshooting

Missing hooks = true

Add hooks = true to ~/.codex/config.toml, then restart Codex if needed.

Missing Runner

If brainbrew codex init reports a missing codex-runner.cjs, build or reinstall the package:

npm run build

Then rerun:

brainbrew codex init

Stale Hooks

Run brainbrew codex init again. It removes stale BrainBrew-owned hook entries and appends fresh entries while preserving unrelated hooks.

Unsupported Hook Names

Codex support only installs the six supported hook events listed above. Remove Claude-only events such as SubagentStart, SubagentStop, SessionEnd, Notification, PreCompact, or PostCompact from Codex hook configuration.

User Skill Conflict

If a destination skill exists in ~/.codex/skills without BrainBrew ownership metadata, BrainBrew skips it. Rename or remove the user skill, then rerun:

brainbrew codex sync-brainbrew-skills

MCP Server Missing

Run:

codex mcp list

If brainbrew is not listed, register the installed server with codex mcp add brainbrew -- node <installed-codex-plugin-root>/mcp/mcp-server.cjs.

Related

• Installation
• Chain Workflow