Skip to content
Reflex Reflex Reflex Docs

Codex

library

Lets a script hand work to the OpenAI Codex CLI (`codex exec`): Codex.task runs one instruction, Codex.session keeps a conversation going over several messages. Use it to let an AI agent analyse, generate or change files in the project and then check the result in the script. Things to know: the CLI runs on the machine of the Reflex agent. It must be installed there, on the PATH of the agent process (or set REFLEX_CODEX_COMMAND), and already be signed in; Reflex passes no credentials. Check with Codex.available(). It runs non-interactively in the project workspace of the current run with the workspace-write sandbox and approvals disabled, so it can change files there without asking. Prompts and file contents are processed by an external AI service. Arguments are positional (use nil to skip one). A run is killed after 30 minutes unless you give a timeout. A CLI that fails or times out does not raise an error: check result.success (exit is -1 on a timeout). Errors are raised for a missing CLI, a bad argument or an invalid reasoning value.

  • Kind Library, a global in every script
  • Category AI in scripts
  • Functions 5

Functions

  • available boolean Returns true when the codex command can be found on the PATH of the agent process (or at the path in REFLEX_CODEX_COMMAND).
  • version string Returns the first line printed by `codex --version`.
  • close self Closes every Codex session of this script and stops Codex processes that are still running for it.
  • session CodexSession Starts a Codex conversation: runs `codex exec --json` with the prompt, waits for it to finish and returns the session table.
  • task AgentTaskResult Runs one instruction through `codex exec` and waits for it to finish.

available()

Section titled “available()”
Codex.available()→boolean

Returns true when the codex command can be found on the PATH of the agent process (or at the path in REFLEX_CODEX_COMMAND). Does not check that it is signed in.

Returns

boolean

version()

Section titled “version()”
Codex.version()→string

Returns the first line printed by `codex --version`. Raises an error when the CLI is missing or prints nothing within 10 seconds.

Returns

string

close()

Section titled “close()”
Codex.close()→self

Closes every Codex session of this script and stops Codex processes that are still running for it. The conversations stay in the CLI's own history; sessions that were closed cannot send again.

Returns

self chainable The library itself, so calls can be chained.

session()

Section titled “session()”
Codex.session(prompt: string, model?: string, reasoning?: string, timeoutSeconds?: number)→CodexSession

Starts a Codex conversation: runs `codex exec --json` with the prompt, waits for it to finish and returns the session table. Later messages go to the same conversation through session.send (using `codex exec resume <id>`), so Codex remembers the earlier messages and the files it already looked at. The returned table has the functions send, id and close and the fields sessionId, last (the result of the latest message, see AgentSessionResult) and closed. Raises an error when the CLI does not report a session id.

Parameters

prompt string
The instruction for the agent, a non-empty string
model string optional
Model name handed to the CLI; nil uses the CLI's configured default
reasoning string optional
"low", "medium" or "high" (anything else is an error); nil uses the CLI default
timeoutSeconds number optional
Kill the CLI when it runs longer than this many seconds, must be above 0; default 1800 (30 minutes)

Returns

CodexSession A Codex conversation started by Codex.session.

task()

Section titled “task()”
Codex.task(prompt: string, model?: string, reasoning?: string, timeoutSeconds?: number, showReasoning?: boolean)→AgentTaskResult

Runs one instruction through `codex exec` and waits for it to finish. The result is a table, not text: success (exit code 0), exit, text (the final answer of Codex), all (the complete output including progress lines), and duration (milliseconds). Each task starts with a fresh context; use Codex.session for follow-up questions. With showReasoning true Codex also produces reasoning summaries and its progress output is printed to the script console while it runs.

Parameters

prompt string
The instruction for the agent, a non-empty string
model string optional
Model name handed to the CLI; nil uses the CLI's configured default
reasoning string optional
"low", "medium" or "high" (anything else is an error); nil uses the CLI default
timeoutSeconds number optional
Kill the CLI when it runs longer than this many seconds, must be above 0; default 1800 (30 minutes)
showReasoning boolean optional
Include the reasoning output in the console log

Returns

AgentTaskResult The result of a one-off task run with a CLI agent library (Codex, Copilot, OpenCode).
Fields of AgentTaskResult
success boolean
true when the CLI exited with code 0
exit number
process exit code
text string
the final answer of the agent
all string
the complete CLI output
duration number
run time in milliseconds
All table shapes

Example 1

Ask for a review and fail the script when Codex fails

local result = Codex.task("Read scripts/login.lua and list any step that has no assertion. Reply as a bullet list.")
if not result.success then
    error("Codex failed (exit " .. result.exit .. "): " .. result.all)
end
print(result.text)

Example 2

Let Codex write a file in the project, with a time limit

-- model, reasoning effort and a 10 minute limit; nil keeps the CLI default for the model
local result = Codex.task("Add a smoke test for the checkout page to tests/checkout.lua", nil, "high", 600)
print(result.success, result.duration .. " ms")