Installation

Prerequisites

• Node.js 18+
• Claude Code CLI installed for Claude Code plugin usage.
• Codex CLI installed for Codex plugin usage.
• For Codex hooks, ~/.codex/config.toml should include hooks = true.

Install the Plugin

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

After installation, restart your Claude Code session for the new hooks, agents, and chain config to take effect.

Verify Installation

After restarting, check that the plugin is active:

/plugins

You should see brainbrew-devkit in the list.

opencode support

brainbrew-devkit runs under opencode via the oh-my-opencode (OHO) plugin. OHO discovers Claude Code plugins from ~/.claude/plugins/ and registers their agents, skills, commands, and MCP servers inside opencode.

Prerequisite

You must install the plugin in Claude Code first (the Install the Plugin steps above). opencode does not have its own plugin marketplace — OHO only sees brainbrew-devkit after Claude Code has installed it into ~/.claude/plugins/.

Setup

1. Install OHO in your opencode config (~/.config/opencode/opencode.json):

   {
     "plugin": ["oh-my-openagent@latest"]
   }

2. Install brainbrew-devkit through Claude Code as shown above. OHO will surface its agents, skills, and MCP tools (chain_run, template_bump, etc.) inside opencode automatically.

3. Run the init MCP tool to register hooks in ~/.claude/settings.json. From inside opencode (or Claude Code), invoke the brainbrew MCP:

   mcp__plugin_brainbrew-devkit_brainbrew__init

   or in chat: "run brainbrew init". The tool writes hook entries with absolute paths to the plugin's runner.cjs, so opencode's lack of ${CLAUDE_PLUGIN_ROOT} env propagation is not a problem.

   This step is required for opencode. OHO's claude-code-hooks plugin only dispatches hooks declared in ~/.claude/settings.json — it does not dispatch hooks shipped inside plugin manifests. Without this step, chain routing (PostToolUse → next agent) will not fire under opencode even though the plugin is installed.

4. Restart opencode so the new hook entries are picked up.

TIP

Claude Code reads hooks directly from the plugin manifest, so you don't need brainbrew init for Claude Code — only for opencode.

Codex Support

brainbrew-devkit also supports Codex with plugin-native commands, agents, curated skills, global hooks, global skills, and workflow recipe guidance. Codex does not run Claude's automatic subagent lifecycle, so BrainBrew chains are projected as Codex-safe skills and recipes.

Prerequisites

• The brainbrew package/plugin is available locally.
• Codex has a config file at ~/.codex/config.toml.
• hooks = true is enabled in that config.
• plugin_hooks = false is acceptable because BrainBrew writes supported hooks to ~/.codex/hooks.json.

Setup

Install the BrainBrew plugin from the Codex marketplace:

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

Then enable BrainBrew's Codex runtime support:

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

brainbrew codex init merges BrainBrew-owned hook entries into ~/.codex/hooks.json and preserves unrelated user hooks. brainbrew codex sync-brainbrew-skills writes BrainBrew-owned workflow, role, template, and helper skills to ~/.codex/skills, because Codex active skills are global rather than plugin-local.

After plugin install, Codex can also discover BrainBrew prompt commands such as /brainbrew:init, /brainbrew:chain-run, /brainbrew:template-bump, /brainbrew:sync-brainbrew-skills, and /brainbrew:status.

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.

MCP

BrainBrew packages a dedicated Codex-safe MCP server in plugin-codex/mcp/mcp-server.cjs and keeps Claude/opencode MCP metadata in plugin/.mcp.json. The Codex server does not expose Claude/opencode setup tools such as the shared init MCP tool. For the Codex beta, register the installed Codex plugin server explicitly:

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

For local development from this repository, use ./plugin-codex/mcp/mcp-server.cjs.

See Codex Support for command details and troubleshooting.

Next Steps

• Quick Start — Set up your first workflow
• Templates — Browse available workflow templates