Codec for Claude Code's stream-json protocol.
Claude Code started with --input-format stream-json --output-format stream-json --verbose --include-partial-messages reads and writes newline-delimited JSON (one JSON object per line) on stdin and stdout. This module decodes one output line into a typed frame and encodes the frames the bridge writes to stdin.
Decoding
decode/1 never raises. It returns:
{:ok, frame}whereframeis one of the structs inframe/0. A frame with atypethis module does not model, or asystemframe other thaninit, decodes toMingaClaudeBridge.Wire.Unknown.{:error, {:invalid_json, {kind, offset}}}when the line is not valid JSON. The reason holds only the error kind and byte offset, never line content.{:error, :not_a_frame}when the JSON value is not an object with a stringtype.{:error, {:invalid_frame, type}}when a modeled frame lacks a required field or has a field of the wrong JSON type.
Enumerated strings (stop reasons, result subtypes, rate-limit status) decode to atoms from closed tables. Unknown values decode to {:other, string}; the codec never creates atoms from input.
Encoding
Each encoder returns one complete line, newline included, ready to write to the Port. Optional fields that are nil are omitted from the JSON.
Payloads
Decoded frames hold conversation content. This module does not log or store anything, and callers must not log frame contents or Unknown.raw.
Field-name sources
Field names were checked against @anthropic-ai/claude-agent-sdk 0.3.330 (sdk.d.ts types and the sdk.mjs control-protocol implementation): SDKSystemMessage, SDKPartialAssistantMessage, SDKAssistantMessage, SDKUserMessage, SDKResultSuccess/SDKResultError, SDKRateLimitEvent/SDKRateLimitInfo, SDKControlRequest, SDKControlResponse (ControlResponse/ControlErrorResponse), SDKControlCancelRequest, SDKControlInitializeRequest, SDKControlInterruptRequest, SDKControlMcpMessageRequest, and SDKControlPermissionRequest. Stream events follow the Anthropic Messages API streaming events, which the SDK embeds as BetaRawMessageStreamEvent.
Unverified
resetsAtunits: Unix seconds per pi-claude-bridge observation, not stated in the SDK types. SeeMingaClaudeBridge.Wire.RateLimit.- The
userinput frame: the SDK type markssession_idanduuidoptional, and pi-claude-bridge sends neither. Whether a given CLI version requires them on stdin is not confirmed;user_message/2omits them unless given. - The success reply to an
mcp_messagerequest wraps the JSON-RPC reply asresponse.mcp_response. This is confirmed fromsdk.mjsbut not from a typed declaration.
Summary
Types
The id of a JSON-RPC 2.0 error reply. It is nil (JSON null) when the request id could not be read.
A JSON-RPC 2.0 request id.
One encoded frame: a JSON object followed by a newline.
Functions
Encodes a client-initiated control request, for example %{"subtype" => "get_usage", "skip_behaviors" => true}. request must hold a string "subtype".
Encodes a control_response that rejects a control request with an error message.
Decodes one stream-json line. A trailing newline is allowed.
Encodes the initialize control request, which the bridge sends before the first prompt.
Encodes the interrupt control request, which stops the current turn.
Encodes a successful answer to an mcp_message control request whose JSON-RPC reply is an error, for example code -32800 for a cancelled request.
Encodes a successful answer to an mcp_message control request whose JSON-RPC reply is a result.
Encodes a user frame that sends a prompt or tool results to Claude Code.
Types
@type decode_error() :: {:invalid_json, {kind :: atom(), offset :: non_neg_integer()}} | :not_a_frame | {:invalid_frame, type :: String.t()}
@type error_id() :: jsonrpc_id() | nil
The id of a JSON-RPC 2.0 error reply. It is nil (JSON null) when the request id could not be read.
@type frame() :: MingaClaudeBridge.Wire.SystemInit.t() | MingaClaudeBridge.Wire.StreamEvent.t() | MingaClaudeBridge.Wire.Assistant.t() | MingaClaudeBridge.Wire.User.t() | MingaClaudeBridge.Wire.Result.t() | MingaClaudeBridge.Wire.RateLimit.t() | MingaClaudeBridge.Wire.ControlRequest.t() | MingaClaudeBridge.Wire.ControlResponse.t() | MingaClaudeBridge.Wire.ControlCancel.t() | MingaClaudeBridge.Wire.Unknown.t()
A JSON-RPC 2.0 request id.
@type line() :: String.t()
One encoded frame: a JSON object followed by a newline.
Functions
Encodes a client-initiated control request, for example %{"subtype" => "get_usage", "skip_behaviors" => true}. request must hold a string "subtype".
Encodes a control_response that rejects a control request with an error message.
@spec decode(binary()) :: {:ok, frame()} | {:error, decode_error()}
Decodes one stream-json line. A trailing newline is allowed.
Encodes the initialize control request, which the bridge sends before the first prompt.
Options:
:sdk_mcp_servers- names of the MCP servers the bridge hosts over the control channel, for example["minga"].:system_prompt- the system prompt, as a string or a list of strings. The wire field is a list; a string is sent as a one-element list.:append_system_prompt- text appended to the system prompt.
Encodes the interrupt control request, which stops the current turn.
Encodes a successful answer to an mcp_message control request whose JSON-RPC reply is an error, for example code -32800 for a cancelled request.
The control request itself succeeds; the JSON-RPC error tells the MCP client that the call failed. jsonrpc_id is nil when the request id could not be read, which encodes as JSON null.
@spec mcp_result(String.t(), jsonrpc_id(), map()) :: line()
Encodes a successful answer to an mcp_message control request whose JSON-RPC reply is a result.
jsonrpc_id is the id of the JSON-RPC request inside the mcp_message. request_id is the control request's id.
@spec user_message(String.t() | [MingaClaudeBridge.Wire.Block.t()], keyword()) :: line()
Encodes a user frame that sends a prompt or tool results to Claude Code.
content is a string or a list of MingaClaudeBridge.Wire.Block values. A string is sent as one text block.
Options:
:session_id- the Claude Code session id. Omitted when absent.:uuid- a client message uuid that Claude Code echoes back on the reply. Omitted when absent.