How to Enable Streaming Output in OpenClaude: A Complete Guide

To enable streaming output in OpenClaude, run the CLI in headless mode with --print, set --output-format=stream-json, and include the --verbose flag.

OpenClaude supports real-time streaming output via NDJSON, allowing applications to process tokens as they are generated rather than waiting for complete responses. This article explains how to activate and consume the streaming interface based on the official Gitlawb/openclaude source code.

Prerequisites for OpenClaude Streaming

Streaming output in OpenClaude requires three specific conditions to be met simultaneously. The implementation in src/cli/print.ts enforces these constraints strictly.

1. Enter Headless Mode with --print

The -p or --print flag disables the interactive UI and directs output to stdout. Without this flag, OpenClaude launches its conversational interface, which does not support streaming protocols.

openclaude -p "Your prompt here"

2. Select the Streaming Format

Set --output-format=stream-json to enable NDJSON output. This flag is defined in web/src/data/cliFlags.ts at line 42 alongside other format options.

openclaude -p --output-format=stream-json "Your prompt here"

3. Enable Verbose Logging

The print.ts implementation contains an explicit guard at lines 886–888 that throws an error if --verbose is missing when stream-json is requested.

openclaude -p --output-format=stream-json --verbose "Your prompt here"

Optional: Include Partial Messages

For intermediate tokens and partial generations, add --include-partial-messages. This flag, documented at lines 46–47 of web/src/data/cliFlags.ts, exposes the model's incremental output rather than buffering until complete sentences finish.

openclaude -p --output-format=stream-json --verbose --include-partial-messages "Write a story."

Complete Command Examples

Basic Streaming Usage

# Minimal working command for streaming JSON output

openclaude -p --output-format=stream-json --verbose "Explain recursion in 3 sentences."

Consume with jq

Pipe the NDJSON stream to jq for real-time content extraction:

openclaude -p --output-format=stream-json --verbose "List three JavaScript array methods." |
  jq -c '.content'

Each line prints as it arrives, enabling responsive downstream processing.

Using the Official SDK

The @openclaude/sdk package forwards the same constraints to the CLI internally:

import { OpenClaude } from '@openclaude/sdk'

const client = new OpenClaude({ /* authentication config */ })

const stream = client.query({
  prompt: 'Summarize the plot of "Inception".',
  outputFormat: 'stream-json',
  verbose: true,
})

for await (const chunk of stream) {
  console.log('Received:', chunk)
}

The outputFormat option is defined in src/entrypoints/sdk/coreSchemas.ts and accepts 'stream-json' as a valid value.

Key Source Files for Streaming Implementation

Understanding the codebase helps debug streaming issues:

File	Purpose
web/src/data/cliFlags.ts	Flag definitions including --output-format and --include-partial-messages
src/cli/print.ts	Headless printer implementation; enforces --verbose requirement at lines 886–888
src/utils/streamJsonStdoutGuard.ts	Guards process.stdout.write to ensure valid NDJSON output
src/cli/headlessHeartbeat.ts	Manages optional heartbeat events during streaming sessions
src/entrypoints/sdk/coreSchemas.ts	SDK schema with outputFormat: 'stream-json' option

Common Errors and Resolutions

Error	Cause	Fix
"Streaming output requires verbose mode"	Missing --verbose flag	Add --verbose to your command
"Invalid output format"	Typo in format string	Use exactly stream-json
Interactive UI launches	Forgot --print flag	Include -p or --print

Summary

• Headless mode (--print) is mandatory for streaming output in OpenClaude
• --output-format=stream-json selects the NDJSON protocol
• --verbose is enforced by src/cli/print.ts and cannot be omitted
• --include-partial-messages exposes incremental tokens for real-time applications
• The @openclaude/sdk abstracts these flags for programmatic usage

Frequently Asked Questions

What NDJSON format does OpenClaude streaming use?

Each line of stdout is a complete, parseable JSON object. The src/utils/streamJsonStdoutGuard.ts module intercepts writes to guarantee this structure, preventing malformed chunks from corrupting the stream.

Can I use streaming with the interactive UI?

No. Streaming output requires headless mode (--print). The interactive interface manages its own rendering loop and does not expose raw token streams.

Why does streaming require --verbose?

According to the source code in src/cli/print.ts (lines 886–888), verbose logging ensures sufficient metadata is available for each streamed chunk. This design decision links diagnostic detail with streaming capability.

How do I handle connection interruptions during streaming?

The src/cli/headlessHeartbeat.ts module emits optional heartbeat events you can monitor. Implement client-side retry logic that detects missing heartbeats and re-establishes the stream with your last successful sequence number.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}