claude-smart 0.2.26 → 0.2.28

package/plugin/scripts/codex-hook.js

@@ -0,0 +1,386 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawn, spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const http = require("node:http");
+const os = require("node:os");
+const path = require("node:path");
+
+const HOME = os.homedir();
+const STATE_DIR = path.join(HOME, ".claude-smart");
+const REFLEXIO_DIR = path.join(HOME, ".reflexio");
+const DEFAULT_BACKEND_PORT = 8071;
+const FALLBACK_BACKEND_PORT = 8072;
+const DASHBOARD_PORT = 3001;
+
+function emitOk() {
+  process.stdout.write('{"continue":true,"suppressOutput":true}\n');
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function appendLog(name, line) {
+  ensureDir(STATE_DIR);
+  fs.appendFileSync(path.join(STATE_DIR, name), `${line}\n`);
+}
+
+function pluginRoot() {
+  for (const value of [process.env.CLAUDE_PLUGIN_ROOT, process.env.PLUGIN_ROOT]) {
+    if (value && fs.existsSync(path.join(value, "pyproject.toml"))) {
+      return path.resolve(value);
+    }
+  }
+  const fromScript = path.resolve(__dirname, "..");
+  if (fs.existsSync(path.join(fromScript, "pyproject.toml"))) return fromScript;
+  const cacheRoot = path.join(HOME, ".codex", "plugins", "cache", "reflexioai", "claude-smart");
+  try {
+    const versions = fs
+      .readdirSync(cacheRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => path.join(cacheRoot, entry.name))
+      .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+    for (const candidate of versions) {
+      if (fs.existsSync(path.join(candidate, "pyproject.toml"))) return candidate;
+    }
+  } catch {
+    // Fall through to the stable plugin-root link.
+  }
+  return path.join(REFLEXIO_DIR, "plugin-root");
+}
+
+function prependRuntimePath() {
+  const privateNode = path.join(STATE_DIR, "node", "current");
+  const parts = [
+    path.join(privateNode, "bin"),
+    privateNode,
+    path.join(HOME, ".local", "bin"),
+    path.join(HOME, ".cargo", "bin"),
+  ];
+  process.env.PATH = `${parts.join(path.delimiter)}${path.delimiter}${process.env.PATH || ""}`;
+}
+
+function commandPath(names) {
+  const pathParts = (process.env.PATH || "").split(path.delimiter).filter(Boolean);
+  for (const dir of pathParts) {
+    for (const name of names) {
+      const candidate = path.join(dir, name);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+function uvPath() {
+  return commandPath(process.platform === "win32" ? ["uv.exe", "uv"] : ["uv"]);
+}
+
+function npmPath() {
+  return commandPath(process.platform === "win32" ? ["npm.cmd", "npm.exe", "npm"] : ["npm"]);
+}
+
+function stateFile(name) {
+  return path.join(STATE_DIR, name);
+}
+
+function backendUrlFile() {
+  return stateFile("backend-url");
+}
+
+function writeBackendUrl(port) {
+  ensureDir(STATE_DIR);
+  fs.writeFileSync(backendUrlFile(), `http://localhost:${port}/\n`);
+}
+
+function codexCompatPath(root) {
+  return path.join(root, "scripts", "codex-claude-compat.py");
+}
+
+function readBackendUrl() {
+  if (process.env.REFLEXIO_URL) return process.env.REFLEXIO_URL;
+  try {
+    const value = fs.readFileSync(backendUrlFile(), "utf8").trim();
+    if (value) return value;
+  } catch {
+    // Fall through to default.
+  }
+  return `http://localhost:${DEFAULT_BACKEND_PORT}/`;
+}
+
+function healthOk(port, pathname, markerHeader) {
+  return new Promise((resolve) => {
+    const req = http.request(
+      {
+        host: "127.0.0.1",
+        port,
+        path: pathname,
+        method: "GET",
+        timeout: 1200,
+      },
+      (res) => {
+        const ok = res.statusCode && res.statusCode >= 200 && res.statusCode < 400;
+        const markerOk = markerHeader ? Boolean(res.headers[markerHeader]) : true;
+        res.resume();
+        resolve(Boolean(ok && markerOk));
+      },
+    );
+    req.on("timeout", () => req.destroy());
+    req.on("error", () => resolve(false));
+    req.end();
+  });
+}
+
+function portOccupied(port) {
+  return new Promise((resolve) => {
+    const req = http.request(
+      {
+        host: "127.0.0.1",
+        port,
+        path: "/",
+        method: "GET",
+        timeout: 900,
+      },
+      (res) => {
+        res.resume();
+        resolve(true);
+      },
+    );
+    req.on("timeout", () => req.destroy());
+    req.on("error", (err) => {
+      resolve(err && err.code !== "ECONNREFUSED");
+    });
+    req.end();
+  });
+}
+
+async function waitForHealth(port, pathname, markerHeader, attempts) {
+  for (let i = 0; i < attempts; i += 1) {
+    if (await healthOk(port, pathname, markerHeader)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+  }
+  return false;
+}
+
+function detached(command, args, options = {}) {
+  const child = spawn(command, args, {
+    cwd: options.cwd,
+    env: options.env || process.env,
+    detached: true,
+    shell: process.platform === "win32" && /\.(?:cmd|bat)$/i.test(command),
+    stdio: "ignore",
+    windowsHide: true,
+  });
+  child.unref();
+  return child.pid;
+}
+
+function readPid(file) {
+  try {
+    const value = fs.readFileSync(file, "utf8").trim();
+    return value ? Number(value) : null;
+  } catch {
+    return null;
+  }
+}
+
+function pidAlive(pid) {
+  if (!pid || Number.isNaN(pid)) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function writePid(file, pid) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, `${pid}\n`);
+}
+
+function ensurePluginRoot(root) {
+  ensureDir(REFLEXIO_DIR);
+  const link = path.join(REFLEXIO_DIR, "plugin-root");
+  try {
+    fs.rmSync(link, { recursive: true, force: true });
+  } catch {
+    // Ignore and try to recreate below.
+  }
+  try {
+    fs.symlinkSync(root, link, process.platform === "win32" ? "junction" : "dir");
+  } catch {
+    fs.writeFileSync(path.join(REFLEXIO_DIR, "plugin-root.txt"), `${root}\n`);
+  }
+}
+
+async function startBackend(root) {
+  if (process.env.CLAUDE_SMART_BACKEND_AUTOSTART === "0") {
+    emitOk();
+    return;
+  }
+  const pidFile = path.join(STATE_DIR, "backend.pid");
+  for (const port of [DEFAULT_BACKEND_PORT, FALLBACK_BACKEND_PORT]) {
+    if (pidAlive(readPid(pidFile)) && await healthOk(port, "/health")) {
+      writeBackendUrl(port);
+      emitOk();
+      return;
+    }
+    if (await healthOk(port, "/health")) {
+      writeBackendUrl(port);
+      emitOk();
+      return;
+    }
+  }
+  const uv = uvPath();
+  if (!uv) {
+    appendLog("backend.log", "[claude-smart] backend: uv not on PATH; skipping");
+    emitOk();
+    return;
+  }
+  let selectedPort = DEFAULT_BACKEND_PORT;
+  if (await portOccupied(DEFAULT_BACKEND_PORT)) {
+    appendLog("backend.log", "[claude-smart] backend: port 8071 occupied; trying 8072");
+    selectedPort = FALLBACK_BACKEND_PORT;
+  }
+  const backendUrl = `http://localhost:${selectedPort}/`;
+  const env = {
+    ...process.env,
+    BACKEND_PORT: String(selectedPort),
+    REFLEXIO_URL: backendUrl,
+    CLAUDE_SMART_USE_LOCAL_CLI: process.env.CLAUDE_SMART_USE_LOCAL_CLI || "1",
+    CLAUDE_SMART_USE_LOCAL_EMBEDDING: process.env.CLAUDE_SMART_USE_LOCAL_EMBEDDING || "1",
+    CLAUDE_SMART_HOST: "codex",
+    CLAUDE_SMART_CLI_PATH: process.env.CLAUDE_SMART_CLI_PATH || codexCompatPath(root),
+    INTERACTION_CLEANUP_THRESHOLD: process.env.INTERACTION_CLEANUP_THRESHOLD || "500",
+    INTERACTION_CLEANUP_DELETE_COUNT: process.env.INTERACTION_CLEANUP_DELETE_COUNT || "200",
+  };
+  const pid = detached(
+    uv,
+    [
+      "run",
+      "--project",
+      root,
+      "--quiet",
+      "reflexio",
+      "services",
+      "start",
+      "--only",
+      "backend",
+      "--no-reload",
+    ],
+    { cwd: root, env },
+  );
+  writePid(pidFile, pid);
+  if (await waitForHealth(selectedPort, "/health", null, 10)) {
+    writeBackendUrl(selectedPort);
+  }
+  emitOk();
+}
+
+async function startDashboard(root) {
+  if (process.env.CLAUDE_SMART_DASHBOARD_AUTOSTART === "0") {
+    emitOk();
+    return;
+  }
+  const dashboard = path.join(root, "dashboard");
+  if (!fs.existsSync(dashboard)) {
+    emitOk();
+    return;
+  }
+  const pidFile = path.join(STATE_DIR, "dashboard.pid");
+  if (
+    pidAlive(readPid(pidFile)) &&
+    await healthOk(DASHBOARD_PORT, "/api/health", "x-claude-smart-dashboard")
+  ) {
+    emitOk();
+    return;
+  }
+  const npm = npmPath();
+  if (!npm) {
+    appendLog("dashboard.log", "[claude-smart] dashboard: npm not on PATH; skipping");
+    emitOk();
+    return;
+  }
+  if (!fs.existsSync(path.join(dashboard, ".next"))) {
+    const buildPidFile = path.join(STATE_DIR, "dashboard-build.pid");
+    if (!pidAlive(readPid(buildPidFile))) {
+      const pid = detached(npm, ["run", "build"], { cwd: dashboard });
+      writePid(buildPidFile, pid);
+      appendLog("dashboard.log", "[claude-smart] dashboard: .next missing; started background build");
+    }
+    emitOk();
+    return;
+  }
+  const env = {
+    ...process.env,
+    PORT: String(DASHBOARD_PORT),
+    REFLEXIO_URL: readBackendUrl(),
+    CLAUDE_SMART_DASHBOARD_WORKSPACE: process.cwd(),
+  };
+  const pid = detached(npm, ["run", "start"], { cwd: dashboard, env });
+  writePid(pidFile, pid);
+  await waitForHealth(DASHBOARD_PORT, "/api/health", "x-claude-smart-dashboard", 5);
+  emitOk();
+}
+
+function runHook(root, event) {
+  const uv = uvPath();
+  if (!uv) {
+    appendLog("backend.log", "[claude-smart] hook: uv not on PATH; skipping");
+    emitOk();
+    return 0;
+  }
+  const input = fs.readFileSync(0);
+  const result = spawnSync(
+    uv,
+    ["run", "--project", root, "--quiet", "python", "-m", "claude_smart.hook", "codex", event],
+    {
+      cwd: root,
+      env: {
+        ...process.env,
+        REFLEXIO_URL: readBackendUrl(),
+        CLAUDE_SMART_HOST: "codex",
+        CLAUDE_SMART_CLI_PATH: process.env.CLAUDE_SMART_CLI_PATH || codexCompatPath(root),
+      },
+      input,
+      stdio: ["pipe", "inherit", "inherit"],
+      windowsHide: true,
+    },
+  );
+  return typeof result.status === "number" ? result.status : 1;
+}
+
+async function main() {
+  prependRuntimePath();
+  const root = pluginRoot();
+  process.env.PLUGIN_ROOT = root;
+  process.env.CLAUDE_PLUGIN_ROOT = root;
+  const action = process.argv[2] || "hook";
+  if (action === "ensure-root") {
+    ensurePluginRoot(root);
+    emitOk();
+    return 0;
+  }
+  if (action === "backend") {
+    await startBackend(root);
+    return 0;
+  }
+  if (action === "dashboard") {
+    await startDashboard(root);
+    return 0;
+  }
+  if (action === "hook") {
+    return runHook(root, process.argv[3] || "session-start");
+  }
+  emitOk();
+  return 0;
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    appendLog("backend.log", `[claude-smart] codex hook failed: ${err && err.stack ? err.stack : err}`);
+    emitOk();
+  });

package/plugin/scripts/ensure-plugin-root.sh

@@ -51,7 +51,8 @@ if [ "$FOLLOW" = "1" ]; then
 fi
 
 # Cache-tracking: if the link currently resolves to a path under the
-# managed plugin cache (~/.claude/plugins/cache/), always retarget it to
+# managed plugin cache (~/.claude/plugins/cache/ or ~/.codex/plugins/cache/),
+# always retarget it to
 # $TARGET. Plugin updates leave old version directories behind, so a
 # valid pyproject.toml at the stale target is not proof the link is
 # fresh. Links pointing outside the cache (e.g., a user's local-dev
@@ -60,7 +61,7 @@ if [ -L "$LINK" ]; then
     # Literal target string, not realpath: we compare against what was written by ln -s.
     CURRENT="$(readlink "$LINK" 2>/dev/null || true)"
     case "$CURRENT" in
-        "$HOME/.claude/plugins/cache/"*)
+        "$HOME/.claude/plugins/cache/"*|"$HOME/.codex/plugins/cache/"*)
             CURRENT_NORM="${CURRENT%/}"
             TARGET_NORM="${TARGET%/}"
             if [ "$CURRENT_NORM" != "$TARGET_NORM" ]; then

package/plugin/scripts/smart-install.sh

@@ -311,7 +311,6 @@ if ! grep -q '^CLAUDE_SMART_USE_LOCAL_EMBEDDING=' "$REFLEXIO_ENV"; then
   printf '# Use the in-process ONNX embedder (chromadb) — no API key for semantic search\nCLAUDE_SMART_USE_LOCAL_EMBEDDING=1\n' >> "$REFLEXIO_ENV"
   echo "[claude-smart] appended CLAUDE_SMART_USE_LOCAL_EMBEDDING=1 to $REFLEXIO_ENV" >&2
 fi
-
 # Migrate stale REFLEXIO_URL from reflexio's library default (8081) to the
 # plugin backend port (8071). Matches the quoted and unquoted forms but
 # requires paired quotes, so malformed or deliberately different values

package/plugin/src/claude_smart/cli.py

@@ -76,6 +76,8 @@ _CODEX_REQUIRED_FILES = (
     Path(".agents/plugins/marketplace.json"),
     Path("plugin/.codex-plugin/plugin.json"),
     Path("plugin/hooks/codex-hooks.json"),
+    Path("plugin/scripts/codex-claude-compat.py"),
+    Path("plugin/scripts/codex-hook.js"),
     Path("plugin/scripts/_codex_env.sh"),
 )
 _COPYTREE_IGNORE = shutil.ignore_patterns(
@@ -110,7 +112,10 @@ def _seed_reflexio_env() -> list[str]:
     _REFLEXIO_ENV_PATH.parent.mkdir(parents=True, exist_ok=True)
     _REFLEXIO_ENV_PATH.touch(exist_ok=True)
     existing = _REFLEXIO_ENV_PATH.read_text()
-    flags = ("CLAUDE_SMART_USE_LOCAL_CLI", "CLAUDE_SMART_USE_LOCAL_EMBEDDING")
+    flags = (
+        "CLAUDE_SMART_USE_LOCAL_CLI",
+        "CLAUDE_SMART_USE_LOCAL_EMBEDDING",
+    )
     missing = [f for f in flags if f"{f}=" not in existing]
     if not missing:
         return []

package/plugin/src/claude_smart/events/stop.py

@@ -8,7 +8,7 @@ import time
 from pathlib import Path
 from typing import Any
 
-from claude_smart import cs_cite, ids, publish, runtime, state
+from claude_smart import cs_cite, ids, internal_call, publish, runtime, state
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -112,6 +112,16 @@ def _scan_transcript_for_assistant_text(entries: list[dict[str, Any]]) -> str:
     return "\n\n".join(parts)
 
 
+def _scan_transcript_for_user_text(entries: list[dict[str, Any]]) -> str:
+    """Return the user text that opened the current transcript turn."""
+    for entry in reversed(entries):
+        if not _is_user_turn_boundary(entry):
+            continue
+        message = entry.get("message") or {}
+        return "\n\n".join(_extract_text_blocks(message.get("content")))
+    return ""
+
+
 def _is_user_turn_boundary(entry: dict[str, Any]) -> bool:
     """True if ``entry`` is the user message that opened the current turn.
 
@@ -350,6 +360,11 @@ def handle(payload: dict[str, Any]) -> None:
         if path.is_file():
             entries = _load_transcript_with_retry(path)
 
+    if runtime.is_codex():
+        prompt = payload.get("prompt") or _scan_transcript_for_user_text(entries)
+        if internal_call.is_codex_internal_prompt(prompt):
+            return
+
     last_assistant_message = payload.get("last_assistant_message")
     assistant_text = (
         last_assistant_message

package/plugin/src/claude_smart/internal_call.py

@@ -29,6 +29,9 @@ Detection signals, OR'd:
   - ``payload.cwd`` resolves inside the reflexio submodule. Catches
     direct interactive ``claude`` runs from inside reflexio (manual
     debugging) that would otherwise pollute the corpus.
+  - Known Codex-internal prompt templates (title generation and home-screen
+    suggestions). These are model calls made by Codex itself, not user
+    coding turns, and must never be reflected into claude-smart memory.
 """
 
 from __future__ import annotations
@@ -41,6 +44,19 @@ from claude_smart import runtime
 
 _ENTRYPOINT_VAR = "CLAUDE_CODE_ENTRYPOINT"
 _INTERACTIVE_ENTRYPOINT = "cli"
+_CODEX_TITLE_PROMPT_PREFIX = (
+    "You are a helpful assistant. You will be presented with a user prompt, "
+    "and your job is to provide a short title for a task"
+)
+_CODEX_SUGGESTIONS_PROMPT_PREFIX = "# Overview\n\nGenerate 0 to 3 "
+_CODEX_SUGGESTIONS_PROMPT_MARKER = (
+    "hyperpersonalized suggestions for what this user can do with Codex "
+    "in this local project:"
+)
+_CODEX_SUGGESTIONS_APPS_MARKER = (
+    "Get an understanding of the user's intent and goals by deeply viewing "
+    "their connected apps."
+)
 
 # Reflexio submodule lives at <repo>/reflexio when this package runs from
 # a dev checkout (<repo>/plugin/src/claude_smart/internal_call.py); anchor
@@ -75,6 +91,8 @@ def is_internal_invocation(payload: dict[str, Any]) -> bool:
     entrypoint = os.environ.get(_ENTRYPOINT_VAR)
     if entrypoint and entrypoint != _INTERACTIVE_ENTRYPOINT:
         return True
+    if runtime.is_codex() and is_codex_internal_prompt(payload.get("prompt")):
+        return True
     cwd = payload.get("cwd")
     if not isinstance(cwd, str) or not cwd:
         return False
@@ -87,3 +105,15 @@ def is_internal_invocation(payload: dict[str, Any]) -> bool:
     except ValueError:
         return False
     return True
+
+
+def is_codex_internal_prompt(prompt: Any) -> bool:
+    """True for Codex's own UI/task prompts, not user-authored turns."""
+    if not isinstance(prompt, str):
+        return False
+    text = prompt.strip()
+    return text.startswith(_CODEX_TITLE_PROMPT_PREFIX) or (
+        text.startswith(_CODEX_SUGGESTIONS_PROMPT_PREFIX)
+        and _CODEX_SUGGESTIONS_PROMPT_MARKER in text
+        and _CODEX_SUGGESTIONS_APPS_MARKER in text
+    )

package/plugin/src/claude_smart/optimizer_assistant.py

@@ -2,22 +2,24 @@
 
 Reflexio's ``LocalScriptAssistant`` sends one JSON payload on stdin and expects
 one JSON object on stdout. This module bridges that protocol to a guarded
-``claude -p`` subprocess so candidate playbooks can be evaluated against Claude
-Code without re-entering claude-smart/reflexio hooks.
+local CLI subprocess so candidate playbooks can be evaluated against the active
+host without re-entering claude-smart/reflexio hooks.
 """
 
 from __future__ import annotations
 
 import json
 import os
+from pathlib import Path
 import shutil
 import subprocess
 import sys
+import tempfile
 from typing import Any
 
 from claude_smart import internal_call, runtime
 
-_CLAUDE_TIMEOUT_SECONDS = 300
+_CLI_TIMEOUT_SECONDS = 300
 _READ_ONLY_TOOLS = "Read,Grep,Glob,LS"
 _MUTATING_TOOLS = "Bash,Edit,Write,MultiEdit,NotebookEdit"
 
@@ -33,7 +35,7 @@ def main() -> int:
         messages = _validated_list(payload, "messages")
         playbooks = _validated_list(payload, "playbooks")
         prompt, system_prompt = _build_prompt(messages, playbooks)
-        content = _run_claude(prompt=prompt, system_prompt=system_prompt)
+        content = _run_local_cli(prompt=prompt, system_prompt=system_prompt)
     except Exception as exc:  # noqa: BLE001 - script errors become LocalScript failures.
         sys.stderr.write(f"{type(exc).__name__}: {exc}\n")
         return 1
@@ -134,6 +136,12 @@ def _render_transcript(messages: list[dict[str, str]]) -> str:
     )
 
 
+def _run_local_cli(*, prompt: str, system_prompt: str) -> str:
+    if runtime.is_codex():
+        return _run_codex(prompt=prompt, system_prompt=system_prompt)
+    return _run_claude(prompt=prompt, system_prompt=system_prompt)
+
+
 def _run_claude(*, prompt: str, system_prompt: str) -> str:
     cli_path = shutil.which("claude") or "claude"
     # This is an evaluation rollout, not a real user session: allow local
@@ -167,13 +175,13 @@ def _run_claude(*, prompt: str, system_prompt: str) -> str:
             input=prompt,
             capture_output=True,
             text=True,
-            timeout=_CLAUDE_TIMEOUT_SECONDS,
+            timeout=_CLI_TIMEOUT_SECONDS,
             check=False,
             env=env,
         )
     except subprocess.TimeoutExpired as exc:
         raise OptimizerAssistantError(
-            f"claude CLI timed out after {_CLAUDE_TIMEOUT_SECONDS}s"
+            f"claude CLI timed out after {_CLI_TIMEOUT_SECONDS}s"
         ) from exc
     except FileNotFoundError as exc:
         raise OptimizerAssistantError("claude CLI not found on PATH") from exc
@@ -199,5 +207,77 @@ def _run_claude(*, prompt: str, system_prompt: str) -> str:
     return content
 
 
+def _run_codex(*, prompt: str, system_prompt: str) -> str:
+    cli_path = shutil.which("codex") or "codex"
+    output_path = _temporary_output_path()
+    cmd = [
+        cli_path,
+        "exec",
+        "--sandbox",
+        "read-only",
+        "--skip-git-repo-check",
+        "--ephemeral",
+        "--ignore-rules",
+        "--output-last-message",
+        str(output_path),
+        "-",
+    ]
+
+    env = os.environ.copy()
+    env[runtime.HOST_ENV] = runtime.HOST_CODEX
+    env[runtime.INTERNAL_ENV] = "1"
+    env[internal_call._ENTRYPOINT_VAR] = "optimizer"  # noqa: SLF001
+
+    try:
+        proc = subprocess.run(  # noqa: S603 - command is fixed plus resolved executable.
+            cmd,
+            input=_codex_prompt(prompt=prompt, system_prompt=system_prompt),
+            capture_output=True,
+            text=True,
+            timeout=_CLI_TIMEOUT_SECONDS,
+            check=False,
+            env=env,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise OptimizerAssistantError(
+            f"codex CLI timed out after {_CLI_TIMEOUT_SECONDS}s"
+        ) from exc
+    except FileNotFoundError as exc:
+        raise OptimizerAssistantError("codex CLI not found on PATH") from exc
+
+    try:
+        content = output_path.read_text(encoding="utf-8").strip()
+    except OSError as exc:
+        raise OptimizerAssistantError("codex CLI did not write output") from exc
+    finally:
+        try:
+            output_path.unlink()
+        except OSError:
+            pass
+
+    if proc.returncode != 0:
+        stderr = proc.stderr.strip()
+        raise OptimizerAssistantError(
+            f"codex CLI exited {proc.returncode}: {stderr[:500]}"
+        )
+    if not content:
+        raise OptimizerAssistantError("codex CLI returned empty output")
+    return content
+
+
+def _temporary_output_path() -> Path:
+    handle = tempfile.NamedTemporaryFile(prefix="claude-smart-codex-", delete=False)
+    try:
+        return Path(handle.name)
+    finally:
+        handle.close()
+
+
+def _codex_prompt(*, prompt: str, system_prompt: str) -> str:
+    if not system_prompt:
+        return prompt
+    return f"{system_prompt}\n\n## Task\n{prompt}"
+
+
 if __name__ == "__main__":
     raise SystemExit(main())