SDKStreaming output

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:

MessageWhat it holds
Start record (init)The model, the available tools, the slash commands, the MCP servers, the permission mode and the session id.
Status recordsProgress updates while the run works.
Assistant messagesEach 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

FlagAdds to the stream
--include-partial-messagesText and reasoning as they are produced, token by token.
--include-hook-eventsA record each time a hook runs.
--replay-user-messagesEach 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 type values as messages to skip. New kinds of record can be added.
  • Stop reading when the result record arrives, then check its is_error field before you trust result.
  • Use the exit code as well. A failed run exits with 1, and a usage error exits with 2. See Scripting and CI for the full list.

For the structure of the single final object, see the json output in Scripting and CI.