odd-studio 3.2.3 → 3.3.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "odd-studio",
   "description": "Outcome-Driven Development — a planning and build harness for domain experts building serious software with AI. Installs the /odd skill, safety hooks, and project scaffolding into Claude Code.",
-  "version": "3.2.2",
+  "version": "3.3.1",
   "author": {
     "name": "ODD Studio"
   },

package/README.md

@@ -4,7 +4,7 @@
 
 A planning and build harness for domain experts who are building serious software with AI — and want to understand exactly what they're doing and why.
 
-Works with **Claude Code** and **OpenCode** (with Ollama, Qwen, DeepSeek, MiniMax, and 75+ other model providers).
+Works with **Claude Code**, **OpenCode**, and **Codex**.
 
 ---
 
@@ -38,21 +38,38 @@ npx odd-studio init my-project --agent opencode
 cd my-project
 ```
 
-### For both agents on the same machine
+### For Codex
+
+```bash
+npx odd-studio init my-project --agent codex
+cd my-project
+```
+
+In Codex, ODD Studio is installed as a project-local plugin with visible plugin commands. After restarting Codex, type `/odd`.
+Once inside `/odd`, the same starred flow works there too, including commands like `*plan`, `*build`, and `*status`. You can also invoke the direct Codex commands such as `/odd-build`.
+
+### For Claude Code and OpenCode on the same machine
 
 ```bash
 npx odd-studio init my-project --agent both
 cd my-project
 ```
 
+### For every supported agent on the same machine
+
+```bash
+npx odd-studio init my-project --agent all
+cd my-project
+```
+
 Everything is installed into your project folder. Nothing is written to your home directory or installed globally.
 
 That single command:
 
 - Detects your installed AI coding agent (or uses `--agent` to specify)
 - Scaffolds your project structure (`docs/`, `.odd/`, instruction files)
-- Installs the `/odd` skill and safety hooks into the project (`.claude/`)
-- Configures odd-flow MCP server for cross-session memory (`.mcp.json`)
+- Installs the ODD harness into the matching project-local agent surface (`.claude/`, `.opencode/`, or `plugins/odd-studio/`)
+- Configures odd-flow MCP server for cross-session memory in the matching agent config
 - Optionally installs Checkpoint security scanning (you'll be asked)
 - Initialises git with an initial commit
 
@@ -69,8 +86,9 @@ That single command:
 |-------|-------------------|---------------|
 | **Claude Code** | Project-local skills (`.claude/skills/`), hooks (`.claude/settings.local.json`), odd-flow MCP (`.mcp.json`) | Claude (Opus, Sonnet, Haiku) |
 | **OpenCode** | Project-local commands (`.opencode/commands/`), JS plugin (`.opencode/plugins/`), odd-flow MCP (`opencode.json`) | Any provider — Ollama (Qwen3-Coder, MiniMax M2.7, DeepSeek), OpenAI, Anthropic, Google, Groq, and 75+ more |
+| **Codex** | Project-local plugin (`plugins/odd-studio/`), local marketplace registration (`.agents/plugins/marketplace.json`), plugin MCP (`plugins/odd-studio/.mcp.json`) | Codex |
 
-Both agents get the same methodology, the same safety enforcement, and the same odd-flow-powered cross-session memory. The only difference is the delivery mechanism.
+All supported agents get the same methodology, the same safety enforcement, and the same odd-flow-powered cross-session memory. The only difference is the delivery mechanism.
 
 ---
 
@@ -138,6 +156,8 @@ ODD Studio installs safety gates that run automatically throughout your build. T
 
 **Claude Code:** Implemented as shell hooks registered in `.claude/settings.local.json` (project-local).
 **OpenCode:** Implemented as a JS plugin (`odd-studio-plugin.js`) in `.opencode/plugins/` (project-local).
+**Codex:** Implemented as a project-local plugin in `plugins/odd-studio/` with `hooks.json` and plugin-local skills.
+It also installs Codex plugin commands so `/odd` is directly discoverable in the composer.
 
 ---
 
@@ -150,7 +170,7 @@ When you're ready to build, ODD Studio initialises a odd-flow swarm — a team o
 - **UI agent** — implements the frontend using shadcn/ui, Tailwind CSS v4, and Framer Motion, against WCAG 2.1 AA accessibility standards
 - **QA agent** — runs your verification steps and reports failures in your language, not technical error messages
 
-odd-flow MCP is configured automatically in your project's `.mcp.json` — it provides cross-session memory for both Claude Code and OpenCode. Every agent knows the full project state, regardless of which sessions they were spawned in.
+odd-flow MCP is configured automatically in your project-local agent config — `.mcp.json` for Claude Code, `opencode.json` for OpenCode, and `plugins/odd-studio/.mcp.json` for Codex. Every agent knows the full project state, regardless of which sessions they were spawned in.
 
 ---
 
@@ -206,8 +226,8 @@ After `npx odd-studio init my-project`, your project looks like this:
 ```
 my-project/
 ├── CLAUDE.md                        ← ODD build rules (Claude Code)
-├── AGENTS.md                        ← ODD build rules (OpenCode)
-├── .mcp.json                        ← odd-flow MCP config (project-local)
+├── AGENTS.md                        ← ODD build rules (OpenCode and Codex)
+├── .mcp.json                        ← odd-flow MCP config (Claude Code)
 ├── .odd/
 │   └── state.json                   ← Project state (updated automatically)
 ├── .claude/                         ← Claude Code config (project-local)
@@ -219,6 +239,14 @@ my-project/
 │   ├── commands/                    ← /odd command files
 │   ├── plugins/odd-studio-plugin.js ← Safety gate plugin
 │   └── odd/                         ← Skill knowledge base
+├── .agents/plugins/marketplace.json ← Codex local marketplace registration
+├── plugins/odd-studio/              ← Codex project-local plugin
+│   ├── .codex-plugin/plugin.json    ← Codex plugin manifest
+│   ├── commands/odd.md              ← Codex /odd command entrypoint
+│   ├── skills/                      ← ODD Studio skills for Codex
+│   ├── hooks/odd-studio.sh          ← Safety gate hook script
+│   ├── hooks.json                   ← Codex hook registration
+│   └── .mcp.json                    ← odd-flow MCP config for Codex
 └── docs/
     ├── plan.md                      ← Master Implementation Plan
     ├── contract-map.md              ← Contracts and dependency graph
@@ -229,13 +257,13 @@ my-project/
     └── ui/                          ← UI specifications per outcome
 ```
 
-Only the config directories for your target agent are generated (`.claude/`, `.opencode/`, or both).
+Only the config directories for your target agent are generated (`.claude/`, `.opencode/`, `plugins/odd-studio/`, or a supported combination).
 
 ---
 
 ## Slash commands
 
-These are the top-level commands you can invoke in either Claude Code or OpenCode:
+These are the top-level commands you can invoke in Claude Code, OpenCode, or Codex:
 
 | Command | What it does |
 |---------|-------------|
@@ -273,10 +301,13 @@ Once inside `/odd`, you can also use these sub-commands:
 ```bash
 npx odd-studio init [name]               # Scaffold a new ODD project
 npx odd-studio init --agent opencode     # Scaffold for OpenCode (local models)
+npx odd-studio init --agent codex        # Scaffold for Codex
 npx odd-studio init --agent both         # Scaffold for both agents
+npx odd-studio init --agent all          # Scaffold for Claude Code, OpenCode, and Codex
 npx odd-studio init --skip-git           # Scaffold without git init or the initial commit
 npx odd-studio status                    # Show current planning state (run from project dir)
 npx odd-studio upgrade                   # Update skills, hooks, and odd-flow config (run from project dir)
+npx odd-studio uninstall                 # Remove ODD Studio agent assets from the project
 npx odd-studio export                    # Instructions for exporting the Session Brief
 ```
 
@@ -322,6 +353,7 @@ ODD Studio implements the methodology from **The ODD Way to Build Software with
 - One of:
   - **Claude Code** installed (`npm install -g @anthropic-ai/claude-code`)
   - **OpenCode** installed (`npm install -g opencode` or `brew install opencode`)
+  - **Codex** installed
 - odd-flow MCP is configured automatically by `npx odd-studio init`
 
 ### For local model builds (OpenCode)

package/bin/commands/init.js

@@ -10,7 +10,7 @@ export function registerInit(program, deps) {
   program
     .command('init [project-name]')
     .description('Scaffold a new ODD project and install /odd into your AI coding agent')
-    .option('--agent <type>', 'Target agent: claude-code, opencode, both, or auto (default: auto)', 'auto')
+    .option('--agent <type>', 'Target agent: claude-code, opencode, codex, both, all, or auto (default: auto)', 'auto')
     .option('--skip-skill', 'Skip installing the /odd skills/commands globally (advanced)')
     .option('--skip-hooks', 'Skip installing safety hooks/plugin (not recommended)')
     .option('--skip-mcp', 'Skip configuring the odd-flow MCP server')
@@ -23,11 +23,12 @@ export function registerInit(program, deps) {
       const { default: scaffoldProject } = await import('../../scripts/scaffold-project.js');
 
       const agent = detectAgent(options.agent);
-      const isClaude = agent === 'claude-code' || agent === 'both';
-      const isOpenCode = agent === 'opencode' || agent === 'both';
+      const isClaude = agent === 'claude-code' || agent === 'both' || agent === 'all';
+      const isOpenCode = agent === 'opencode' || agent === 'both' || agent === 'all';
+      const isCodex = agent === 'codex' || agent === 'all';
       const targetDir = projectName ? path.resolve(process.cwd(), projectName) : process.cwd();
       const resolvedName = projectName || path.basename(process.cwd());
-      const agentLabel = agent === 'both' ? 'Claude Code + OpenCode' : agent === 'opencode' ? 'OpenCode' : 'Claude Code';
+      const agentLabel = getAgentLabel(agent);
       const totalSteps = 5;
 
       console.log(chalk.bold(`  Setting up: ${chalk.cyan(resolvedName)}`) + chalk.dim(` (${agentLabel})\n`));
@@ -45,13 +46,13 @@ export function registerInit(program, deps) {
       }
 
       await installSkills({ PACKAGE_ROOT, isClaude, isOpenCode, options, print, targetDir, totalSteps });
-      await installHooks({ PACKAGE_ROOT, isClaude, isOpenCode, options, print, targetDir, totalSteps });
+      await installHooks({ PACKAGE_ROOT, isClaude, isOpenCode, isCodex, options, print, targetDir, totalSteps });
       await maybeInstallCheckpoint({ options, print, targetDir, totalSteps });
       await configureMcp({ agent, options, print, targetDir, totalSteps });
 
       print.blank();
       console.log(chalk.bold.green('  ✓ ODD Studio is ready.\n'));
-      printNextSteps({ isClaude, isOpenCode, projectName });
+      printNextSteps({ isClaude, isOpenCode, isCodex, projectName });
       console.log(chalk.dim('  ODD Studio implements Outcome-Driven Development.'));
       console.log(chalk.dim("  At every step, you'll understand why — not just what to do."));
       print.blank();
@@ -98,7 +99,7 @@ async function installSkills(context) {
 }
 
 async function installHooks(context) {
-  const { PACKAGE_ROOT, isClaude, isOpenCode, options, print, targetDir, totalSteps } = context;
+  const { PACKAGE_ROOT, isClaude, isOpenCode, isCodex, options, print, targetDir, totalSteps } = context;
 
   if (options.skipHooks) {
     print.step(3, totalSteps, 'Skipping hooks/plugin (--skip-hooks)');
@@ -109,6 +110,7 @@ async function installHooks(context) {
   const targets = [];
   if (isClaude) targets.push('hooks');
   if (isOpenCode) targets.push('plugin');
+  if (isCodex) targets.push('Codex plugin');
   print.step(3, totalSteps, `Installing safety ${targets.join(' + ')}...`);
   const spinner = ora({ text: '', indent: 4 }).start();
 
@@ -126,6 +128,12 @@ async function installHooks(context) {
         print.ok('OpenCode plugin installed → odd-studio-plugin.js');
       }));
     }
+    if (isCodex) {
+      const { default: setupCodexPlugin } = await import('../../scripts/setup-codex-plugin.js');
+      installs.push(setupCodexPlugin(PACKAGE_ROOT, targetDir).then(() => {
+        print.ok('Codex plugin installed → ' + chalk.cyan('plugins/odd-studio/'));
+      }));
+    }
     await Promise.all(installs);
     spinner.stop();
   } catch (error) {
@@ -184,7 +192,7 @@ async function configureMcp({ agent, options, print, targetDir, totalSteps }) {
     const { default: setupMcp } = await import('../../scripts/setup-mcp.js');
     const result = await setupMcp(agent, targetDir);
     spinner.stop();
-    if (result.mcpJsonUpdated || result.openCodeUpdated) {
+    if (result.mcpJsonUpdated || result.openCodeUpdated || result.codexUpdated) {
       print.ok('odd-flow MCP server configured → ' + chalk.cyan('.mcp.json'));
     } else {
       print.ok('odd-flow MCP server already configured');
@@ -195,7 +203,7 @@ async function configureMcp({ agent, options, print, targetDir, totalSteps }) {
   }
 }
 
-function printNextSteps({ isClaude, isOpenCode, projectName }) {
+function printNextSteps({ isClaude, isOpenCode, isCodex, projectName }) {
   console.log(chalk.bold('  Next steps:'));
   console.log(chalk.dim('  ─────────────────────────────────────────'));
   let stepN = 1;
@@ -208,6 +216,18 @@ function printNextSteps({ isClaude, isOpenCode, projectName }) {
     console.log(`  ${stepN++}. Restart OpenCode: ` + chalk.cyan('quit and reopen') + chalk.dim(' (activates odd-flow memory + plugin)'));
     console.log(`  ${stepN++}. Open your project: ` + chalk.cyan('opencode'));
   }
+  if (isCodex) {
+    console.log(`  ${stepN++}. Restart Codex: ` + chalk.cyan('quit and reopen') + chalk.dim(' (activates the local ODD Studio plugin)'));
+    console.log(`  ${stepN++}. Open your project in Codex`);
+  }
   console.log(`  ${stepN++}. Start your ODD session: ` + chalk.cyan('/odd'));
   console.log();
 }
+
+function getAgentLabel(agent) {
+  if (agent === 'all') return 'Claude Code + OpenCode + Codex';
+  if (agent === 'both') return 'Claude Code + OpenCode';
+  if (agent === 'opencode') return 'OpenCode';
+  if (agent === 'codex') return 'Codex';
+  return 'Claude Code';
+}

package/bin/commands/uninstall.js

@@ -2,7 +2,7 @@
 
 import path from 'path';
 import fs from 'fs-extra';
-import { OPEN_CODE_COMMAND_FILES } from '../../scripts/assets.js';
+import { CODEX_PLUGIN_NAME, OPEN_CODE_COMMAND_FILES } from '../../scripts/assets.js';
 import { removeIfEmpty } from '../shared.js';
 
 export function registerUninstall(program, deps) {
@@ -11,19 +11,21 @@ export function registerUninstall(program, deps) {
   program
     .command('uninstall')
     .description('Remove all ODD Studio hooks, skills, commands, plugin, and MCP config from this project')
-    .option('--agent <type>', 'Target agent: claude-code, opencode, both, or auto (default: auto)', 'auto')
+    .option('--agent <type>', 'Target agent: claude-code, opencode, codex, both, all, or auto (default: auto)', 'auto')
     .action(async (options) => {
       print.logo();
       const { default: detectAgent } = await import('../../scripts/detect-agent.js');
       const agent = detectAgent(options.agent);
-      const isClaude = agent === 'claude-code' || agent === 'both';
-      const isOpenCode = agent === 'opencode' || agent === 'both';
+      const isClaude = agent === 'claude-code' || agent === 'both' || agent === 'all';
+      const isOpenCode = agent === 'opencode' || agent === 'both' || agent === 'all';
+      const isCodex = agent === 'codex' || agent === 'all';
       const targetDir = process.cwd();
       const removals = [];
 
       console.log('  Removing ODD Studio from this project...\n');
       if (isClaude) await removeClaudeAssets(targetDir, removals);
       if (isOpenCode) await removeOpenCodeAssets(targetDir, removals);
+      if (isCodex) await removeCodexAssets(targetDir, removals);
       await removeMcpConfig(targetDir, removals);
 
       print.blank();
@@ -84,6 +86,22 @@ async function removeMcpConfig(targetDir, removals) {
   await removeMcpEntry(path.join(targetDir, 'opencode.json'), ['mcp', 'odd-flow'], 'odd-flow MCP server from opencode.json', removals);
 }
 
+async function removeCodexAssets(targetDir, removals) {
+  await removeOwnedPath(path.join(targetDir, 'plugins', CODEX_PLUGIN_NAME), 'Codex ODD plugin', removals);
+  const marketplacePath = path.join(targetDir, '.agents', 'plugins', 'marketplace.json');
+  if (!fs.existsSync(marketplacePath)) return;
+
+  try {
+    const marketplace = await fs.readJson(marketplacePath);
+    if (!Array.isArray(marketplace.plugins)) return;
+    const nextPlugins = marketplace.plugins.filter((plugin) => plugin.name !== CODEX_PLUGIN_NAME);
+    if (nextPlugins.length === marketplace.plugins.length) return;
+    marketplace.plugins = nextPlugins;
+    await fs.writeJson(marketplacePath, marketplace, { spaces: 2 });
+    removals.push('Codex marketplace registration');
+  } catch {}
+}
+
 async function removeMcpEntry(filePath, keyPath, label, removals) {
   if (!fs.existsSync(filePath)) return;
   try {

package/bin/commands/upgrade.js

@@ -11,13 +11,14 @@ export function registerUpgrade(program, deps) {
   program
     .command('upgrade')
     .description('Upgrade the /odd skills/commands, hooks/plugin, and odd-flow config to the latest version')
-    .option('--agent <type>', 'Target agent: claude-code, opencode, both, or auto (default: auto)', 'auto')
+    .option('--agent <type>', 'Target agent: claude-code, opencode, codex, both, all, or auto (default: auto)', 'auto')
     .action(async (options) => {
       print.logo();
       const { default: detectAgent } = await import('../../scripts/detect-agent.js');
       const agent = detectAgent(options.agent);
-      const isClaude = agent === 'claude-code' || agent === 'both';
-      const isOpenCode = agent === 'opencode' || agent === 'both';
+      const isClaude = agent === 'claude-code' || agent === 'both' || agent === 'all';
+      const isOpenCode = agent === 'opencode' || agent === 'both' || agent === 'all';
+      const isCodex = agent === 'codex' || agent === 'all';
       const targetDir = process.cwd();
       const stateFile = path.resolve(targetDir, '.odd', 'state.json');
 
@@ -30,6 +31,7 @@ export function registerUpgrade(program, deps) {
       console.log(chalk.bold('  Upgrading ODD Studio...\n'));
       if (isClaude) await upgradeClaude(PACKAGE_ROOT, targetDir);
       if (isOpenCode) await upgradeOpenCode(PACKAGE_ROOT, targetDir);
+      if (isCodex) await upgradeCodex(PACKAGE_ROOT, targetDir);
       await upgradeMcp(agent, targetDir);
       print.blank();
       print.ok('Upgrade complete.');
@@ -66,6 +68,13 @@ async function upgradeOpenCode(packageRoot, targetDir) {
   });
 }
 
+async function upgradeCodex(packageRoot, targetDir) {
+  await runSpinner('Updating Codex plugin...', 'Codex plugin updated', async () => {
+    const { default: setupCodexPlugin } = await import('../../scripts/setup-codex-plugin.js');
+    await setupCodexPlugin(packageRoot, targetDir);
+  });
+}
+
 async function upgradeMcp(agent, targetDir) {
   await runSpinner('Checking odd-flow MCP configuration...', null, async (spinner) => {
     const { default: setupMcp } = await import('../../scripts/setup-mcp.js');

package/bin/odd-studio.js

@@ -15,7 +15,7 @@ import { registerUninstall } from './commands/uninstall.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const require = createRequire(import.meta.url);
-const pkg = require('../package.json'); // v3.2.3
+const pkg = require('../package.json'); // v3.3.1
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const deps = { PACKAGE_ROOT, print };

package/codex-plugin/.codex-plugin/plugin.json

@@ -0,0 +1,39 @@
+{
+  "name": "odd-studio",
+  "version": "3.3.1",
+  "description": "Outcome-Driven Development planning and build harness for domain experts building serious software with AI.",
+  "author": {
+    "name": "ODD Studio"
+  },
+  "homepage": "https://github.com/odd-studio/odd-studio",
+  "repository": "https://github.com/odd-studio/odd-studio",
+  "license": "MIT",
+  "keywords": [
+    "odd-studio",
+    "outcome-driven-development",
+    "codex",
+    "planning",
+    "build"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks.json",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "ODD Studio",
+    "shortDescription": "Guide planning, build sequencing, and verification with Outcome-Driven Development",
+    "longDescription": "Use ODD Studio to plan around personas, outcomes, contracts, and phased delivery, then run a disciplined build and verification flow with odd-flow memory and safety gates.",
+    "developerName": "ODD Studio",
+    "category": "Coding",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/odd-studio/odd-studio",
+    "privacyPolicyURL": "https://github.com/odd-studio/odd-studio",
+    "termsOfServiceURL": "https://github.com/odd-studio/odd-studio",
+    "defaultPrompt": "Start or resume an ODD Studio planning and build session for this project",
+    "brandColor": "#111111",
+    "screenshots": []
+  }
+}

package/codex-plugin/.mcp.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "odd-flow": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "odd-flow@latest",
+        "mcp",
+        "start"
+      ],
+      "env": {}
+    }
+  }
+}

package/codex-plugin/README.md

@@ -0,0 +1,3 @@
+# ODD Studio for Codex
+
+This plugin installs the ODD Studio planning and build harness into Codex as a project-local plugin.

package/codex-plugin/hooks.json

@@ -0,0 +1,110 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh brief-gate"
+          },
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh build-gate"
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh swarm-write"
+          },
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh verify-gate"
+          },
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh confirm-gate"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh commit-gate"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh swarm-guard"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh session-save"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__odd-flow__memory_store",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh store-validate"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__odd-flow__coordination_sync",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh sync-validate"
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh code-quality"
+          },
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh brief-quality"
+          },
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh outcome-quality"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh code-quality"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "odd-studio",
-  "version": "3.2.3",
-  "description": "Outcome-Driven Development for AI coding agents — a planning and build harness for domain experts building serious software with AI. Works with Claude Code and OpenCode.",
+  "version": "3.3.1",
+  "description": "Outcome-Driven Development for AI coding agents — a planning and build harness for domain experts building serious software with AI. Works with Claude Code, OpenCode, and Codex.",
   "keywords": [
     "claude-code",
     "opencode",
+    "codex",
     "odd",
     "outcome-driven-development",
     "ai-development",
@@ -35,6 +36,7 @@
     "skill/",
     "hooks/",
     "plugins/",
+    "codex-plugin/",
     "templates/",
     ".claude-plugin/"
   ],

package/scripts/assets.js

@@ -1,6 +1,14 @@
 'use strict';
 
 export const ODD_HOOK_FILE = 'odd-studio.sh';
+export const CODEX_PLUGIN_NAME = 'odd-studio';
+export const CODEX_MARKETPLACE_ROOT = {
+  name: 'local-plugins',
+  interface: {
+    displayName: 'Local plugins',
+  },
+  plugins: [],
+};
 
 export const OPEN_CODE_COMMAND_FILES = [
   'odd.md',

package/scripts/detect-agent.js

@@ -5,20 +5,28 @@ import os from 'os';
 
 const CLAUDE_DIR = path.join(os.homedir(), '.claude');
 const OC_DIR = path.join(os.homedir(), '.config', 'opencode');
+const CODEX_DIR = path.join(os.homedir(), '.codex');
 
 /**
  * Detects which AI coding agent is installed on this machine.
  *
- * @param {string} override - 'claude-code', 'opencode', 'both', or 'auto'
- * @returns {'claude-code' | 'opencode' | 'both'}
+ * @param {string} override - 'claude-code', 'opencode', 'codex', 'both', 'all', or 'auto'
+ * @param {{ existsSync?: (path: string) => boolean }} options
+ * @returns {'claude-code' | 'opencode' | 'codex' | 'both' | 'all'}
  */
-export default function detectAgent(override = 'auto') {
+export default function detectAgent(override = 'auto', options = {}) {
   if (override !== 'auto') return override;
+  const exists = options.existsSync || fs.existsSync;
 
-  const hasClaude = fs.existsSync(CLAUDE_DIR);
-  const hasOpenCode = fs.existsSync(OC_DIR);
+  const hasClaude = exists(CLAUDE_DIR);
+  const hasOpenCode = exists(OC_DIR);
+  const hasCodex = exists(CODEX_DIR);
 
+  if (hasClaude && hasOpenCode && hasCodex) return 'all';
   if (hasClaude && hasOpenCode) return 'both';
+  if (hasClaude && hasCodex) return 'all';
+  if (hasOpenCode && hasCodex) return 'all';
+  if (hasCodex) return 'codex';
   if (hasOpenCode) return 'opencode';
   return 'claude-code';
 }

package/scripts/install-codex-commands.js

@@ -0,0 +1,56 @@
+'use strict';
+import fs from 'fs-extra';
+import path from 'path';
+import { COMMANDS } from './command-definitions.js';
+import { CODEX_PLUGIN_NAME } from './assets.js';
+
+const CODEX_ODD_ROOT = `plugins/${CODEX_PLUGIN_NAME}/skills/odd/`;
+
+export default async function installCodexCommands(pluginDest) {
+  const commandsDest = path.join(pluginDest, 'commands');
+  await fs.ensureDir(commandsDest);
+
+  for (const cmd of COMMANDS) {
+    const content = cmd.source
+      ? buildMainCommand(cmd)
+      : buildSubcommand(cmd);
+    await fs.writeFile(path.join(commandsDest, `${cmd.name}.md`), content);
+  }
+
+  return { destination: commandsDest, commandCount: COMMANDS.length };
+}
+
+function buildMainCommand(cmd) {
+  return [
+    '---',
+    `description: "${cmd.description}"`,
+    '---',
+    '',
+    '# /odd',
+    '',
+    'You are now operating as the ODD Studio coach.',
+    '',
+    'Read this file now:',
+    `- \`${CODEX_ODD_ROOT}SKILL.md\` — the full ODD Studio coach`,
+    '',
+    'Then execute the startup state check exactly as documented.',
+    '',
+  ].join('\n');
+}
+
+function buildSubcommand(cmd) {
+  return [
+    '---',
+    `description: "${cmd.description}"`,
+    '---',
+    '',
+    `# /${cmd.name}`,
+    '',
+    rewriteBody(cmd.body),
+    '',
+  ].join('\n');
+}
+
+function rewriteBody(body) {
+  return body.replace(/`\.opencode\/odd\//g, `\`${CODEX_ODD_ROOT}`);
+}

package/scripts/scaffold-project.js

@@ -16,6 +16,9 @@ export default async function scaffoldProject(targetDir, projectName, agent = 'c
   }
   const isClaude = agent === 'claude-code' || agent === 'both';
   const isOpenCode = agent === 'opencode' || agent === 'both';
+  const isCodex = agent === 'codex' || agent === 'all';
+  const wantsAgentsMd = isOpenCode || isCodex;
+  const wantsClaudeMd = isClaude || agent === 'all';
 
   await fs.ensureDir(targetDir);
 
@@ -31,9 +34,8 @@ export default async function scaffoldProject(targetDir, projectName, agent = 'c
         return !fs.existsSync(destDir) || fs.readdirSync(destDir).length === 0;
       }
       // Skip CLAUDE.md if OpenCode-only
-      if (basename === 'CLAUDE.md' && !isClaude) return false;
-      // Skip AGENTS.md if Claude-only
-      if (basename === 'AGENTS.md' && !isOpenCode) return false;
+      if (basename === 'CLAUDE.md' && !wantsClaudeMd) return false;
+      if (basename === 'AGENTS.md' && !wantsAgentsMd) return false;
       return true;
     },
   });

package/scripts/setup-codex-plugin.js

@@ -0,0 +1,117 @@
+'use strict';
+import fs from 'fs-extra';
+import path from 'path';
+import {
+  CODEX_MARKETPLACE_ROOT,
+  CODEX_PLUGIN_NAME,
+  ODD_HOOK_FILE,
+} from './assets.js';
+import installCodexCommands from './install-codex-commands.js';
+
+const PLUGIN_RELATIVE_PATH = `./plugins/${CODEX_PLUGIN_NAME}`;
+const MARKETPLACE_ENTRY = {
+  name: CODEX_PLUGIN_NAME,
+  source: {
+    source: 'local',
+    path: PLUGIN_RELATIVE_PATH,
+  },
+  policy: {
+    installation: 'AVAILABLE',
+    authentication: 'ON_INSTALL',
+  },
+  category: 'Coding',
+};
+
+export default async function setupCodexPlugin(packageRoot, targetDir) {
+  const pluginSource = path.join(packageRoot, 'codex-plugin');
+  const pluginDest = path.join(targetDir, 'plugins', CODEX_PLUGIN_NAME);
+  const skillSource = path.join(packageRoot, 'skill');
+  const hookSource = path.join(packageRoot, 'hooks', ODD_HOOK_FILE);
+
+  if (!fs.existsSync(pluginSource)) {
+    throw new Error(`Codex plugin source not found: ${pluginSource}`);
+  }
+
+  await fs.copy(pluginSource, pluginDest, { overwrite: true });
+  await installCodexSkills(skillSource, pluginDest);
+  await installCodexCommands(pluginDest);
+  await installCodexHook(hookSource, pluginDest);
+  const marketplaceUpdated = await updateMarketplace(targetDir);
+
+  return { destination: pluginDest, marketplaceUpdated };
+}
+
+async function installCodexSkills(skillSource, pluginDest) {
+  const skillsDest = path.join(pluginDest, 'skills');
+  await fs.ensureDir(skillsDest);
+
+  const oddDest = path.join(skillsDest, 'odd');
+  await fs.ensureDir(oddDest);
+
+  const entries = await fs.readdir(skillSource, { withFileTypes: true });
+  for (const entry of entries) {
+    const src = path.join(skillSource, entry.name);
+    if (entry.isDirectory() && fs.existsSync(path.join(src, 'SKILL.md'))) {
+      await fs.copy(src, path.join(skillsDest, entry.name), { overwrite: true });
+      await rewriteSkillPaths(path.join(skillsDest, entry.name, 'SKILL.md'));
+      continue;
+    }
+
+    await fs.copy(src, path.join(oddDest, entry.name), { overwrite: true });
+  }
+
+  await rewriteSkillPaths(path.join(oddDest, 'SKILL.md'));
+}
+
+async function rewriteSkillPaths(filePath) {
+  if (!fs.existsSync(filePath)) return;
+  let content = await fs.readFile(filePath, 'utf8');
+  content = content.replace(/Works with Claude Code and OpenCode\./g, 'Works with Claude Code, OpenCode, and Codex.');
+  content = content.replace(/`\.claude\/skills\/odd\//g, '`plugins/odd-studio/skills/odd/');
+  content = content.replace(/\.claude\/skills\/odd\//g, 'plugins/odd-studio/skills/odd/');
+  await fs.writeFile(filePath, content);
+}
+
+async function installCodexHook(hookSource, pluginDest) {
+  const hooksDest = path.join(pluginDest, 'hooks');
+  await fs.ensureDir(hooksDest);
+  const hookDest = path.join(hooksDest, ODD_HOOK_FILE);
+  await fs.copy(hookSource, hookDest, { overwrite: true });
+  await fs.chmod(hookDest, 0o755);
+}
+
+async function updateMarketplace(targetDir) {
+  const marketplacePath = path.join(targetDir, '.agents', 'plugins', 'marketplace.json');
+  await fs.ensureDir(path.dirname(marketplacePath));
+
+  let marketplace = CODEX_MARKETPLACE_ROOT;
+  if (fs.existsSync(marketplacePath)) {
+    try {
+      marketplace = await fs.readJson(marketplacePath);
+    } catch {
+      marketplace = CODEX_MARKETPLACE_ROOT;
+    }
+  }
+
+  if (!marketplace.name) marketplace.name = CODEX_MARKETPLACE_ROOT.name;
+  if (!marketplace.interface) marketplace.interface = CODEX_MARKETPLACE_ROOT.interface;
+  if (!marketplace.interface.displayName) {
+    marketplace.interface.displayName = CODEX_MARKETPLACE_ROOT.interface.displayName;
+  }
+  if (!Array.isArray(marketplace.plugins)) marketplace.plugins = [];
+
+  const existingIndex = marketplace.plugins.findIndex((plugin) => plugin.name === CODEX_PLUGIN_NAME);
+  if (existingIndex === -1) {
+    marketplace.plugins.push(MARKETPLACE_ENTRY);
+    await fs.writeJson(marketplacePath, marketplace, { spaces: 2 });
+    return true;
+  }
+
+  const existing = marketplace.plugins[existingIndex];
+  const changed = JSON.stringify(existing) !== JSON.stringify(MARKETPLACE_ENTRY);
+  if (changed) {
+    marketplace.plugins[existingIndex] = MARKETPLACE_ENTRY;
+    await fs.writeJson(marketplacePath, marketplace, { spaces: 2 });
+  }
+  return changed;
+}

package/scripts/setup-mcp.js

@@ -24,14 +24,14 @@ const ODD_FLOW_SERVER_ENTRY = {
  *
  * Nothing is written to ~/. Both paths are idempotent.
  *
- * @param {'claude-code' | 'opencode' | 'both'} agent - Target agent
+ * @param {'claude-code' | 'opencode' | 'codex' | 'both' | 'all'} agent - Target agent
  * @param {string} targetDir - Project directory
  */
 export default async function setupMcp(agent = 'claude-code', targetDir) {
-  const result = { mcpJsonUpdated: false, openCodeUpdated: false };
+  const result = { mcpJsonUpdated: false, openCodeUpdated: false, codexUpdated: false };
 
   // ── Claude Code: <projectDir>/.mcp.json ───────────────────────────────────
-  if (agent === 'claude-code' || agent === 'both') {
+  if (agent === 'claude-code' || agent === 'both' || agent === 'all') {
     const mcpJsonPath = path.join(targetDir, '.mcp.json');
     let mcpConfig = { mcpServers: {} };
     if (fs.existsSync(mcpJsonPath)) {
@@ -55,7 +55,7 @@ export default async function setupMcp(agent = 'claude-code', targetDir) {
   }
 
   // ── OpenCode: <projectDir>/opencode.json ──────────────────────────────────
-  if (agent === 'opencode' || agent === 'both') {
+  if (agent === 'opencode' || agent === 'both' || agent === 'all') {
     const ocConfigPath = path.join(targetDir, 'opencode.json');
 
     let ocConfig = {};
@@ -84,5 +84,28 @@ export default async function setupMcp(agent = 'claude-code', targetDir) {
     }
   }
 
+  if (agent === 'codex' || agent === 'all') {
+    const codexMcpPath = path.join(targetDir, 'plugins', 'odd-studio', '.mcp.json');
+    await fs.ensureDir(path.dirname(codexMcpPath));
+    let codexConfig = { mcpServers: {} };
+    if (fs.existsSync(codexMcpPath)) {
+      try {
+        codexConfig = await fs.readJson(codexMcpPath);
+      } catch {
+        codexConfig = { mcpServers: {} };
+      }
+    }
+    if (!codexConfig.mcpServers) codexConfig.mcpServers = {};
+
+    if (!codexConfig.mcpServers['odd-flow']) {
+      if (fs.existsSync(codexMcpPath)) {
+        await fs.copy(codexMcpPath, codexMcpPath + '.bak', { overwrite: true });
+      }
+      codexConfig.mcpServers['odd-flow'] = ODD_FLOW_SERVER_ENTRY;
+      await fs.writeJson(codexMcpPath, codexConfig, { spaces: 2 });
+      result.codexUpdated = true;
+    }
+  }
+
   return result;
 }

package/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "odd"
-version: "3.2.3"
-description: "Outcome-Driven Development planning and build coach. Use /odd to start or resume an ODD project — building personas, writing outcomes, mapping contracts, creating a Master Implementation Plan, and directing a odd-flow-powered build. Designed for domain experts who are not developers. Works with Claude Code and OpenCode."
+version: "3.3.1"
+description: "Outcome-Driven Development planning and build coach. Use /odd to start or resume an ODD project — building personas, writing outcomes, mapping contracts, creating a Master Implementation Plan, and directing a odd-flow-powered build. Designed for domain experts who are not developers. Works with Claude Code, OpenCode, and Codex."
 ---
 
 # ODD Studio — Outcome-Driven Development Coach
@@ -35,7 +35,7 @@ Display this when no existing state is found:
 
 ---
 
-Welcome to ODD Studio v3.2.3.
+Welcome to ODD Studio v3.3.1.
 
 You are about to plan and build something real — using a methodology called Outcome-Driven Development. Before we write a single line of code, we are going to get precise about three things:
 
@@ -59,7 +59,7 @@ Display this when existing state is found. Replace the bracketed values with act
 
 ---
 
-Welcome back to ODD Studio v3.2.3.
+Welcome back to ODD Studio v3.3.1.
 
 **Project:** [project.name]
 **Current Phase:** [state.currentPhase]