feat: add Codex as a first-class host (0.11.2)

Codex CLI reads a native .codex-plugin/plugin.json that points at a new
hooks/hooks-codex.json using the Claude-shaped hook schema (event ->
matcher groups -> { "type": "command" }).

detectHost recognizes Codex by the un-prefixed PLUGIN_ROOT it sets, since
Claude sets only CLAUDE_PLUGIN_ROOT; session state lives under CODEX_HOME
(default ~/.codex). Codex shares Claude's hookSpecificOutput contract, so
orientation injects on SessionStart and the routing audit on
UserPromptSubmit, and the commit-attribution PreToolUse guard applies. The
config omits SessionEnd, which Codex has no event for, so stale session
state is pruned on the next SessionStart instead.

Bumps every host manifest to 0.11.2 and covers the new host with unit and
end-to-end hook tests, a README install section, and a CHANGELOG entry.

Author: KodingDev

.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "meridian",
   "description": "Research-first workflows, ruthless code review, orchestrator-led reasoning, and opaque subagent isolation for the entire development lifecycle.",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "author": {
     "name": "KodingDev"
   },

.codex-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "meridian",
+  "version": "0.11.2",
+  "description": "Research-first workflows, ruthless code review, orchestrator-led reasoning, and opaque subagent isolation for the entire development lifecycle.",
+  "hooks": "./hooks/hooks-codex.json"
+}

.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "meridian",
   "description": "Research-first workflows, ruthless code review, orchestrator-led reasoning, and opaque subagent isolation for the entire development lifecycle.",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "author": {
     "name": "KodingDev"
   },

.plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "meridian",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "hooks": "./hooks/hooks-copilot.json"
 }

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to Meridian are recorded here. The format follows
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). History before
 0.11.0 lives in the git log.
 
+## [0.11.2] - 2026-07-03
+
+### Added
+
+- Codex host support, alongside the existing Claude Code, Cursor, and Copilot hosts. A
+  `.codex-plugin/plugin.json` manifest points at a new `hooks/hooks-codex.json`, and
+  `detectHost` recognizes Codex by the un-prefixed `PLUGIN_ROOT` it sets (Claude sets only
+  `CLAUDE_PLUGIN_ROOT`). Codex shares Claude's `hookSpecificOutput` context-injection
+  contract, so orientation and the periodic routing audit inject on both `SessionStart` and
+  `UserPromptSubmit`, and the commit-attribution `PreToolUse` guard applies. Session state
+  lives under `CODEX_HOME` (default `~/.codex`). The Codex config omits `SessionEnd` — Codex
+  has no such event — so stale session state is pruned on `SessionStart` instead.
+
 ## [0.11.1] - 2026-06-29
 
 ### Changed

README.md

@@ -62,6 +62,10 @@ Copilot CLI installs the same plugin via its `/plugin` commands and loads the sk
 
 Hooks ship in Copilot's own format: Copilot's command schema treats `command` as a shell string and has no `args` array, so the Claude exec-form config would run a bare `node`. Copilot is pointed at `hooks/hooks-copilot.json` via `.plugin/plugin.json` (a manifest slot Copilot reads but Claude and Cursor don't). Session orientation injects via a flat `additionalContext` on `sessionStart`; prompt submission is state-only, because Copilot's `userPromptSubmitted` hook cannot inject context (same ceiling as Cursor).
 
+### Codex
+
+Codex CLI installs the plugin from the same marketplace and reads a native `.codex-plugin/plugin.json` that points at `hooks/hooks-codex.json`. Codex uses the Claude-shaped hook schema (event → matcher groups → `{ "type": "command" }`) and shares Claude's `hookSpecificOutput` context contract — so, unlike Cursor and Copilot, orientation injects on `SessionStart` **and** the routing audit injects on `UserPromptSubmit`, and the commit-attribution `PreToolUse` guard runs. Codex is detected by the un-prefixed `PLUGIN_ROOT` it sets (Claude sets only `CLAUDE_PLUGIN_ROOT`); state lives under `CODEX_HOME` (default `~/.codex`). The config omits `SessionEnd` — Codex has no such event — so stale state is pruned on the next `SessionStart`.
+
 Hook tests: `node --test test/meridian-hooks.test.mjs`
 
 ## Credit

hooks/hooks-codex.json

@@ -0,0 +1,40 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"let r=process.env.CLAUDE_PLUGIN_ROOT||process.env.PLUGIN_ROOT;if(!r)process.exit(0);let cp=require('child_process');if(process.platform==='linux'&&/^[a-zA-Z]:/.test(r)){try{r=cp.execFileSync('wslpath',['-u',r],{encoding:'utf8'}).trim()}catch{r='/mnt/'+r[0].toLowerCase()+r.slice(2).split(String.fromCharCode(92)).join('/')}}cp.execFileSync(process.execPath,[r+'/hooks/session-start.mjs'],{stdio:'inherit'})\"",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"let r=process.env.CLAUDE_PLUGIN_ROOT||process.env.PLUGIN_ROOT;if(!r)process.exit(0);let cp=require('child_process');if(process.platform==='linux'&&/^[a-zA-Z]:/.test(r)){try{r=cp.execFileSync('wslpath',['-u',r],{encoding:'utf8'}).trim()}catch{r='/mnt/'+r[0].toLowerCase()+r.slice(2).split(String.fromCharCode(92)).join('/')}}cp.execFileSync(process.execPath,[r+'/hooks/user-prompt-submit.mjs'],{stdio:'inherit'})\"",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"let r=process.env.CLAUDE_PLUGIN_ROOT||process.env.PLUGIN_ROOT;if(!r)process.exit(0);let cp=require('child_process');if(process.platform==='linux'&&/^[a-zA-Z]:/.test(r)){try{r=cp.execFileSync('wslpath',['-u',r],{encoding:'utf8'}).trim()}catch{r='/mnt/'+r[0].toLowerCase()+r.slice(2).split(String.fromCharCode(92)).join('/')}}cp.execFileSync(process.execPath,[r+'/hooks/pre-tool-use.mjs'],{stdio:'inherit'})\"",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

hooks/lib/host.mjs

@@ -22,11 +22,14 @@ function resolveStateBase(name) {
   const claude = join(homedir(), ".claude");
   const cursor = join(homedir(), ".cursor");
   const copilot = process.env.COPILOT_HOME || join(homedir(), ".copilot");
-  // Copilot sets CLAUDE_PLUGIN_ROOT too, so its branch must precede that fallback.
+  const codex = process.env.CODEX_HOME || join(homedir(), ".codex");
+  // Copilot and Codex both set CLAUDE_PLUGIN_ROOT (as a compat alias), so their
+  // branches must precede that fallback or they'd resolve to ~/.claude.
   const candidates = [
     () => process.env.CLAUDE_CONFIG_DIR,
     () => name === "cursor" && cursor,
     () => name === "copilot" && copilot,
+    () => name === "codex" && codex,
     () => process.env.CLAUDE_PLUGIN_ROOT && claude,
     () => existsSync(claude) && claude,
     () => existsSync(cursor) && cursor,
@@ -41,9 +44,14 @@ function resolveStateBase(name) {
 /**
  * Detect the host once. Cursor sets `CURSOR_PLUGIN_ROOT` and injects context only
  * on `SessionStart` (via `additional_context`); Copilot sets `COPILOT_PLUGIN_ROOT`
- * and injects on `SessionStart` only (via flat `additionalContext`); Claude injects
- * on every event (via `hookSpecificOutput`). Copilot also sets `CLAUDE_PLUGIN_ROOT`,
- * so it must be checked before the Claude default.
+ * and injects on `SessionStart` only (via flat `additionalContext`); Codex sets the
+ * un-prefixed `PLUGIN_ROOT` and, like Claude, injects on every event via
+ * `hookSpecificOutput`; Claude injects on every event via `hookSpecificOutput`.
+ * Copilot and Codex also set `CLAUDE_PLUGIN_ROOT` (compat), so both must be checked
+ * before the Claude default. Codex ships no unique identity var, so the un-prefixed
+ * `PLUGIN_ROOT` — which Codex sets but Claude does not — is the documented
+ * discriminator; a misdetect only picks the wrong state dir, since Codex and Claude
+ * share the `hookSpecificOutput` emit shape.
  * @returns {Host}
  */
 export function detectHost() {
@@ -52,7 +60,9 @@ export function detectHost() {
     ? "cursor"
     : process.env.COPILOT_PLUGIN_ROOT
       ? "copilot"
-      : "claude";
+      : process.env.PLUGIN_ROOT
+        ? "codex"
+        : "claude";
   return {
     name,
     stateBase: resolveStateBase(name),

hooks/lib/types.mjs

@@ -14,7 +14,7 @@
  * @property {string} [hook_event_name]
  */
 
-/** @typedef {"claude" | "cursor" | "copilot"} HostName */
+/** @typedef {"claude" | "cursor" | "copilot" | "codex"} HostName */
 
 /** The hook events that can inject context. @typedef {"SessionStart" | "UserPromptSubmit"} HookEvent */
 

test/meridian-consistency.test.mjs

@@ -50,7 +50,11 @@ test("per-host plugin manifests declare the same version", () => {
   assert.match(claude, /^\d+\.\d+\.\d+$/, "Claude manifest has a semver version");
   // Compare against the Claude manifest rather than a literal, so a release bump
   // touches the manifests but never this test.
-  for (const rel of [".cursor-plugin/plugin.json", ".plugin/plugin.json"]) {
+  for (const rel of [
+    ".cursor-plugin/plugin.json",
+    ".plugin/plugin.json",
+    ".codex-plugin/plugin.json",
+  ]) {
     const version = readJSON(rel).version;
     if (version === undefined) continue; // a manifest may omit version; if present it must agree
     assert.equal(version, claude, `${rel} version matches the Claude manifest`);