API Reference

parseLine(line: string): ClaudeEvent | null

Parse a single NDJSON line from Claude Code's stdout into a typed event.

• Returns null for empty lines, whitespace-only lines, or invalid JSON
• Does not throw — safe to call on any string

import { parseLine } from 'claude-code-parser'

const event = parseLine('{"type":"system","subtype":"init","model":"claude-sonnet-4-6-20250514"}')
// → { type: 'system', subtype: 'init', model: 'claude-sonnet-4-6-20250514' }

parseLine('')           // → null
parseLine('{bad json')  // → null

Translator

Stateful translator that converts raw ClaudeEvent objects into deduplicated RelayEvent objects.

Why Stateful?

In --verbose mode, every assistant event contains the complete message so far — not just new content. The translator tracks which content blocks have already been emitted and only yields new ones. See Deduplication for details.

Constructor

const translator = new Translator()

translate(event: ClaudeEvent): RelayEvent[]

Convert a raw event into zero or more relay events.

const relayEvents = translator.translate(claudeEvent)
for (const ev of relayEvents) {
  console.log(ev.type, ev)
}

reset(): void

Reset content tracking. Called automatically on result events (turn boundaries). Call manually when starting a new session.

sessionId: string | undefined

The session ID captured from the most recent system/init event.

model: string | undefined

The model name captured from the most recent system/init event.

RelayEvent

A discriminated union on the type field. Use switch (event.type) for full type narrowing.

text_delta

{ type: 'text_delta', content: string }

Assistant's text output (markdown).

thinking_delta

{ type: 'thinking_delta', content: string }

Extended thinking content.

tool_use

{ type: 'tool_use', toolUseId: string, toolName: string, input: string }

Tool invocation. input is the tool's input as a JSON string.

tool_result

{ type: 'tool_result', toolUseId: string, output: string, isError: boolean }

Tool execution result. output is the normalized content (polymorphic content already resolved).

session_meta

{ type: 'session_meta', model: string }

Emitted once when Claude Code starts. Contains the model name.

turn_complete

{
  type: 'turn_complete',
  sessionId?: string,
  costUsd?: number,
  inputTokens?: number,
  outputTokens?: number,
  contextWindow?: number,
}

Emitted when a turn finishes. inputTokens is the total: inputTokens + cacheReadInputTokens + cacheCreationInputTokens.

error

{ type: 'error', message: string, sessionId?: string }

Emitted on turn failure or is_error: true.

createMessage

Construct NDJSON messages for Claude Code's stdin. Each returns a JSON string terminated with \n.

createMessage.user(content: string): string

claude.stdin.write(createMessage.user('Hello Claude'))
// writes: {"type":"user","message":{"role":"user","content":"Hello Claude"}}\n

createMessage.approve(toolUseId: string): string

Approve a pending tool execution.

claude.stdin.write(createMessage.approve('toolu_abc123'))
// writes: {"type":"approve","tool_use_id":"toolu_abc123"}\n

createMessage.deny(toolUseId: string): string

Deny a pending tool execution.

claude.stdin.write(createMessage.deny('toolu_abc123'))
// writes: {"type":"deny","tool_use_id":"toolu_abc123"}\n

createMessage.toolResult(toolUseId: string, content: string): string

Send a tool result with custom content (for interactive tools like AskUserQuestion).

claude.stdin.write(createMessage.toolResult('toolu_abc123', 'User selected option B'))
// writes: {"type":"tool_result","tool_use_id":"toolu_abc123","content":"User selected option B"}\n

extractContent(raw: unknown): string

Normalize the polymorphic content field from tool_result blocks.

import { extractContent } from 'claude-code-parser'

extractContent('plain string')                                  // → 'plain string'
extractContent([{ type: 'text', text: 'a' }, { type: 'text', text: 'b' }])  // → 'a\nb'
extractContent(null)                                             // → ''

TypeScript Types

All types are exported for use in your own code:

import type {
  // Raw protocol types
  ClaudeEvent,
  ClaudeMessage,
  ClaudeContent,
  ModelUsageEntry,

  // Relay event types
  RelayEvent,
  TextDeltaEvent,
  ThinkingDeltaEvent,
  ToolUseEvent,
  ToolResultEvent,
  SessionMetaEvent,
  TurnCompleteEvent,
  ErrorEvent,
} from 'claude-code-parser'