claude-mods/skills/claude-code-headless/references/output-formats.md

Output Formats Reference

Detailed documentation for Claude Code output formats.

Text Format (Default)

Human-readable output for terminal use.

claude -p "Hello"
# Output: Hello! How can I help you today?

Characteristics:

• Plain text response
• May include ANSI colors (disable with NO_COLOR=1)
• No metadata (session ID, cost, etc.)
• Best for interactive scripts

JSON Format

Structured output for programmatic parsing.

claude -p "Hello" --output-format json

Success Response

{
  "type": "result",
  "subtype": "success",
  "result": "Hello! How can I help you today?",
  "session_id": "session_abc123xyz",
  "total_cost_usd": 0.00123,
  "duration_ms": 1542,
  "num_turns": 1,
  "is_error": false
}

Error Response

{
  "type": "result",
  "subtype": "error",
  "result": "Error message here",
  "session_id": "session_abc123xyz",
  "total_cost_usd": 0.0005,
  "duration_ms": 234,
  "num_turns": 0,
  "is_error": true
}

Field Reference

Field	Type	Description
type	string	Always "result"
subtype	string	"success" or "error"
result	string	Response text or error message
session_id	string	Session identifier for resumption
total_cost_usd	number	Total API cost in USD
duration_ms	number	Total execution time in milliseconds
num_turns	number	Number of conversation turns
is_error	boolean	Whether result is an error

Parsing Examples

# Extract session ID
session=$(claude -p "Start" --output-format json | jq -r '.session_id')

# Check for errors
result=$(claude -p "Task" --output-format json)
if [[ $(echo "$result" | jq -r '.is_error') == "true" ]]; then
    echo "Error: $(echo "$result" | jq -r '.result')"
    exit 1
fi

# Get cost
cost=$(echo "$result" | jq -r '.total_cost_usd')
echo "Cost: \$${cost}"

Stream-JSON Format

Real-time JSONL (JSON Lines) output for streaming applications.

claude -p "Count to 5" --output-format stream-json

Message Types

Assistant Message

{"type": "assistant", "content": "1", "timestamp": "2024-01-15T10:30:00Z"}
{"type": "assistant", "content": "2", "timestamp": "2024-01-15T10:30:01Z"}

Tool Use

{"type": "tool_use", "tool": "Read", "input": {"file_path": "/path/to/file"}, "timestamp": "..."}
{"type": "tool_result", "tool": "Read", "output": "file contents...", "timestamp": "..."}

Final Result

{"type": "result", "session_id": "...", "total_cost_usd": 0.01, "duration_ms": 5000}

Stream Processing

# Process each line as it arrives
claude -p "Long task" --output-format stream-json | while IFS= read -r line; do
    type=$(echo "$line" | jq -r '.type')
    case "$type" in
        assistant)
            echo "Claude: $(echo "$line" | jq -r '.content')"
            ;;
        tool_use)
            echo "Using: $(echo "$line" | jq -r '.tool')"
            ;;
        result)
            echo "Done! Cost: \$$(echo "$line" | jq -r '.total_cost_usd')"
            ;;
    esac
done

Node.js Stream Processing

const { spawn } = require('child_process');
const readline = require('readline');

const claude = spawn('claude', ['-p', 'Task', '--output-format', 'stream-json']);

const rl = readline.createInterface({ input: claude.stdout });

rl.on('line', (line) => {
    const event = JSON.parse(line);
    switch (event.type) {
        case 'assistant':
            process.stdout.write(event.content);
            break;
        case 'result':
            console.log(`\nCost: $${event.total_cost_usd}`);
            break;
    }
});

Python Stream Processing

import subprocess
import json

proc = subprocess.Popen(
    ['claude', '-p', 'Task', '--output-format', 'stream-json'],
    stdout=subprocess.PIPE,
    text=True
)

for line in proc.stdout:
    event = json.loads(line)
    if event['type'] == 'assistant':
        print(event['content'], end='', flush=True)
    elif event['type'] == 'result':
        print(f"\nCost: ${event['total_cost_usd']}")

Format Comparison

Feature	text	json	stream-json
Real-time output	Yes	No	Yes
Structured data	No	Yes	Yes
Session ID	No	Yes	Yes
Cost tracking	No	Yes	Yes
Easy parsing	No	Yes	Yes
Best for	Humans	Scripts	Real-time apps

Format Selection Guide

Use Case	Format
Interactive terminal	text
CI/CD pipelines	json
Web applications	stream-json
Cost tracking	json
Session management	json
Live progress display	stream-json