NDJSON

• NDJSON(Newline Delimited JSON)은 줄바꿈(\n)으로 JSON 객체를 구분하는 직렬화 포맷
• 각 줄이 하나의 완전한 JSON 객체 — 그게 전부
• TCP, Unix pipe, stdio 등 스트리밍 채널에서 여러 JSON을 순서대로 전송할 때 사용
• JSON-RPC, SSE 같은 “프로토콜”이 아니라 포맷(형식) — 줄 안의 내용 구조를 강제하지 않음

해당 개념이 필요한 이유

• 스트리밍 채널(TCP, stdio, pipe)에서 여러 JSON을 끊김 없이 순서대로 전송해야 할 때
• 로그 파일, 이벤트 스트림, 대용량 데이터를 한 줄씩 읽으며 처리해야 할 때 (메모리 효율)
• 서버-클라이언트 간 실시간 이벤트 push가 필요할 때 (AI 응답 streaming, 로그 수집 등)
• JSON 배열([{...},{...}])은 끝까지 받아야 파싱 가능하지만, NDJSON은 한 줄 도착할 때마다 즉시 처리 가능

AS-IS: JSON 배열 — 전체를 받아야 파싱 가능

sequenceDiagram
    autonumber
    participant Producer as Producer
    participant Consumer as Consumer

    Producer->>Consumer: [{...},{...},{...}] 전송 시작
    Note over Consumer: 아직 파싱 불가 (배열이 닫히지 않음)
    Producer->>Consumer: 전송 완료 (']' 도착)
    Consumer->>Consumer: 전체 파싱
    Note over Consumer: 마지막 바이트까지 기다려야 처리 가능

TO-BE: NDJSON — 한 줄마다 즉시 처리 (Claude Code CLI 예시)

sequenceDiagram
    autonumber
    participant App as Application
    participant CLI as claude CLI (--output-format stream-json)

    CLI-->>App: {"type":"system","subtype":"init",...}\n
    App->>App: 즉시 파싱 → 세션 초기화 처리
    CLI-->>App: {"type":"stream_event","event":{"delta":{"type":"text_delta","text":"Hello"}}}\n
    App->>App: 즉시 파싱 → UI에 토큰 출력
    CLI-->>App: {"type":"result","result":"...","session_id":"abc"}\n
    App->>App: 즉시 파싱 → 완료 처리

NDJSON 포맷 규칙 3가지

규칙 1. 각 줄 = 하나의 완전한 JSON

{"name":"Alice","age":30}\n
{"name":"Bob","age":25}\n
{"name":"Carol","age":35}\n

JSON 내부에 리터럴 줄바꿈이 있으면 반드시 \\n으로 escape해야 한다. 줄바꿈 = 메시지 구분자이기 때문이다.

규칙 2. 미디어 타입과 파일 확장자

항목	값
미디어 타입	application/x-ndjson
파일 확장자	.ndjson
인코딩	UTF-8 필수

HTTP API 응답으로 스트리밍할 때:

HTTP/1.1 200 OK
Content-Type: application/x-ndjson
 
{"id":1,"status":"processing"}\n
{"id":1,"status":"done","result":"ok"}\n

파일로 저장할 때:

# logs.ndjson
{"ts":"2026-04-17T10:00:00Z","level":"info","msg":"서버 시작"}
{"ts":"2026-04-17T10:00:01Z","level":"info","msg":"요청 수신"}
{"ts":"2026-04-17T10:00:02Z","level":"error","msg":"DB 연결 실패"}

규칙 3. 빈 줄은 무시 가능

파서는 빈 줄(\n\n)을 건너뛸 수 있다. heartbeat나 keep-alive 용도로 활용된다.

Claude Code CLI의 NDJSON 통신

--output-format stream-json 플래그로 활성화한다. 공식 문서에서 “Format: NDJSON (newline-delimited JSON)” 으로 명시한다.

출처: Claude Agent SDK TypeScript Reference

단방향 출력 스트림 (기본 활용)

claude -p "Fix the bug in auth.py" \
  --output-format stream-json \
  --allowedTools "Read,Edit,Bash"

{"type":"system","subtype":"init","session_id":"abc","model":"claude-sonnet-4-6",...}
{"type":"assistant","message":{"role":"assistant","content":[...]}}
{"type":"result","subtype":"success","result":"Fixed the bug.","session_id":"abc"}

Delta Streaming (토큰 단위 수신)

--include-partial-messages 추가 시 stream_event 타입의 delta 이벤트가 추가된다:

claude -p "Explain recursion" \
  --output-format stream-json \
  --include-partial-messages

{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":"재귀"}}}
{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":"는 함수가"}}}
{"type":"result","subtype":"success","result":"...","session_id":"abc"}

jq로 delta만 추출:

claude -p "Write a poem" --output-format stream-json --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

양방향 통신 (stdin + stdout 모두 NDJSON)

claude -p \
  --input-format stream-json \
  --output-format stream-json \
  --replay-user-messages

stdin에 NDJSON 형식의 사용자 메시지를 보내고, stdout에서 이벤트 스트림을 받는다:

← stdin: {"type":"user","message":{"role":"user","content":[{"type":"text","text":"Fix auth.py"}]}}
 
→ stdout: {"type":"user","message":{...}}     ← --replay-user-messages로 echo됨
→ stdout: {"type":"assistant","message":{...}}
→ stdout: {"type":"result","result":"Fixed.","session_id":"abc"}

Codex JSON-RPC 2.0 vs Claude SDKMessage

두 시스템 모두 NDJSON을 전송 포맷으로 사용하지만, 줄 안의 구조가 다르다.

프로토콜 비교표

항목	Codex app-server	Claude Code CLI
전송 포맷	NDJSON	NDJSON
내부 프로토콜	JSON-RPC 2.0 (기존 표준)	SDKMessage (Claude 고유)
공식 정의	jsonrpc.org 스펙	SDKMessage 타입 유니온 (TypeScript SDK 공식 문서)
메시지 구조	jsonrpc / method / id / params	type / subtype / session_id
요청-응답 매칭	id 필드로 매칭	없음 (단방향 push)
통신 방향	요청↔응답 양방향	출력 단방향 (옵션으로 양방향 가능)

SDKMessage 공식 타입 정의

출처: Claude Agent SDK TypeScript Reference

type SDKMessage =
  | SDKSystemMessage           // 세션 초기화
  | SDKAssistantMessage        // Claude 응답
  | SDKUserMessage             // 사용자 입력
  | SDKResultMessage           // 최종 결과
  | SDKPartialAssistantMessage // delta streaming (stream_event)
  | SDKHookStartedMessage      // hook 이벤트
  | SDKHookResponseMessage
  | SDKRateLimitEvent
  | SDKPluginInstallMessage
  // ... 총 20개 타입

실제 wire 데이터 비교

같은 작업 “Fix the bug”를 요청할 때:

# Codex app-server (JSON-RPC 2.0 over NDJSON)
# ──────────────────────────────────────────────────────────
← stdin:  {"jsonrpc":"2.0","method":"turn/start","params":{"message":"Fix the bug"},"id":1}

→ stdout: {"jsonrpc":"2.0","id":1,"result":{"threadId":"t_abc"}}               ← id:1 응답 매칭
→ stdout: {"jsonrpc":"2.0","method":"item/agentMessage/delta","params":{"delta":"I'll fix"}}
→ stdout: {"jsonrpc":"2.0","method":"item/agentMessage/delta","params":{"delta":" the bug"}}
→ stdout: {"jsonrpc":"2.0","method":"turn/completed","params":{}}

# Claude Code CLI (SDKMessage over NDJSON)
# ──────────────────────────────────────────────────────────
← 실행:   claude -p "Fix the bug" --output-format stream-json

→ stdout: {"type":"system","subtype":"init","session_id":"abc","model":"claude-sonnet-4-6"}
→ stdout: {"type":"stream_event","event":{"delta":{"type":"text_delta","text":"I'll fix"}}}
→ stdout: {"type":"stream_event","event":{"delta":{"type":"text_delta","text":" the bug"}}}
→ stdout: {"type":"result","subtype":"success","result":"Fixed.","session_id":"abc"}

두 출력 모두 줄바꿈으로 자른다 = NDJSON 동일. 줄 안의 구조가 method/id vs type/subtype = 프로토콜 다름.

[Codex]  줄 = {"jsonrpc":"2.0", "method":"...", "id":1, "params":{...}}
                                               ↑
                                         요청-응답 id 매칭 있음

[Claude] 줄 = {"type":"stream_event", "session_id":"abc", "event":{...}}
                                               ↑
                                         세션 구분만, id 매칭 없음

NDJSON은 “어떻게 자를 것인가” (줄바꿈으로 JSON 구분)이고, 프로토콜은 “그 안에 무엇을 담을 것인가”다.

이벤트 타입 참조 (SDKMessage)

type	subtype	설명
system	init	세션 시작, 모델/툴 정보
system	api_retry	API 재시도 이벤트
assistant	—	Claude 응답 메시지
user	—	사용자 메시지 (replay 시)
stream_event	—	delta streaming 이벤트
result	success	최종 결과 + session_id
result	error_*	오류 결과

참고 문서

• Claude Agent SDK TypeScript Reference — SDKMessage 타입 정의, NDJSON 명시
• Claude Code Headless / Programmatic Usage — stream-json CLI 사용법
• Stream responses in real-time — delta streaming 상세
• NDJSON Spec (GitHub) — NDJSON 공식 스펙
• JSON-RPC — Codex app-server가 사용하는 프로토콜
• Codex SDK 한계와 app-server 모드_1 — Codex app-server 구현 분석