Use --output-format stream-json for Real-Time Processing

If you're building tools that wrap Claude Code, you need structured output you can process line-by-line as it arrives. --output-format stream-json gives you exactly that — a stream of newline-delimited JSON events.

claude -p --output-format stream-json "Analyse the API routes in src/routes/"

Each line is a self-contained JSON object representing one event in the session:

{"type":"system","subtype":"init","session_id":"abc123","tools":["bash","read","write"]}
{"type":"assistant","message":{"content":[{"type":"text","text":"Looking at the routes..."}]}}
{"type":"assistant","message":{"content":[{"type":"tool_use","name":"read","input":{"file_path":"src/routes/api.ts"}}]}}
{"type":"result","subtype":"success","cost_usd":0.004,"duration_ms":3241}

Process the stream with jq to extract exactly what you need:

# Stream just the text content as it arrives
claude -p --output-format stream-json "Review the routes" | \
  jq -r 'select(.type=="assistant") | .message.content[] | select(.type=="text") | .text'

# Log cost after every automated run
claude -p --output-format stream-json "Run the audit" | \
  jq -r 'select(.type=="result") | "Cost: $\(.cost_usd) | Duration: \(.duration_ms)ms"'

If you don't need real-time streaming and prefer a single JSON object at the end, use --output-format json instead — same structure, but delivered all at once after the session completes.

stream-json turns Claude Code from a black box into a live event stream you can build on.