CodexSession

A Codex conversation started by Codex.session. The first prompt has already been answered when you get it (see last); send continues the same thread, so Codex remembers earlier messages.

• Kind Object
• Library Codex
• Category AI in scripts
• Functions 3

How to get one

1. Codex .session()
2. CodexSession

local chat = Codex.session(prompt)

Returned by

• Codex.session()

Functions

• send AgentSessionResult Sends the next message of the conversation and waits for the answer.
• id string | nil Returns the Codex thread id of this conversation, the same value as the sessionId field.
• close self Closes this session and stops its Codex process if one is still running.

send()

chat.send(prompt: string)→AgentSessionResult

Sends the next message of the conversation and waits for the answer. Returns the result table, which is also stored as session.last. Raises an error when the session is closed.

Parameters

prompt string

The next message in the conversation

Returns

AgentSessionResult The result of a message sent in a CLI agent session.

Fields of AgentSessionResult

success boolean

true when the CLI exited with code 0

exit number

process exit code

text string

the answer of the agent

all string

the complete CLI output

duration number

run time in milliseconds

sessionId string

id of the session, nil until the CLI reports it

messages any[]

the answer messages as a list of strings

All table shapes

Example

local chat = Codex.session("Read tests/checkout.lua and remember its structure.")
local answer = chat.send("Which steps are missing assertions?")
print(answer.text)
chat.close()

id()

chat.id()→string | nil

Returns the Codex thread id of this conversation, the same value as the sessionId field.

Returns

string | nil can be nil The session id, nil until the CLI has reported it

close()

chat.close()→self

Closes this session and stops its Codex process if one is still running. Afterwards send raises an error.

Returns

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