compat-muse

# compat-muse — OpenCode Zen → Grok Build bridge

> **Fixes `muse-spark-1.2-contributor-free` streaming inside Grok Build.** Runs as a tiny local proxy.

[![proxy: 127.0.0.1:8799](https://img.shields.io/badge/proxy-127.0.0.1%3A8799-14B8A6?style=flat-square)](#quick-start) [![verified: 2026-08-24](https://img.shields.io/badge/verified-2026--08--24-60A5FA?style=flat-square)](#verification) [![zero deps](https://img.shields.io/badge/zero--deps-stdlib-34D399?style=flat-square)](#quick-start)

![compat-muse architecture — Grok Build → localhost proxy → OpenCode Zen](./assets/architecture.svg)

## What is this?

**compat-muse** sits between Grok Build and OpenCode Zen (`https://opencode.ai/zen/v1`) and makes `muse-spark-1.2-contributor-free` work reliably. You point Grok at `http://127.0.0.1:8799` instead of OpenCode directly.

For the full technical investigation, protocol captures, root-cause analysis, and validation evidence, see **[TECHNICAL_REPORT.md](./TECHNICAL_REPORT.md)**.

## The problem

Grok Build expects strict OpenAI-compatible streaming. OpenCode Zen's streaming for this model breaks that contract on both endpoints (trailing ping events, missing IDs). The result is Grok errors instead of answers.

## The fix

The proxy always calls OpenCode **non-streaming** (`stream:false` — the lane that works), then **synthesizes a clean streaming response** locally for Grok. Successful proxied streams are synthesized into a strict client-compatible schema. See the technical report for details.

```
Grok Build → compat-muse :8799 → OpenCode Zen   (stream:false)
Grok Build ← clean SSE   ← compat-muse          (synthesized)
```

* Binds `127.0.0.1` only — never exposed to your network.
* No request bodies, prompts, or keys are ever logged.

## Quick start — just Python

**Prerequisites:** Python 3.10+ and an OpenCode Zen key.

**1. Set your key once (system-wide):**

```powershell
setx OPENCODE_API_KEY "sk-your-key-here"
# restart your terminal after setx
```

Or for one shell only:

```powershell
$env:OPENCODE_API_KEY = "sk-your-key-here"
```

**2. Run the proxy:**

```powershell
# from this directory
python muse.py
# → muse compat proxy  http://127.0.0.1:8799 -> https://opencode.ai/zen/v1
#   waiting for requests... press Ctrl+C to stop
```

That's it. Leave it running.

> Node alternative (`proxy.mjs`) exists with identical behavior if you prefer `node proxy.mjs