Headless runs

The headless mode of the command line runs one task and exits, without opening the app. Use it from a terminal or a script to hand Oda one task and read the answer, to follow the run as JSON events, or to continue a chat an earlier run saved. Oda profiles and launchers covers profiles in general, and Command line and flags covers how Oda reads the line.

Run one task and exit

Open a terminal on the computer where Oda runs.
Start the headless mode with the task:
sh
```
oda --profile headless "run the tests"
```
Read the answer on standard output. Oda exits when the task settles.

One task per run. The mode answers a single task and ends on its own; a second task cannot be sent into the same run. To continue the work later, adopt the chat the run saved (see below).
Nothing is served. The mode starts no interface, web server or browser layer, and it opens no listening port.
The answer stays clean. The final answer goes to standard output; reasoning and diagnostics go to standard error, so a script can read the answer without filtering it.
Budgets apply. The calls a task makes follow Oda's usual time budgets; Timeouts in Oda covers them and the message each timeout prints.

Pass the task in

As words on the line. oda --profile headless run the tests works the same way: the words are joined with spaces into a single task.
As piped text. With no task on the line, Oda reads the task from standard input:
sh
```
{ echo "Summarise these changes:"; git diff --stat; } | oda --profile headless
```
With the lone dash. A - as the only task argument reads the task from standard input as well. Mixing it with words is refused: `-` must be the only task argument.
A blank task is refused before anything runs. A blank or whitespace-only task stops the run; a whitespace-only task exits 1 even when text is piped in. With no task on the line and nothing piped in, the run stops with a task is required, for example: oda --profile headless "run the tests".
Piped text is sent as it arrives, including its trailing newline.

Read the answer and the exit code

The answer goes to standard output. A run that produces no assistant message writes an empty line there instead.
Reasoning streams to standard error under the oda: reasoning: heading, so it never mixes into the answer; a run that reasons nothing leaves standard error empty.
Captured standard error deserves care. Reasoning can reflect what the run worked with, so a script or log that keeps standard error keeps that material too.
Errors go to standard error as oda: <code>: <message>: the command prefix, a code that names the kind of problem, and the detail. The code distinguishes causes, for example FS_NOT_FOUND for something that cannot be found or FS_SANDBOX_DENIED when the sandbox refuses access.
Exit code 0 means the task completed.
Exit code 1 means the run did not complete: it was aborted or it errored, or it finished without an assistant message.

Continue a chat from an earlier run

Each run works in a chat of its own, saved for later, unless you name an earlier chat to continue.

Find the chat's id. A program that follows the JSON stream reads it from the opening session event.

Start the mode with the option and the new task:

oda --profile headless --session-id <id> "carry on with the task"

--session-id <id> adopts the saved chat with this id and runs the new task as its next message. An id Oda does not know fails before the task runs: session "<id>" does not exist; omit --session-id to start a new Session.
The id goes as typed. A blank id exits 1 with --session-id requires a non-empty session id; otherwise Oda passes the exact text of the id on to the run.
The chat must fit the run. Adoption is refused, before the task runs, when the chat is still live in this Oda process, was saved under a preset this mode does not run, is a subagent or forked chat, saved no folder, was saved in a different folder than the one you run from, or has damaged records. Adopting also needs the chat's saved records and their storage to be available; without them, the run is refused. Start from the chat's own folder, or omit the option to start a new chat.

Stream the run as JSON events

oda --profile headless --json "<task>" writes newline-delimited events to standard output instead of the final message.

Event	What it carries
`session`	Opens the stream: the chat's id and the folder the run works in.
`status`	The run's phase: `turn_start`, `step_start`, `step_end` or `turn_end`.
`text`	A piece of the assistant's answer, at the moment it is committed.
`thinking`	The model's reasoning, at the moment it is committed.
`tool_call`	A tool the run starts, with its arguments.
`tool_result`	How a tool ended: `completed` or `error`.
`final`	The run's final answer.
`error`	A problem with the invocation itself, such as a bad option or a missing task.

Commit points, not live tokens. text and thinking arrive when they are committed; an attempt that was discarded never reaches the stream.
Usage adds up across attempts. Usage figures on the status events sum retried attempts, and they are left out when an attempt has no sample.
A result is written once. A tool result is projected when it is appended to the chat, so a later compaction of the chat does not repeat it.
A failed task still closes with final. A task that fails during the run ends with a final event and no error event; the failure signal is exit code 1 and the reason on the closing turn_end.
Only a real --json turns the stream on. A literal --json after --, or as another option's value, does not switch the mode.

The JSON stream's bounds

Strings and keys stop at 8 KiB. A longer string or key is cut, and its event carries truncated: true.
One event line stays under 32 KiB. A line that would run longer is reduced until it fits, keeping the event's type.
Depth is capped. Values nested more than 64 levels deep are cut with a [truncated: depth] marker.
The final answer is not capped.
The stream is a projection, not a log. It is built for programs to follow the run, so it shows what the run committed, not a copy of the chat's full record.

Questions, answered

How do I pass the task to a headless run?

Three ways: as words on the line, which are joined with spaces into one task; as piped text, when you give no task; or with a lone -, which reads standard input. A blank task is refused before anything runs.

Does a headless run open a window or a port?

No. The mode starts no interface, web server or browser layer and opens no listening port, and it exits on its own when the task settles.

What do the exit codes of a headless run mean?

0 means the task completed. 1 means it did not: the run was aborted or errored, or it finished without an assistant message.

Why is standard output empty but the exit code is 1?

The run produced no assistant message. Oda writes an empty line to standard output to mark that, and exits 1 because the task did not complete.

What is `oda: reasoning:` on standard error?

The heading before the model's reasoning for the task. Reasoning goes to standard error so the answer on standard output stays clean; a run that reasons nothing leaves standard error empty.

Can I continue a chat from an earlier headless run?

Yes. --session-id <id> adopts the saved chat with that id and runs your task as its next message; without the option, the run starts a new chat. The chat must have been saved in the folder you run from, must not be running here, and must be one this mode can adopt; a refused adoption fails before the task runs.

Why was my `--session-id` refused?

The chat cannot be adopted from this run: it is unknown, still running in this Oda process, saved under a preset this mode does not run, a subagent or forked chat, saved with no folder or in a different folder, or its records are damaged. The chat's saved records and their storage may also be missing where you run. Fix the named case, or omit the option to start a new chat.

What does the `--json` stream contain?

One event per line: session, the status phases, text, thinking, tool_call, tool_result, final, and error for a problem with the invocation itself. Text and thinking arrive at commit points, not per token.

Does the `--json` stream lose anything?

It is not a full copy of the run. It shows what the run committed at each point: a discarded attempt never appears, a tool result is written once even if the chat is compacted later, and a failing task still ends with final instead of an error event.

What happens to very long output in `--json` mode?

Strings and keys stop at 8 KiB with truncated: true, one event line stays under 32 KiB, and values nested deeper than 64 levels are cut. The final answer is never capped.