Streaming output
With --output-format stream-json --verbose, Syntic Code prints one JSON message per line while the run goes on. Your program reads the lines as they arrive, instead of waiting for one final object. This page lists the kinds of message you get and the switches that add more detail.
The Syntic Code SDK packages are not released yet. This page describes the command-line stream that programs read today.
Turn it on
syntic -p "summarise the open issues in this repo" --output-format stream-json --verbose--verbose is required with stream-json.
The messages
Each line is a complete JSON object with a type field. In order, a run produces:
| Message | What it holds |
|---|---|
Start record (init) | The model, the available tools, the slash commands, the MCP servers, the permission mode and the session id. |
| Status records | Progress updates while the run works. |
| Assistant messages | Each message the agent produces, including its tool calls. |
Result (result) | The final answer and the run details, the same fields that --output-format json prints. |
When a plugin or an MCP server fails to load, the start record lists it in plugin_errors ({"plugin": ..., "error": ...}) or mcp_server_errors ({"server": ..., "error": ...}). Each field is present only when there is at least one error. The mcp_servers list also shows each server’s status.
The result record has this shape:
{
"type": "result",
"subtype": "success",
"is_error": false,
"result": "…",
"session_id": "4fb72789-…",
"num_turns": 1,
"stop_reason": "end_turn"
}To read only the answer, filter for the result line:
syntic -p "count the TODOs in src" --output-format stream-json --verbose \
| jq -c 'select(.type == "result") | .result'Add more detail
| Flag | Adds to the stream |
|---|---|
--include-partial-messages | Text and reasoning as they are produced, token by token. |
--include-hook-events | A record each time a hook runs. |
--replay-user-messages | Each user message, echoed before the reply that answers it. |
Use --include-partial-messages for a live display. Leave it off when you only need complete messages, because the stream is shorter.
Subagents in the stream
By default a subagent’s tool calls appear in the stream, but its own text does not. Add --forward-subagent-text (or set SYNTIC_FORWARD_SUBAGENT_TEXT=1) to include its text and reasoning too. This applies to stream-json output.
Read the stream safely
- Read one line at a time and parse each line on its own.
- Treat unknown
typevalues as messages to skip. New kinds of record can be added. - Stop reading when the
resultrecord arrives, then check itsis_errorfield before you trustresult. - Use the exit code as well. A failed run exits with
1, and a usage error exits with2. See Scripting and CI for the full list.
For the structure of the single final object, see the json output in Scripting and CI.