Skip to content
Reflex Reflex Reflex Docs

Copilot

library

Lets a script hand work to the GitHub Copilot CLI (`copilot -p`): Copilot.task runs one instruction, Copilot.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_COPILOT_COMMAND), and already be signed in with a Copilot subscription; Reflex passes no credentials. Check with Copilot.available(). It runs non-interactively with --allow-all-tools and --no-ask-user, so it may run any shell command and change files without asking, and the project workspace of the current run is added as its working folder. 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 copilot command can be found on the PATH of the agent process (or at the path in REFLEX_COPILOT_COMMAND).
  • version string Returns the first line printed by `copilot --version`.
  • close self Closes every Copilot session of this script and stops Copilot processes that are still running for it.
  • session CopilotSession Starts a Copilot conversation: runs `copilot -p <prompt> --output-format json`, waits for it to finish and returns the session table.
  • task AgentTaskResult Runs one instruction through `copilot -p` and waits for it to finish.

available()

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

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

Returns

boolean

version()

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

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

Returns

string

close()

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

Closes every Copilot session of this script and stops Copilot 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()”
Copilot.session(prompt: string, model?: string, reasoning?: string, timeoutSeconds?: number)→CopilotSession

Starts a Copilot conversation: runs `copilot -p <prompt> --output-format json`, waits for it to finish and returns the session table. Later messages go to the same conversation through session.send (using `--resume=<id>`), so Copilot 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. 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 passed to the CLI as --model; 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

CopilotSession A Copilot conversation started by Copilot.session.

task()

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

Runs one instruction through `copilot -p` and waits for it to finish. The result is a table, not text: success (exit code 0), exit, text (the last answer message of Copilot), all (the complete output: JSON event lines, or readable text with showReasoning), and duration (milliseconds). Each task starts with a fresh context; use Copilot.session for follow-up questions.

Parameters

prompt string
The instruction for the agent, a non-empty string
model string optional
Model name passed to the CLI as --model; 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
true to print the agent's reasoning and answers to the script console while it works, and to make all a readable text instead of raw JSON events; 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 Copilot fails

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

Example 2

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

-- model, reasoning effort, 10 minute limit and live output in the console
local result = Copilot.task("Add a smoke test for the checkout page to tests/checkout.lua", nil, "high", 600, true)
print(result.success, result.duration .. " ms")