The project's README from github.com/openai/euphony. As one markdown file: README.md.
Visualize harmony chat conversations and Codex sessions in your browser 🎵
| 🎵 Euphony Demo | 💬 Harmony Chat Example | 🤖 Codex Session Example |
Harmony conversations and Codex session logs are useful across training, evaluation, and agent workflows, but they are often difficult to inspect. Euphony addresses that gap by providing portable, customizable, and modular Web Components for visualizing structured chat data and Codex sessions in the browser.
| Feature | What it does |
|---|---|
| Harmony conversation viewer | Renders Harmony conversations with support for different message types and metadata. |
| Codex session viewer | Detects Codex session JSONL files, converts them into a conversation, and renders them in the same viewer. |
| Flexible loading | Loads data from the clipboard, local .json or .jsonl files, or public HTTP(S) JSON/JSONL URLs. |
| Markdown and HTML rendering | Renders markdown in message content, including formulas and optional HTML blocks. |
| Translation | Translates non-English text into English in normal mode or frontend-only mode with a user-provided OpenAI API key. |
| Metadata inspection | Exposes conversation-level and message-level metadata directly in the UI. |
| Filtering and focus mode | Filters datasets with JMESPath and narrows visible messages by role, recipient, or content type. |
| Grid and editor modes | Supports dataset skimming in grid view and direct JSONL editing in editor mode. |
| Harmony token rendering | Shows Harmony renderer output, token IDs, decoded tokens, and rendered display strings. |
| Embeddable web components | Ships reusable custom elements for integrating the viewer into other web apps in any framework (e.g., React, Svelte, Vue). |
There are two ways you can use Euphony.
.json or .jsonl fileTo use Euphony web components, first build the Euphony library:
pnpm install
pnpm run build:library
The main library entrypoint is built at: ./lib/euphony.js.
Then, you can import the JS file. To show a viewer of Harmony data, you can add the web component to your HTML file (or React, Svelte, Vue components):
<euphony-conversation conversation-string="HARMONY_CONVERSATION_JSON_STRING">
</euphony-conversation>
Alternatively, you can pass parsed JSON object directly into the euphony-conversation HTMLElement from Javascript.
const harmonyConversation: Conversation;
const myEuphonyConvoElement = document.querySelector('euphony-conversation');
myEuphonyConvoElement.conversationJSON = harmonyConversation;
Euphony web components are customizable. For example, to style these components, you can override CSS variables in your stylesheets.
--euphony-padding-v: 10px;
--euphony-padding-h: 15px;
--euphony-font-color: hsl(0, 0%, 12.94%);
--euphony-font-color-secondary: hsl(0, 0%, 61.96%);
--euphony-user-color: hsl(122, 43.43%, 38.82%);
--euphony-assistant-color: hsl(282, 67.88%, 37.84%);
--euphony-conv-background-color: hsl(0, 0%, 96.08%);
Euphony can run in two modes:
| Mode | What it is for |
|---|---|
| Frontend-only mode | Recommended for static or external hosting. URL loading happens in the browser, and translation uses a user-provided OpenAI API key when needed. |
| Backend-assisted mode | Optional for local development. The FastAPI server supports remote JSON/JSONL loading, backend translation, and Harmony rendering. Useful to load large datasets. |
The backend server is optional. It should only be used locally. Frontend-only mode is controlled with the Vite env variable VITE_EUPHONY_FRONTEND_ONLY.
VITE_EUPHONY_FRONTEND_ONLY=true to force frontend-only mode.VITE_EUPHONY_FRONTEND_ONLY=false to use the local backend-assisted mode.The current backend includes a remote URL fetch path for loading JSON and JSONL data. If you host that backend on an external server, it can introduce SSRF risk because the server may be tricked into fetching attacker-controlled URLs. Therefore, only use the backend-assisted mode for local development.
To develop Euphony locally, install Node.js and a package manager such as pnpm.
Start the backend server:
pnpm install
uvicorn fastapi-main:app --app-dir server --host 127.0.0.1 --port 8020 --reload
Start the frontend development server:
pnpm run dev
To force frontend-only mode with Vite:
VITE_EUPHONY_FRONTEND_ONLY=true pnpm run dev
Visit http://localhost:3000/, you should see Euphony running in your browser!
To build the static frontend:
pnpm run build
python -m http.server -d ./dist
To build a frontend-only static bundle:
VITE_EUPHONY_FRONTEND_ONLY=true pnpm run build
python -m http.server -d ./dist
Euphony is released under the Apache 2.0 license. See LICENSE.
The file src/css/prism-coldark-auto.css is derived
from an upstream Prism theme (GitHub)
and remains subject to the MIT license terms of that upstream work.