{"id":770,"date":"2026-04-22T12:38:14","date_gmt":"2026-04-22T04:38:14","guid":{"rendered":"https:\/\/connectword.dpdns.org\/?p=770"},"modified":"2026-04-22T12:38:14","modified_gmt":"2026-04-22T04:38:14","slug":"openai-open-sources-euphony-a-browser-based-visualization-tool-for-harmony-chat-data-and-codex-session-logs","status":"publish","type":"post","link":"https:\/\/connectword.dpdns.org\/?p=770","title":{"rendered":"OpenAI Open-Sources Euphony: A Browser-Based Visualization Tool for Harmony Chat Data and Codex Session Logs"},"content":{"rendered":"

Debugging an AI agent that runs for dozens of steps: reading files, calling APIs, writing code, and revising its own output, is not like debugging a regular function. There is no single stack trace to read. Instead, developers are left staring at hundreds of lines of raw JSON, trying to reconstruct what the model was actually thinking and doing at each step. OpenAI team is taking a direct swing at that problem with the release of Euphony<\/strong>, a new open-source browser-based visualization tool designed to turn structured chat data and Codex session logs into readable, interactive conversation views.<\/p>\n

Euphony<\/strong> is built specifically around two of OpenAI\u2019s own data formats: Harmony<\/strong> conversations and Codex session JSONL<\/strong> files. <\/p>\n

What is the Harmony Format?<\/strong><\/h3>\n

To understand why Euphony exists, you need a quick primer on Harmony. OpenAI\u2019s open-weight model series, gpt-oss<\/code>, was trained on a specialized prompt format called the harmony response format<\/strong>. Unlike standard chat formats, Harmony supports multi-channel outputs \u2014 meaning the model can produce reasoning output, tool calling preambles, and regular responses all within a single structured conversation. It also supports role-based instruction hierarchies (system<\/code>, developer<\/code>, user<\/code>, assistant<\/code>) and named tool namespaces.<\/p>\n

The result is that a single Harmony conversation stored as a .json<\/code> or .jsonl<\/code> file can contain a lot more structured metadata than a typical OpenAI API response. This richness is useful for training, evaluation, and agent workflows but it also makes raw inspection painful. Without tooling, you are reading deeply nested JSON objects with token IDs, decoded tokens, and rendered display strings all interleaved. Euphony was built to solve exactly this problem.<\/p>\n

What Euphony Actually Does<\/strong><\/h3>\n

At its core, Euphony is a web component library and standalone web app<\/strong> that ingests Harmony JSON\/JSONL data or Codex session JSONL files and renders them as structured, browseable conversation timelines in the browser.<\/p>\n

The tool supports three data loading methods<\/strong> out of the box: pasting JSON or JSONL directly from the clipboard, loading a local .json<\/code> or .jsonl<\/code> file from disk, or pointing it at any public HTTP(S) URL serving JSON or JSONL \u2014 including Hugging Face dataset URLs. Euphony then auto-detects the format and renders accordingly across four cases: if the JSONL is a list of conversations, it renders all conversations; if it detects a Codex session file, it renders a structured Codex session timeline; if a conversation is stored under a top-level field, it renders all conversations and treats other top-level fields as per-conversation metadata; and if none of those match, it falls back to rendering the data as raw JSON objects. <\/p>\n

The feature set goes well beyond basic rendering. Euphony surfaces conversation-level and message-level metadata<\/strong> directly in the UI through a dedicated metadata inspection panel \u2014 useful when evaluating annotated datasets where each conversation carries extra fields like scores, sources, or labels. It also supports JMESPath-based filtering<\/strong>, which lets developers narrow down large datasets by querying over the JSON structure. There is a focus mode<\/strong> that filters visible messages by role, recipient, or content type, a grid view<\/strong> for skimming datasets quickly, and an editor mode<\/strong> for directly modifying JSONL content in the browser. Markdown rendering (including mathematical formulas) and optional HTML rendering are supported inside message content.<\/p>\n

Two Operating Modes: Frontend-Only vs. Backend-Assisted<\/strong><\/h3>\n

Euphony is designed with a clean architectural split. In frontend-only mode<\/strong> (configured via the VITE_EUPHONY_FRONTEND_ONLY=true<\/code> environment variable), the entire app runs in the browser with no server dependency. In backend-assisted mode<\/strong>, a local FastAPI Python server handles remote JSON\/JSONL loading, backend translation, and Harmony rendering \u2014 which is particularly useful for loading large datasets. <\/p>\n

Embedding Euphony in Your Own Web App<\/strong><\/h3>\n

One of the more practical features for AI dev teams is that Euphony ships as reusable custom elements<\/strong> \u2014 standard Web Components that can be embedded in any frontend framework: React, Svelte, Vue, or plain HTML. After building the library with pnpm run build:library<\/code> (which outputs the main entrypoint at .\/lib\/euphony.js<\/code>), you can drop a <euphony-conversation><\/code> element into your UI and pass it a Harmony conversation either as a JSON string attribute or as a parsed JavaScript object via the DOM. Visual styling is fully overridable through CSS custom properties, covering padding, font colors, and role-specific color coding for user and assistant messages.<\/p>\n

The tech stack is primarily TypeScript (78.7% of the codebase) with CSS and a Python backend layer, and it is released under the Apache 2.0 license<\/strong>.<\/p>\n

Key Takeaways<\/strong><\/h3>\n