Building a TypeScript client for OpenAI Harmony

I’ve been playing around with OpenAI’s new gpt-oss model this week, and immediately ran into an interesting challenge. The model uses this new message format called Harmony, and you really can’t use it effectively without properly formatting your messages this way.

OpenAI was thoughtful enough to release documentation explaining the format and even open-sourced a renderer for it written in Rust. Their codebase includes functionality to build the Rust program and wrap it with Python bindings, which is great if you’re working in that ecosystem. There’s also some indication they’re planning JavaScript support, but it’s not finished yet.

When the models first dropped, I wanted to dive right in and start experimenting. The problem was that implementations of the Harmony conversion varied across different providers and tools and many weren’t quite right. I realized I could save myself some headaches by using OpenAI’s official Harmony renderer, except for one small issue: it didn’t work with TypeScript, which is what I needed.

Naturally I soon embarked on a little adventure to bridge that gap myself.

I should mention I’m not a Rust developer by any stretch. But I was able to learn enough about its syntax and ecosystem to extend their code in useful ways. I figured out how to use serde and its plugins to correctly notate the code structure with Rust macros. From there, I generated a WASM binary of the Rust code and wrapped it with a TypeScript library, complete with typings derived from tsify.

The whole process was a fascinating challenge that spanned multiple languages and ecosystems. There’s something really satisfying about making different technologies work together, especially when you’re learning as you go. I found myself enjoying the process of discovery almost as much as reaching the solution.

If you’re interested in checking out the result, I’ve put it up on my GitHub as zacharytamas/harmony-ts and published it to npm as openai-harmony. I’m planning to deprecate it once OpenAI releases their official version at @openai/harmony, but in the meantime, it’s been a useful tool for experimentation.

Sometimes the most rewarding projects are the ones that start with “I need this to work, but it doesn’t yet.” Those little gaps in the ecosystem create perfect opportunities to learn something new while creating something immediately useful. This project definitely checked both those boxes for me.