{"record":{"id":"ac1ae35d272c9b9e","repo":"ruvnet/ruflo","slug":"codex-cli-path-not-found","errorCode":null,"errorMessage":"Codex CLI path not found","messagePattern":"Codex CLI path not found","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/codex/src/mcp-config.ts","lineNumber":33,"sourceCode":"    command?: unknown;\n    args?: unknown;\n  } | null;\n  startup_timeout_sec?: unknown;\n}\n\nexport interface CodexCliInvocation {\n  command: string;\n  prefixArgs: string[];\n}\n\nexport function getCodexCliInvocation(\n  lookupOutput: string,\n  platform: NodeJS.Platform = process.platform,\n  commandShell = process.env.ComSpec || 'cmd.exe',\n): CodexCliInvocation {\n  const matches = lookupOutput.split(/\\r?\\n/).map(value => value.trim()).filter(Boolean);\n  if (matches.length === 0) {\n    throw new Error('Codex CLI path not found');\n  }\n\n  if (platform !== 'win32') {\n    return { command: matches[0]!, prefixArgs: [] };\n  }\n\n  const executable = matches.find(match => /\\.exe$/i.test(match));\n  if (executable) {\n    return { command: executable, prefixArgs: [] };\n  }\n\n  // npm installs expose extensionless and .cmd shims, neither of which can\n  // be launched reliably with execFileSync on Windows. Resolve the shim via\n  // cmd.exe without interpolating any user-controlled arguments.\n  return { command: commandShell, prefixArgs: ['/d', '/s', '/c', 'codex'] };\n}\n\nexport function getRufloMcpServerConfig(","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/codex/src/mcp-config.ts#L15-L51","documentation":"getCodexCliInvocation() takes the stdout of a PATH lookup for the codex executable (e.g. `where codex` on Windows, `which -a codex` elsewhere), splits it into lines, and discards empties. Zero remaining lines means no codex binary was found, so MCP-config generation cannot build the launcher command and throws 'Codex CLI path not found'.","triggerScenarios":"The Codex CLI is not installed; it is installed local to a project (node_modules/.bin) but the lookup ran in a shell whose PATH lacks it; npx cache miss; on Windows only a non-.exe shim exists but even that is absent from PATH.","commonSituations":"Fresh machines without `npm i -g @openai/codex`; CI runners with minimal PATH; GUI-launched apps inheriting a stripped PATH where npm's global bin dir is missing; local installs mistaken for global.","solutions":["Install globally: `npm install -g @openai/codex`, then verify with `codex --version`","Ensure the npm global bin directory (`npm bin -g` / `npm prefix -g` + bin) is on PATH, including for GUI/CI shells","If you only have a local install, run the lookup from a shell where node_modules/.bin is on PATH, or npx from the project root"],"exampleFix":"# before: lookup returns nothing\n$ where codex\nINFO: Could not find files for the given pattern(s).\n# after\nnpm install -g @openai/codex\ncodex --version  # verify\nwhere codex      # now returns a path","handlingStrategy":"validation","validationCode":"import { execSync } from 'node:child_process';\nfunction codexOnPath(platform: NodeJS.Platform): boolean {\n  const cmd = platform === 'win32' ? 'where codex' : 'command -v codex';\n  try { return execSync(cmd, { encoding: 'utf8', stdio: ['ignore','pipe','pipe'] }).trim().length > 0; }\n  catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"try { inv = getCodexCliInvocation(lookup); } catch (e) { if (/Codex CLI path not found/.test(String(e))) { await installCodexCli(); lookup = relookup(); inv = getCodexCliInvocation(lookup); } else throw e; }","preventionTips":["Verify `codex --version` in the same shell/env the tool runs in (CI and GUI apps inherit different PATHs)","Install the CLI globally and add npm's global bin dir to PATH","Re-check PATH after node/npm version-manager switches"],"tags":["cli-not-found","path","installation","nodejs"],"backgroundTag":"cli-not-found-in-path","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}