Skip to content
Reflex Reflex Reflex Docs

OpenCode

library

Lets a script hand work to the OpenCode CLI (`opencode run`): OpenCode.task runs one instruction, OpenCode.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_OPENCODE_COMMAND), and have a model provider configured and signed in; Reflex passes no credentials. Check with OpenCode.available(). It runs non-interactively with the project workspace of the current run as its directory (--dir), so it can change files there. Prompts and file contents are processed by the configured AI provider. 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 opencode command can be found on the PATH of the agent process (or at the path in REFLEX_OPENCODE_COMMAND).
  • version string Returns the first line printed by `opencode --version`.
  • close self Closes every OpenCode session of this script and stops OpenCode processes that are still running for it.
  • session OpenCodeSession Starts an OpenCode conversation: runs `opencode run --format json <prompt>`, waits for it to finish and returns the session table.
  • task AgentTaskResult Runs one instruction through `opencode run` and waits for it to finish.

available()

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

Returns true when the opencode command can be found on the PATH of the agent process (or at the path in REFLEX_OPENCODE_COMMAND). Does not check that a provider is configured.

Returns

boolean

version()

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

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

Returns

string

close()

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

Closes every OpenCode session of this script and stops OpenCode processes that are still running for it. The conversations stay in OpenCode'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()”
OpenCode.session(prompt: string, model?: string, reasoning?: string, timeoutSeconds?: number)→OpenCodeSession

Starts an OpenCode conversation: runs `opencode run --format json <prompt>`, waits for it to finish and returns the session table. Later messages go to the same conversation through session.send (using `--session <id>`), so OpenCode remembers earlier messages. 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. In a session result, text is all text parts of the answer joined together. 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 as provider/model, for example anthropic/claude-sonnet-4; passed as -m, nil uses OpenCode'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

OpenCodeSession An OpenCode conversation started by OpenCode.session.

task()

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

Runs one instruction through `opencode run` and waits for it to finish. The result is a table, not text: success (exit code 0), exit, text (the answer: the plain output of the CLI with trailing whitespace removed), all (the complete output), and duration (milliseconds). The reasoning argument is passed as --variant. Each task starts with a fresh context; use OpenCode.session for follow-up questions.

Parameters

prompt string
The instruction for the agent, a non-empty string
model string optional
Model as provider/model, for example anthropic/claude-sonnet-4; passed as -m, nil uses OpenCode'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
true to run with --thinking and --print-logs and print the reasoning, logs and answer to the script console while it works; all then contains that readable text instead of the plain output; default false

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 OpenCode fails

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

Example 2

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

-- pick a model, reasoning variant and a 10 minute limit
local result = OpenCode.task("Add a smoke test for the checkout page to tests/checkout.lua", "anthropic/claude-sonnet-4", "high", 600)
print(result.success, result.duration .. " ms")