Medley

A community multi-provider fork of Grok Build.

Medley keeps upstream Grok Build's terminal coding agent — the full-screen TUI that reads your codebase, edits files, runs shell commands, searches the web, and manages long-running tasks — and adds provider choice on top of it: a provider-scoped OpenAI Codex login, any OpenAI-compatible endpoint, and keyless local models, each with its credentials kept in its own lane.

Fork notice · What Medley adds · Coexistence · Installing · Documentation · Repository layout · Development · Support and contributions · License and notices

---

Fork notice

Important

Medley is a community fork. It is not affiliated with, endorsed by, sponsored by, or supported by xAI.

"Grok" and "Grok Build" are trademarks of xAI; the Apache-2.0 license that covers the upstream source grants no trademark rights. Medley uses those names only to identify the project it is derived from. xAI provides no warranty, support, or security response for this distribution — see NOTICE.md for the full trademark and non-affiliation statement.

Note

Three names for one binary. The release archives and install.sh ship it as medley, installed under ~/.medley/bin. A source build produces the upstream cargo bin target xai-grok-pager — crate and bin names deliberately do not change, see Repository layout. Official upstream installs ship that same target as grok. Command examples in this repository and throughout the user guide are written as grok …; read them as "whatever you invoke your build as".

State lives in ~/.medley. It resolves as $MEDLEY_HOME → $GROK_HOME → ~/.medley when it exists → ~/.grok when it exists and ~/.medley does not → ~/.medley, so a fresh install lands in ~/.medley while an existing ~/.grok keeps working. MEDLEY_HOME is the only MEDLEY_* variable the binary itself reads; every other application variable is still GROK_*. The MEDLEY_* prefix otherwise belongs to the installer. See Coexistence for the migration and the remaining sharp edges.

This repository (ImL1s/medley) tracks upstream on main (a pristine fast-forward mirror) and ships the fork's product line on providers, which is the default branch for users and releases. See FORK.md for the branch model, the upstream sync process, and the full list of divergences. SOURCE_REV records the upstream commit this tree was synced from.

What Medley adds

Relative to upstream Grok Build, the providers branch adds:

Capability	What it means
Provider-scoped OpenAI Codex OAuth	grok login --provider openai-codex signs in with a ChatGPT account through a Codex-compatible browser OAuth flow with PKCE. The credential is stored under its own openai::codex scope, refreshes and rotates independently, and grok logout --provider openai-codex removes only that scope — the xAI session and any credential owned by the official Codex CLI are left untouched. Check state with grok auth status --provider openai-codex.
Custom OpenAI-compatible endpoints	[model.*] entries take base_url, api_backend (chat_completions, responses, messages), env_key, per-request query_params, and env_http_headers so a secret can come from the environment instead of config.toml. Anthropic, Gemini, OpenRouter, Together AI, and generic gateways are worked examples.
Keyless local models	auth_scheme = "none" sends no Authorization / x-api-key at all, which is what Ollama, LM Studio, llama.cpp, and vLLM expect. Without it a local server can receive an ambient xAI Bearer token it never asked for.
Strict credential isolation	An unknown or malformed auth_scheme marks the model unready and fails closed rather than silently falling back to Bearer; unready models are rejected by the picker, /model, new sessions, session restore, and ACP model switches. On third-party endpoints and auth_scheme = "none", the x-grok-user-id / x-grok-deployment-id identity headers are omitted. Custom model-catalog discovery uses an explicit key rather than your signed-in session.
Readiness surfaced in the TUI	/model and Ctrl+M show ready / missing / none badges, hard-block unready models, and ask for confirmation when a switch crosses auth classes.

Details and copy-pasteable configuration live in Custom Models and Authentication.

Note

The Codex transport is compatibility with a pinned public Codex contract — not an OpenAI Platform API, not a stability guarantee, and not an endorsement by OpenAI. Your account entitlements, workspace policy, and OpenAI's terms still govern what works. See the service boundary in NOTICE.md.

Coexistence with official Grok Build

Medley now installs under its own command and keeps its state in its own directory, so the two builds no longer collide by default. What still needs care:

• Command. The installer writes a medley command into ~/.medley/bin and never touches an existing grok binary — it warns when it finds one. A source build has no installed name of its own; if you put target/release/xai-grok-pager on your PATH as grok, PATH order silently decides which build runs.
• State. Medley resolves its state directory as $MEDLEY_HOME → $GROK_HOME → ~/.medley when it exists → ~/.grok when it exists and ~/.medley does not → ~/.medley. The installed medley launcher pins the directory to its install location before the binary starts, so an installed Medley does not fall through to ~/.grok — unless you have exported MEDLEY_HOME or GROK_HOME yourself, which the launcher deliberately leaves alone so your choice wins. A source build has no launcher, so on a machine that already has ~/.grok it does resolve to it until the migration below runs.
• Migration. When Medley resolves to ~/.grok, the first interactive run offers a one-time copy into ~/.medley; nothing is deleted and ~/.grok is left as it was. Decline, and Medley writes a .medley-keep-legacy marker into ~/.grok and stops asking — it then keeps sharing that directory with official Grok Build, which can corrupt both: Medley writes provider-scoped credentials and config fields (model_provider, auth_scheme) that upstream does not know, and upstream schema changes can likewise confuse Medley. Non-interactive runs never prompt; they keep using ~/.grok and log one line saying so.
• Environment. Both builds still honour the same GROK_* variables, including GROK_HOME. Exporting GROK_HOME globally therefore points both at one directory again — set MEDLEY_HOME instead, which only Medley reads. Renaming the application's own GROK_* variables is remaining scope on #49.

Note

Medley does not self-update. The inherited updater points at upstream's release channel, so running it would replace Medley with an official Grok Build binary and silently drop the fork's features. Every one of its entry points now refuses instead, and says so — no configuration required. To upgrade, re-run install.sh. See Updates and the release channel.

Installing

Caution

The official installer does not install Medley. x.ai/cli/install.sh, x.ai/cli/install.ps1, and grok update all fetch xAI's official build. Use them only if upstream Grok Build is what you want.

From a release (macOS and Linux)

install.sh downloads the release archive for your platform, verifies its SHA-256 against the release checksums file, unpacks it under ~/.medley/versions/<version>/, and writes a medley launcher into ~/.medley/bin that supplies ~/.medley as the state directory whenever you have not exported MEDLEY_HOME or GROK_HOME yourself:

curl -fsSL https://raw.githubusercontent.com/ImL1s/medley/providers/install.sh | sh

Variable	Effect
MEDLEY_VERSION	Version or tag to install (default: latest published release)
MEDLEY_INSTALL_DIR	Where the medley launcher goes (default: ~/.medley/bin)
MEDLEY_HOME	Where unpacked versions and state live (default: ~/.medley)
MEDLEY_TARGET	Force a target triple instead of detecting one
MEDLEY_REPO	Source repository (default: ImL1s/medley)
MEDLEY_DRYRUN	Set to 1 to print the plan and skip the download, extraction, and install. The release version is still resolved first, so this queries the GitHub API unless MEDLEY_VERSION is also set

Releases are published for aarch64/x86_64 macOS and Linux. The installer refuses to install into ~/.grok, never touches an existing grok binary, and warns when it finds one. Windows is not covered — build from source there.

The Linux archives are dynamically linked and need glibc 2.35 or newer — Ubuntu 22.04+, Debian 12+, Fedora 36+. Distributions on an older glibc need a build from source: RHEL 9, Rocky 9, Alma 9, and Amazon Linux 2023 are all on 2.34, and Debian 11 and Ubuntu 20.04 on 2.31. The release job measures this floor out of each binary and fails rather than publishing an archive that would not start, so the number above is asserted, not aspirational. Lowering it — static musl builds, or building against an older glibc in a container — is tracked in #82.

Building from source

Requirements:

• Rust — the toolchain is pinned by rust-toolchain.toml; rustup installs it automatically on first build.

• DotSlash — required so hermetic tools under bin/ (notably bin/protoc) can download and run. Install it and ensure dotslash is on your PATH before building:

  cargo install dotslash
  # or: prebuilt packages — https://dotslash-cli.com/docs/installation/
  /usr/bin/env dotslash --help   # sanity check

• protoc — proto codegen resolves bin/protoc via DotSlash, or falls back to a protoc on PATH / $PROTOC.

• macOS and Linux are supported build hosts; Windows builds are best-effort and not currently tested from this tree.

git clone -b providers https://github.com/ImL1s/medley.git
cd medley
cargo run -p xai-grok-pager-bin              # build + launch the TUI
cargo build -p xai-grok-pager-bin --release  # release binary: target/release/xai-grok-pager
cargo check -p xai-grok-pager-bin            # fast validation

Check out providers — main is the pristine upstream mirror and contains none of the fork's changes.

The binary artifact is named xai-grok-pager; official upstream installs ship it as grok, and the release archives ship it as medley. A source build keeps the cargo name, so what you invoke it as is up to you. On first launch it opens your browser to authenticate — see the authentication guide. If the machine already has a ~/.grok directory, that first interactive launch also offers the one-time copy into ~/.medley described under Coexistence.

Documentation

The user guide ships with the pager crate: crates/codegen/xai-grok-pager/docs/user-guide/ — getting started, keyboard shortcuts, slash commands, configuration, theming, MCP servers, skills, plugins, hooks, headless mode, sandboxing, and more. Pages that describe fork-specific behaviour carry a fork note; the rest is upstream documentation carried along by the sync, so treat installation, update, and support instructions in it as describing the official build.

xAI's online documentation for the upstream product is at docs.x.ai/build/overview. It does not cover this fork.

Repository layout

Path	Contents
crates/codegen/xai-grok-pager-bin	Composition-root package; builds the xai-grok-pager binary
crates/codegen/xai-grok-pager	The TUI: scrollback, prompt, modals, rendering
crates/codegen/xai-grok-shell	Agent runtime + leader/stdio/headless entry points
crates/codegen/xai-grok-tools	Tool implementations (terminal, file edit, search, ...)
crates/codegen/xai-grok-workspace	Host filesystem, VCS, execution, checkpoints
crates/codegen/...	The rest of the CLI crate closure (config, MCP, markdown, sandbox, ...)
crates/common/, crates/build/, prod/mc/	Small shared leaf crates pulled in by the closure
third_party/	Vendored upstream source (Mermaid diagram stack) — see below

Crate names, module paths, and the cargo bin target deliberately keep their xai-grok-* names: renaming them would make every upstream sync a conflict. The rebrand is an outward one.

Important

The root Cargo.toml (workspace members, dependency versions, lints, profiles) is generated — treat it as read-only. Prefer editing per-crate Cargo.toml files.

Development

cargo check -p <crate>        # always target specific crates; full-workspace builds are slow
cargo test -p xai-grok-config # per-crate tests
cargo clippy -p <crate>       # lint config: clippy.toml at the repo root
cargo fmt --all               # rustfmt.toml at the repo root

CI runs on providers only, over the fork's hot path. See FORK.md for the sync workflow, the auth/config watchlist, and the release tagging scheme.

Support and contributions

Report Medley bugs and request features on the fork's tracker: https://github.com/ImL1s/medley/issues. Feature branches target providers, never main.

Warning

CONTRIBUTING.md and SECURITY.md are inherited upstream documents describing xAI's policies for the official project — including a HackerOne program that does not cover this fork. Do not send Medley bugs or vulnerability reports there. The fork's own contribution and security policy is tracked in #28.

License and notices

First-party code in this repository — upstream's and the fork's — is licensed under the Apache License, Version 2.0; see LICENSE. The fork's modifications relative to upstream are described in FORK.md, which serves as the Apache-2.0 §4(b) change notice.

NOTICE.md carries the upstream attribution, the trademark statement, the non-affiliation notice, and the third-party service boundary for the OpenAI Codex transport.

Third-party and vendored code remains under its original licenses. See:

• THIRD-PARTY-NOTICES — crates.io / git dependencies, bundled UI themes, and in-tree source ports (including openai/codex and sst/opencode tool implementations)
• crates/codegen/xai-grok-tools/THIRD_PARTY_NOTICES.md — crate-local notice for the codex and opencode ports (license texts + Apache §4(b) change notice)
• third_party/NOTICE — vendored Mermaid-stack index