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.

Summary

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

In addition to the usual Claude output, format-claude-stream prints:

• Chain-of-thought
• All tool calls, and their results, in an easy-to-read format
• Tool call errors
• A raw JSON dump of any events it doesn't understand.

Output is color-coded to make it easier to scan.

With format-claude-stream, you can print the live stream or dump the JSON to a file and audit it later. With tee (see below), you can do both!

Installation

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

Usage

CLI

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

You can use tee to duplicate the output to a timestamped file:

claude --print --verbose --output-format stream-json \
  | tee "claude-$(date +'%Y-%m-%d_%H%M%S').jsonl" \
  | format-claude-stream

Library

import {ClaudeStreamFormatter, StandardOutput, ChalkColorizer} from "@khanacademy/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 tsc -w   # watch for type errors
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.