Muse Codex

Keep the harness. Change the model.

An independent compatibility gateway for using OpenAI or Z.ai models through the stock Muse Code CLI.

Warning

Experimental and source-only. Muse Codex currently supports Apple-silicon macOS and exactly Muse Code 1.0.3-R2198.1. Other Muse versions are rejected. No public binary release is available.

Important

Muse Codex is not affiliated with, endorsed by, or distributed by Meta or OpenAI. Install and license Muse Code separately through Meta's official channel.

What it does

Muse Codex keeps the unmodified Muse executable in charge of the terminal UI, sessions, prompts, tools, approvals, sandbox, skills, subagents, and worktrees. It replaces only the model connection with a private loopback gateway backed by the pinned OpenAI Codex client.

• Preserves the host: normal Muse commands and provider-independent behavior stay in the stock executable.
• Isolates credentials: Muse receives a short-lived loopback token, never an OpenAI credential.
• Keeps tools local: the gateway translates model traffic but never executes a model-requested tool.
• Fails closed: unsupported Muse builds, conflicting providers, unsafe endpoints, and unverifiable release artifacts are rejected.

Ownership boundary

Stock Muse owns	Muse Codex owns	Not included here
TUI and exec mode	CLI routing and version gate	The proprietary Muse binary
Sessions and context	Isolated per-provider authentication	Upstream service access
Tools and approvals	Loopback gateway lifecycle	A public binary release
Sandbox and extensions	Model catalog and stream translation	Modified Muse host source

flowchart LR
    U[User] --> L[muse-codex launcher]
    L -->|spawns| M[Stock Muse Code]
    L -->|starts| G[Loopback gateway]
    M -->|ephemeral bearer token| G
    G -->|authenticated HTTPS| O[OpenAI or Z.ai]
    M --> T[Tools, approvals, sandbox]

Loading

See Architecture and the Security model for the detailed boundaries.

Compatibility

Component	Supported baseline
Operating system	macOS on Apple silicon (arm64)
Muse Code	Exactly 1.0.3-R2198.1
Rust	1.95.0 for source builds
OpenAI Codex source	rust-v0.153.4 at 3d2ee51ca2d5db578f328aa75e20aa22c0197c9a
Authentication	ChatGPT browser/device login, an OpenAI API key, or a Z.ai API key
Providers	--provider codex (default) and --provider zai

The current Meta installer may provide a newer Muse build. Muse Codex does not bypass its version gate; verify the installed binary before building:

$ muse --version
Muse Code 1.0.3 (1.0.3-R2198.1)

If the output differs, this version of Muse Codex will not start a session.

Providers

Each launch selects exactly one upstream and never falls back to the other. Omitting --provider selects codex.

Provider	Upstream	Authentication
codex (default)	OpenAI Responses API	ChatGPT subscription or an OpenAI API key
zai	Z.ai GLM Coding Plan (https://api.z.ai/api/coding/paas/v4)	Z.ai API key

Credentials live in two separate keyring records, so signing out of one leaves the other untouched, and a launch that selects one provider can never be served by the other's credential.

Models

Muse Codex discovers models from the authenticated OpenAI catalog on every provider startup and never invents account entitlements. With Codex rust-v0.153.4, the compatibility layer understands the current catalog and Responses Lite contract used by:

• gpt-6-astra
• gpt-5.6-sol
• gpt-5.6-terra
• gpt-5.6-luna

Only models returned as picker-visible for the active ChatGPT account are offered in subscription mode. Models that require a newer client protocol, advertise an unknown tool mode, omit text input, or have no recognized reasoning effort remain hidden until the transport is updated. For the first-party API, API-key discovery intersects endpoint-returned IDs with the pinned Codex protocol metadata, so unrelated embedding, audio, image, and moderation models are not presented as chat models. Explicit compatible custom endpoints remain permissive for models they advertise. See OpenAI's current model catalog and GPT-6 Astra guidance for public model information; the CLI treats its authenticated catalog as the source of truth for access, picker order, context limits, and effort choices.

Quick start from source

Install the exact Muse prerequisite through Meta's official Muse Code installer, then:

git clone https://github.com/Srimi1/muse-codex.git
cd muse-codex

cargo build --workspace --release --locked

mkdir -p "$HOME/.local/bin"
install -m 0755 target/release/muse-codex "$HOME/.local/bin/muse-codex"
install -m 0755 target/release/muse-codex-gateway "$HOME/.local/bin/muse-codex-gateway"

The launcher and gateway must remain beside one another or both be available on PATH. For a nonstandard Muse location, set MUSE_CODEX_MUSE_BIN to the exact executable.

Authenticate

Browser login is the default:

muse-codex login

For a terminal that cannot receive a browser callback:

muse-codex login --device-auth

Or store an OpenAI API key supplied over standard input:

printf '%s' "$OPENAI_API_KEY" | \
  muse-codex auth set --provider codex --api-key-stdin

For the Z.ai GLM Coding Plan, store its key in its own keyring record:

printf '%s' "$ZAI_API_KEY" | \
  muse-codex auth set --provider zai --api-key-stdin

Z.ai issues static keys and has no interactive sign-in, so muse-codex login is rejected for that provider.

ChatGPT subscription authentication and API-key billing are separate modes. Muse Codex never silently falls back between them. Credentials are stored in an isolated operating-system keyring namespace rather than a plaintext auth.json.

Run Muse

muse-codex
muse-codex exec "Explain the failing tests, then propose a fix"
muse-codex resume
muse-codex serve

Use Muse's /model picker in the TUI, or select an account-visible model explicitly:

muse-codex --model gpt-6-astra
muse-codex exec --model gpt-6-astra "Review this repository"
muse-codex --model gpt-6-astra --reasoning-effort ultra
muse-codex --fast --model gpt-6-astra
muse-codex --fast --model gpt-6-astra --reasoning-effort ultra

For a model whose authenticated catalog offers it, ultra is also available from the TUI's /effort picker. Ultra is distinct from max: max requests the model's maximum single-agent reasoning level, while Ultra enables Muse's proactive workflow and subagent delegation mode and can consume tokens more quickly. Following the pinned Codex client contract, the underlying model request uses the catalog-defined multi-agent effort (xhigh for GPT-6 Astra); Ultra's additional behavior lives in the Muse agent harness.

--fast requests OpenAI Fast mode for the entire TUI, exec, resume, or serve process. It is a service tier, not a reasoning effort, so it can be combined with Ultra as shown above. Fast uses priority processing with increased usage or cost. Stock Muse 1.0.3 has no service-tier field or /fast command, so changing the selection requires starting a new process with or without --fast. For ChatGPT, the gateway requires the selected model to advertise the priority tier (or the pinned client's legacy fast capability), then sends service_tier: "priority" and the trusted routing hint. A custom API-key endpoint receives the priority tier without catalog gating and determines whether it supports it. Without --fast, the gateway strips and omits any service tier. The startup banner says Fast was requested because the service can report a downgraded tier.

To run the same harness against your Z.ai subscription:

muse-codex --provider zai
muse-codex --provider zai exec --model glm-5.3 "Review this repository"

Z.ai publishes no model-listing endpoint, so the GLM catalog is pinned in the source and validated at startup against Z.ai's plan-usage endpoint, which confirms the key and an active plan without spending a coding prompt. Set MUSE_CODEX_ZAI_SKIP_PROBE=1 to skip that check and defer credential validation to the first turn.

Arguments unrelated to provider routing pass through to Muse. The public provider is either omitted or explicitly --provider codex or --provider zai; other provider values are rejected.

For complete setup, private signed-feed installation, environment variables, and endpoint rules, see Installation and Configuration.

Security and privacy

The launcher removes inherited provider credentials before starting Muse. It binds the compatibility gateway only to 127.0.0.1, authenticates the local hop with a random per-run token, and keeps OpenAI credentials inside the auth and gateway boundary. A custom upstream base URL is accepted only with explicit API-key authentication.

Review the Security policy before deploying or reporting an issue. Suspected vulnerabilities should be submitted through private vulnerability reporting, not a public issue.

Known limits

• The exact supported Muse build may no longer be the build served by Meta's moving installer.
• Transport compatibility does not imply that different models make identical tool choices or produce identical output.
• The ChatGPT backend is private and unstable. The vendored Codex source is open source, but its Rust crates are not a stable library API.
• Deterministic stock-vs-wrapped CLI/MSP tests cover text, tools, terminal failures, and protocol routing. Full feature parity remains a release gate; the public CI suite cannot run the separately licensed stock binary.
• Live subscription text, tool/result, and MSP restart/resume smoke tests pass locally. Catalog fixtures cover GPT-6 Astra and the GPT-5.6 Sol, Terra, and Luna models, but account access is never inferred from fixture data.
• serve --no-session-log is unsupported because the pinned host does not deliver MSP turn events in memory-only mode. Use normal serve instead.
• New response event types, auxiliary routes, and Muse releases require explicit compatibility work before support is claimed.
• Hooks, MCP servers, skills, and plugins retain Muse's existing trust model.
• With --provider zai: --fast is rejected (GLM has no service tier), the web-search and browser-open routes return 501, and freeform (custom) tools are approximated as a single-string function because Z.ai has no freeform tool type.
• The Z.ai GLM catalog is pinned rather than discovered, and prompts sent under --provider zai are governed by Z.ai's terms rather than OpenAI's.

Track planned qualification work in the Roadmap.

Documentation

Document	Contents
Installation	Source builds and signed private-feed installation
Configuration	Environment, authentication, and endpoint behavior
Architecture	Components, data flow, command routing, and failure rules
CLI and protocol	MSP provider mapping, streaming, and qualification limits
Security model	Trust boundaries, protected assets, and residual risks
Dependency review	Reachability review of open pinned-dependency alerts
Releasing	Private signed-release process and checklist
Contributing	Development workflow and review expectations
Support	Supported scope and help channels
Changelog	User-visible project changes

The official Muse Code SDK is a useful reference for the Muse Session Protocol. The exact OpenAI source snapshot used here is recorded under vendor/openai-codex.

Development

cargo fmt -p codex-transport -p muse-codex -p muse-codex-gateway -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --all-targets --locked
bash tests/scripts/release-tooling-test.sh

CI runs the same quality gates and an Apple-silicon release build. Unit and fixture tests do not require live OpenAI or Meta credentials.

With the exact stock binary installed, run the additional credential-free CLI/MSP differential suite:

cargo build --workspace --locked
MUSE_CODEX_MUSE_BIN=/absolute/path/to/muse-bin-1.0.3-R2198.1 \
  python3 tests/scripts/cli-msp-parity-test.py

Contributions are welcome. Start with CONTRIBUTING.md, use the issue forms for scoped proposals and reproducible bugs, and keep security reports private.

License and trademarks

First-party source and project artwork are licensed under the Apache License 2.0. See Third-party notices for vendored dependencies.

Muse, Muse Code, Muse Spark, Meta, OpenAI, ChatGPT, GPT, and Codex are trademarks of their respective owners. This license does not grant rights to redistribute third-party software or imply endorsement by any trademark owner.