@claude-agent-kit/messages

Utilities and types for working with Claude Agent streaming transcripts. Provides helpers to build user content blocks (prompt + attachments), normalize/append SDK messages into UI-friendly chat messages, and coalesce noisy sequences (e.g., multiple Read tool calls) for better rendering.

• Peer dependency: @anthropic-ai/claude-agent-sdk
• Works in both Node and the browser

Installation

pnpm add @claude-agent-kit/messages

Quick Start

Build user content blocks (prompt + attachments) compatible with the Claude Agent SDK:

import { buildUserMessageContent, type AttachmentPayload } from '@claude-agent-kit/messages'

const attachments: AttachmentPayload[] = [
  {
    name: 'diagram.png',
    mediaType: 'image/png',
    data: '<base64-bytes>',
  },
]

const content = buildUserMessageContent('Summarize this image', attachments)
// pass `content` into the SDK user message

Convert/append SDK messages into chat messages for rendering:

import {
  appendRenderableMessage,
  convertSDKMessages,
  coalesceReadMessages,
  type ChatMessage,
} from '@claude-agent-kit/messages'
import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk'

// Convert a whole transcript
const chatMessages: ChatMessage[] = convertSDKMessages(sdkMessages)

// Stream updates: append one SDK message at a time
const working: ChatMessage[] = [...chatMessages]
const { addedMessage, updatedMessages } = appendRenderableMessage(working, incomingSdkMessage)

// Optional: condense consecutive successful Read tool uses
const condensed = coalesceReadMessages(working)

API Surface

• Message building
  • buildUserMessageContent(prompt, attachments)
• Message shaping
  • appendRenderableMessage(messages, incoming)
  • convertSDKMessages(sdkMessages)
  • coalesceReadMessages(messages)
• Types
  • Content blocks: TextContentBlock, ImageContentBlock, DocumentContentBlock, ToolUseContentBlock, ToolResultContentBlock
  • Chat model: ChatMessage, ChatMessagePart
  • Attachments: AttachmentPayload

Notes

• Images (jpeg/png/gif/webp) are inlined as base64 image blocks.
• Plain text attachments are decoded and added as document blocks.
• PDFs are passed through as base64 document blocks.

See Also

• Top-level System Design section in the root README.md for architecture and flows.
• Real-world usage: examples/claude-code-web (message rendering), examples/basic-example.