format-claude-stream

Note

format-claude-stream is not accepting contributions. We’re releasing the code for others to refer to and learn from, but we are not open to pull requests or issues at this time.

Khan Academy is a non-profit organization with a mission to provide a free, world-class education to anyone, anywhere. You can help us in that mission by donating or looking at career opportunities.

A CLI filter to turn Claude's streaming JSON output into human-readable text.

Installation

npm install -g @khanacademy/format-claude-stream

Usage

CLI

claude --print --output-format stream-json | format-claude-stream

Library

import {ClaudeStreamFormatter, StandardOutput, ChalkColorizer} from "format-claude-stream";

const claudeStreamFormatter = new ClaudeStreamFormatter(
    new StandardOutput(),
    new ChalkColorizer(),
);

await claudeStreamFormatter.write(JSON.parse(streamLine));

Development

Requirements:

node >= 20.20.0
pnpm >= 10.26.0

Everyday commands:

pnpm install  # install dependencies (one-time setup)
pnpm test     # run unit tests
pnpm verify   # run all checks
pnpm fix      # fix formatting

Releasing

Releases are managed via changesets.

The workflow is:

• Each feature PR must include a changeset file, generated by running pnpm changeset, describing what is in that change and whether a major, minor, or patch version bump is required.
• A GitHub workflow watches the main branch and updates a "Version Packages" PR whenever a feature PR is landed.
• When the "Version Packages" PR is landed, a GitHub workflow updates the package version and changelog based on outstanding changesets, builds a new version of the package, and publishes it to NPM.

Merging the "Version Packages" PR is a manual action (you can use git land for this). The package is built and released automatically when the "Version Packages" PR is merged.