{"record":{"id":"ea1d47062b2f03f7","repo":"ruvnet/ruflo","slug":"loop-run-requires-a-prompt-unless-command-is-pro","errorCode":null,"errorMessage":"loop run requires a prompt unless --command is provided","messagePattern":"loop run requires a prompt unless --command is provided","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/codex/src/loop/index.ts","lineNumber":127,"sourceCode":"    '',\n    'Work autonomously for this iteration. Make concrete progress, run relevant checks, and stop before broad unrelated refactors.',\n    `If the task is fully complete, create this marker file: ${state.untilFile}`,\n    'If more work remains, leave the marker absent so the next loop iteration can continue.',\n  ].join('\\n');\n}\n\nexport async function runCodexLoop(options: LoopRunOptions = {}): Promise<LoopState> {\n  const projectPath = path.resolve(options.projectPath ?? process.cwd());\n  const name = normalizeLoopName(options.name);\n  const paths = resolveLoopPaths(projectPath, name, options.stateDir);\n  const intervalSeconds = clampInteger(options.intervalSeconds ?? 270, 0, 86_400);\n  const maxIterations = clampInteger(options.maxIterations ?? 10, 0, 100_000);\n  const timeoutMs = clampInteger(options.timeoutMs ?? 30 * 60_000, 1_000, 24 * 60 * 60_000);\n  const untilFile = path.resolve(projectPath, options.untilFile ?? paths.completePath);\n  const mode: LoopState['mode'] = options.command ? 'command' : 'codex';\n\n  if (mode === 'codex' && !options.prompt?.trim()) {\n    throw new Error('loop run requires a prompt unless --command is provided');\n  }\n\n  await fs.ensureDir(paths.stateDir);\n  await fs.remove(paths.stopPath);\n\n  const startedAt = new Date().toISOString();\n  const state: LoopState = {\n    name,\n    projectPath,\n    mode,\n    status: 'running',\n    iteration: 0,\n    maxIterations,\n    intervalSeconds,\n    startedAt,\n    updatedAt: startedAt,\n    untilFile,\n  };","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/codex/src/loop/index.ts#L109-L145","documentation":"runCodexLoop() supports two modes: 'codex' (runs a Codex prompt each iteration) and 'command' (runs a shell command). In codex mode the prompt is the payload, so a missing or whitespace-only options.prompt with no options.command aborts immediately with this usage error before any state directory is created.","triggerScenarios":"Calling runCodexLoop({}) or runCodexLoop({ name: 'x' }) with neither prompt nor command; CLI `loop run` invoked without --prompt and without --command; prompt passed as '   ' (whitespace only, fails the trim() check).","commonSituations":"Scripts build options dynamically and the prompt variable is undefined when a config field is misnamed (e.g. promptText vs prompt); CLI users assume the loop reads a default task from state; empty-string prompt from an env var.","solutions":["Pass options.prompt with non-whitespace content when running in codex mode","Or switch to command mode by providing options.command","If building options dynamically, guard: if (!prompt?.trim() && !command) fail fast with your own message"],"exampleFix":"// before\nawait runCodexLoop({ name: 'lint-loop' }); // throws\n// after\nawait runCodexLoop({ name: 'lint-loop', prompt: 'Run npm run lint and fix findings' });\n// or command mode\nawait runCodexLoop({ name: 'lint-loop', command: 'npm run lint' });","handlingStrategy":"validation","validationCode":"const prompt = options.prompt?.trim();\nif (!prompt && !options.command) throw new Error('provide prompt or command');","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Default one of prompt/command in wrapper code and document the modes","Fail fast in CLI arg parsing with a helpful flag hint (--prompt or --command)","Guard dynamically built options for the classic undefined-prompt bug"],"tags":["validation","cli","usage-error","loop"],"backgroundTag":"missing-required-argument","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}