Euphony: Harmony Chat and Codex Session Viewer

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.

Features

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.
Codex sessions browser	Lists local Codex sessions with pagination, prompt/response filters, fuzzy search, and full-text search over indexed turns.
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).

Get Started

There are two ways you can use Euphony.

1. Use the standalone app to view Harmony JSON/JSONL data and Codex session JSONL files.
2. Use the Euphony JavaScript library to render Harmony data in your own web app.

Use Euphony to View My Data

1. Load data from one of the supported sources:
   1. Paste JSON or JSONL from the clipboard
   2. Choose a local .json or .jsonl file
   3. Provide a public HTTP(S) URL that serves JSON or JSONL (e.g., Hugging Face)
2. Euphony automatically detects and renders the input:
   1. If the JSONL is a list of conversations → Euphony renders all conversations
   2. If the JSONL is a Codex session file → Euphony renders a structured Codex session timeline
   3. If the conversation is stored at some top-level field → Euphony renders all conversations and treat other top-level fields as each conversation’s metadata
   4. Else → Euphony renders the data as raw JSON objects

Browse Local Codex Sessions

When you run the local backend, Euphony also exposes a dedicated sessions page at /sessions.html.

The sessions page can:

• paginate through local session logs under ~/.codex/sessions or CODEX_HOME/sessions
• show each session's first prompt, last prompt, last response preview, and timestamps
• open any session directly in the main Euphony viewer
• filter by:
  • first prompt
  • last prompt
  • last response
• search across sessions with three modes:
  • Exact: keyword matching on session summary fields such as prompts, response preview, cwd, session id, and file path
  • Fuzzy: typo-tolerant matching on those same summary fields
  • Full text: indexed search across multi-turn user and assistant text from the whole session

The full-text index is built lazily the first time you run a full-text search and is stored locally at ~/.codex/euphony-codex-sessions.sqlite3 or inside CODEX_HOME when that environment variable is set.

Integrate Euphony into My Web App

Web Component API

To 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%);

Frontend-only and Backend-assisted Modes

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.

• Set VITE_EUPHONY_FRONTEND_ONLY=true to force frontend-only mode.
• Set 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.

Development

To develop Euphony locally, install Node.js and a package manager such as pnpm.

For the optional FastAPI backend, use Python 3.9 or newer and install the Python dependencies from pyproject.toml. Euphony currently pins openai-harmony==0.0.4 because newer releases may require a local Rust toolchain during installation on some environments.

After installing dependencies, the easiest way to run Euphony locally is with ./start.sh.

Start in the default production-style local mode:

python3.9 -m pip install -e .
pnpm install
pnpm run build
./start.sh

This mode starts only the FastAPI server on http://127.0.0.1:8020 and serves the prebuilt frontend from dist/, including http://127.0.0.1:8020/sessions.html.

Use this mode when you mainly want to open the local app and the sessions page without running a separate Vite dev server.

Start in explicit development mode:

./start.sh dev

Development mode starts both:

• the backend with uvicorn --reload
• the Vite frontend dev server with hot module reload

Use this mode when you are changing frontend or backend code and want immediate reloads while developing.

You can override ports in either mode:

BACKEND_PORT=8025 FRONTEND_PORT=3005 ./start.sh dev

./start.sh also accepts MODE=prod or MODE=dev if you prefer environment variables over positional arguments.

Common local URLs:

• backend-served app: http://127.0.0.1:8020/
• backend-served sessions page: http://127.0.0.1:8020/sessions.html
• frontend dev server in ./start.sh dev: http://127.0.0.1:3000/

If you prefer to launch the pieces manually, use the commands below.

Start the backend server:

python3.9 -m pip install -e .
pnpm install
uvicorn fastapi-main:app --app-dir server --host 127.0.0.1 --port 8020 --reload

The first backend Harmony render may download o200k_base.tiktoken from https://openaipublic.blob.core.windows.net/encodings/. If your environment cannot reach that URL, set TIKTOKEN_ENCODINGS_BASE to a local directory that already contains the tokenizer file.

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

License

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.