If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/openai/harmony shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 4w ago
• 20 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 55% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live openai/harmony repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/openai/harmony.

What it runs against: a local clone of openai/harmony — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in openai/harmony | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 59 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of openai/harmony. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/openai/harmony.git
#   cd harmony
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of openai/harmony and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "openai/harmony(\\.git)?\\b" \\
  && ok "origin remote is openai/harmony" \\
  || miss "origin remote is not openai/harmony (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 59 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~29d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/openai/harmony"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

openai-harmony is a high-performance Rust library with Python bindings that renders and parses the Harmony response format—OpenAI's structured prompt/response protocol for gpt-oss open-weight models. It enables models to output reasoning chains, tool calls, and structured data across multiple semantic channels (analysis, commentary, final) while maintaining token-sequence consistency between encoding and decoding. Dual-language monorepo: src/ contains core Rust logic (lib.rs, chat.rs, encoding.rs, registry.rs), python/openai_harmony wraps it via pyo3 bindings (py_module.rs), and demo/harmony-demo/ is a Next.js 14 React app showcasing the format. Cargo.toml defines two crate types (rlib, cdylib) with conditional features for python-binding and wasm-binding.

ML engineers and inference framework builders (HuggingFace, Ollama, vLLM) deploying gpt-oss models who need to correctly format prompts and parse structured outputs; Python developers integrating gpt-oss into applications via the pip-installable openai-harmony package.

Actively maintained early-stage project (v0.0.8) with solid infrastructure: complete Python/Rust parity test suite in src/tests.rs, GitHub Actions CI in .github/workflows/CI.yml, and dual-language documentation (docs/python.md, docs/rust.md). Production-ready for gpt-oss integration but still pre-1.0 with potential API changes.

Low dependency risk: clean, well-audited set of dependencies (serde, regex, reqwest) with no obvious unmaintained packages. Single repository owner (OpenAI) mitigates abandonment risk, though tight coupling to gpt-oss model format means breaking changes to model training could require library updates. No visible open issue backlog in provided data.

Library is in active maintenance mode supporting gpt-oss production use. Recent work focuses on ensuring Python/Rust parity (run_checks.sh validates both), documenting the harmony format specification (docs/format.md), and providing a live interactive demo (demo/harmony-demo). No specific PR or milestone data visible, but CI/CD is fully operational.

git clone https://github.com/openai/harmony
cd harmony
# For Python development:
pip install -e .
# For Rust development:
cargo build
cargo test
# Run CI checks:
./run_checks.sh

Daily commands:

# Rust library:
cargo build --release
cargo test
# Python bindings (after Rust build):
pip install -e .
python -c "import openai_harmony; print(openai_harmony.__version__)"
# Demo app:
cd demo/harmony-demo
npm install
npm run dev  # Starts Next.js at localhost:3000

• src/encoding.rs: Core serialization/deserialization logic for the Harmony format; changes here affect both Rust and Python output
• src/chat.rs: Data structures for messages, tools, and channels; defines the Rust API surface that Python bindings expose
• src/py_module.rs: PyO3 bindings gluing Rust implementation to Python; this is how pip-installed users interact with the library
• docs/format.md: Authoritative specification of the Harmony response format; referenced by gpt-oss training and all inference framework implementations
• src/tests.rs: Comprehensive test suite with 100% Rust/Python parity; critical for validating token-sequence consistency
• demo/harmony-demo/src/components/HarmonyDemo.tsx: Interactive live example showing format parsing and rendering; helps users understand and debug the format visually
• .github/workflows/CI.yml: GitHub Actions pipeline that validates Rust, Python, and WASM builds; defines the release process

Adding format features: Edit src/chat.rs (message structures) and src/encoding.rs (serialization logic), then mirror changes in python/openai_harmony/ and update docs/format.md. Fixing parsing bugs: Start in src/registry.rs (token registry) or src/encoding.rs regex patterns. Python API changes: Modify src/py_module.rs and regenerate stubs. Demo updates: Work in demo/harmony-demo/src/components/HarmonyDemo.tsx. Always run: ./run_checks.sh after changes to ensure Rust/Python parity.

No Python pre-built wheels in repo: users must have Rust toolchain (rustc, cargo) installed to pip install openai-harmony from source—maturix should be configured in pyproject.toml to build wheels but this may not be automated yet. Format coupling to model training: Harmony tokens/channels are baked into gpt-oss weights; changing the format requires retraining or model incompatibility. WASM feature untested in CI: wasm-binding feature is defined in Cargo.toml but no visible WASM-specific tests in src/tests.rs, may bitrot. Image encoding: requests fetches images from URLs in encoding.rs; network failures will break rendering of image-heavy prompts silently unless handled.

• Structured Generation / Constrained Decoding — Harmony format enables models to generate outputs that conform to strict schemas (tool calls, reasoning channels) rather than free-form text; critical for reliable automation on top of gpt-oss
• Chain-of-Thought via Multi-Channel Output — Harmony splits reasoning (analysis channel) from final response (final channel), allowing models to show work without polluting user-facing output; core innovation of the format
• Token Preservation in Serialization — Encoding and decoding must be bitwise equivalent to avoid token loss during model training and inference; openai-harmony maintains this invariant via shared Rust implementation
• PyO3 FFI (Foreign Function Interface) — Library uses PyO3 to expose Rust code as native Python module; understanding the py_module.rs bindings is essential for debugging performance or correctness issues across languages
• Tool Namespacing — Harmony organizes function calls into namespaces (e.g., 'functions' namespace); prevents collision when gpt-oss calls multiple tool sets and enables framework to route calls correctly
• Base64 Image Encoding in Prompts — Harmony supports inline image embedding by fetching URLs and encoding as base64; src/encoding.rs handles this, critical for multimodal gpt-oss applications
• Regex-Based Format Parsing — Decoding Harmony format from model output requires precise regex matching (fancy-regex for lookahead/lookbehind); any regex bug breaks parsing and makes models appear broken

• openai/gpt-oss — The open-weight model series that requires Harmony format; defines the downstream spec that this library implements
• openai/cookbook — Contains gpt-oss usage examples and Harmony format tutorials (referenced in README as https://cookbook.openai.com/topic/gpt-oss)
• vllm-project/vllm — Popular inference framework; would consume openai-harmony for gpt-oss model serving and response parsing
• ollama/ollama — Edge inference runtime; users deploying gpt-oss via Ollama need Harmony format rendering to work correctly
• huggingface/transformers — Core ML library; Harmony format must integrate with HuggingFace's generation logic for gpt-oss compatibility

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive JavaScript/TypeScript bindings and tests for the harmony renderer

The repo has a javascript/ directory with only a README.md and package.json, but no actual implementation files. The demo in demo/harmony-demo/src/components/HarmonyDemo.tsx suggests there should be TypeScript bindings to render harmony responses in the browser. Currently, only Rust and Python bindings exist (via pyo3 and wasm-bindgen features). Adding a complete JS/TS implementation with unit tests would enable web developers to use harmony natively without WASM overhead for simpler use cases.

• [ ] Create javascript/src/ directory with TypeScript implementation of core harmony rendering logic
• [ ] Implement deserialization and rendering functions for harmony response format based on docs/format.md
• [ ] Add Jest/Vitest unit tests in javascript/ mirroring test cases from test-data/ directory
• [ ] Update javascript/package.json with proper build scripts and dependencies
• [ ] Document the JS API in javascript/README.md with examples

Add integration tests for Python bindings in CI workflow

The repo has a custom GitHub Action .github/actions/run-rust-python-tests/action.yml and references Python tests, but python/openai_harmony/ only contains __init__.py. The pyproject.toml exists but there are no visible Python test files. Adding comprehensive Python integration tests and ensuring they run in CI would validate the pyo3 bindings work correctly across different Python versions and platforms.

• [ ] Create python/tests/ directory with pytest test files covering harmony rendering, encoding, and registry functions
• [ ] Add test cases that mirror the Rust tests in src/tests.rs to ensure feature parity
• [ ] Update pyproject.toml with pytest configuration and test dependencies
• [ ] Ensure .github/workflows/CI.yml runs Python tests with multiple Python versions (3.8+) and platforms
• [ ] Document how to run Python tests locally in docs/python.md

Add WebAssembly end-to-end tests and documentation for browser usage

The repo has wasm-binding feature and a Next.js demo app, but test-data/ only contains text files. There are no visible WASM-specific integration tests validating that the wasm-bindgen and serde-wasm-bindgen bindings work correctly in browser environments. The demo component HarmonyDemo.tsx exists but lacks test coverage. Adding browser-based tests (e.g., using wasm-pack test or similar) would ensure WASM builds are reliable for the demo and end users.

• [ ] Create tests/wasm/ directory with JavaScript/TypeScript tests using wasm-pack test or Vitest with WASM support
• [ ] Add browser-based integration tests that load and render harmony responses using the WASM module
• [ ] Update demo/harmony-demo/ with unit tests for HarmonyDemo.tsx component using React Testing Library
• [ ] Add .github/workflows/ job to build and test WASM bindings in a browser environment
• [ ] Create docs/wasm.md documenting how to use harmony WASM bindings in web applications with examples

• Add explicit test cases in src/tests.rs for edge cases in image encoding (malformed URLs, oversized images, non-standard formats) that mirror the Python test suite in python/openai_harmony/
• Create a CONTRIBUTING.md guide documenting the Rust↔Python parity testing workflow (running ./run_checks.sh, debugging FFI bindings in py_module.rs) for first-time contributors unfamiliar with PyO3
• Expand docs/format.md with runnable examples showing how to use the Python API from openai_harmony for parsing tool calls and reasoning channels; currently only Rust examples are documented in docs/rust.md

• Medium · Unvalidated Image Processing Dependencies — Cargo.toml - dependencies: image = "0.25.6". The 'image' crate (version 0.25.6) is used for image processing. Image libraries historically have had vulnerabilities in parsing untrusted image formats. Without explicit input validation, processing user-supplied images could lead to DoS or code execution. Fix: Implement strict input validation for image processing, validate image dimensions and formats before processing, consider sandboxing image processing operations, and keep the image crate updated. Review the CHANGELOG for any known vulnerabilities.
• Medium · Regex Denial of Service (ReDoS) Risk — Cargo.toml - dependencies: regex = "1.10.3", fancy-regex = "0.13.0"; Usage likely in src/encoding.rs and src/chat.rs. The codebase uses both 'regex' and 'fancy-regex' crates for pattern matching. Without careful validation of regex patterns (especially if user-supplied), these could be exploited for ReDoS attacks causing performance degradation or hangs. Fix: Validate all regex patterns for catastrophic backtracking, limit regex complexity, set execution timeouts for regex operations, use regex caching, and avoid compiling untrusted regex patterns dynamically.
• Medium · Network Request Library Without Timeout Safeguards — Cargo.toml - dependencies: reqwest; Implementation likely in src/lib.rs or src/registry.rs. The 'reqwest' dependency (0.12.5) is used for HTTP requests. If no request timeouts are configured, the application could be vulnerable to slowloris attacks or indefinite hangs when connecting to malicious or unresponsive servers. Fix: Configure explicit timeouts for all reqwest operations (connect_timeout, timeout), implement retry logic with exponential backoff, validate URLs before making requests, and consider implementing circuit breakers for external API calls.
• Low · Base64 Encoding Without Input Validation — Cargo.toml - dependencies: base64 = "0.22.1"; Likely in src/encoding.rs. The 'base64' crate (0.22.1) is used, likely for encoding image data. Without proper validation of decoded content, there could be potential issues with malformed data processing. Fix: Validate decoded base64 content length and format, implement size limits on base64 input before decoding, and handle decode errors gracefully with proper error messages.
• Low · Cryptographic Hash Functions Used Without Clear Context — Cargo.toml - dependencies: sha1 = "0.10.6", sha2 = "0.10.9". SHA1 and SHA2 are included as dependencies (sha1 = "0.10.6", sha2 = "0.10.9"). While SHA2 is acceptable, SHA1 is cryptographically weak. Without knowing the use case, if SHA1 is used for security-critical operations, this could be a concern. Fix: Audit usage of SHA1 - if used for collision-resistant hashing, migrate to SHA256 or SHA3. If used only for non-cryptographic checksums, document this clearly. Prefer SHA2 or SHA3 for all security-critical operations.
• Low · Serialization Without Type Validation — Cargo.toml - dependencies: serde_json with preserve_order feature; likely in src/lib.rs. The codebase uses serde/serde_json with 'preserve_order' feature for JSON serialization. Processing untrusted JSON without strict schema validation could lead to unexpected behavior or memory exhaustion with deeply nested structures. Fix: Implement JSON schema validation before deserialization, set limits on nesting depth and document size, use strong typing with serde derive macros, and validate all external JSON inputs.
• Low · WASM Module Potential XSS Vector — Cargo.toml - features: wasm-binding; demo/harmony-demo/src components (TypeScript/React). The project includes WASM bindings (wasm-bindgen, serde-wasm-bindgen) for web deployment. If WASM outputs are rendered directly in the browser without sanitization, there could be XSS vulnerabilities. Fix: Ensure all WASM outputs are properly sanitized before rendering in HTML

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.