Codez

English | 简体中文

Codez is a minimal, upstream-compatible fork of the OpenAI Codex CLI. It keeps Codex internals and local data formats intact while exposing the product as codez.

Codez tracks upstream Codex releases and publishes unsigned packages for macOS Apple Silicon and Linux x86_64/ARM64.

Install

curl -fsSL https://github.com/streamsc/codez/releases/latest/download/install-codez.sh | sh
codez

The installer detects the current platform and downloads one of these release packages:

• codez-package-aarch64-apple-darwin.tar.gz
• codez-package-x86_64-unknown-linux-musl.tar.gz
• codez-package-aarch64-unknown-linux-musl.tar.gz

The installer accepts the existing Codex environment controls:

• CODEX_HOME selects the shared configuration and session directory (default ~/.codex).
• CODEX_INSTALL_DIR selects the public command directory (default ~/.local/bin).
• CODEX_RELEASE pins a release such as codez-v0.144.4-r1.

Offline install

Each Codez release also publishes a multi-platform offline bundle. Copy codez-offline-vX.Y.Z-rN.tar.gz and codez-offline-bundle_SHA256SUMS to the offline machine, verify the outer bundle checksum, and extract the bundle:

if command -v sha256sum >/dev/null 2>&1; then
  sha256sum -c codez-offline-bundle_SHA256SUMS
else
  shasum -a 256 -c codez-offline-bundle_SHA256SUMS
fi
tar -xzf codez-offline-v0.144.4-r8.tar.gz
./codez-offline-v0.144.4-r8/install-codez-offline.sh \
  --bundle ./codez-offline-v0.144.4-r8

The offline installer selects the matching macOS Apple Silicon, Linux x86_64, or Linux ARM64 package, verifies its bundled SHA-256 entry, and installs it without contacting GitHub. It accepts the same CODEX_HOME and CODEX_INSTALL_DIR environment variables as the online installer.

Codex compatibility and coexistence

Codez intentionally shares these Codex surfaces:

• CODEX_HOME and .codex
• authentication and keyring entries
• configuration, rollout sessions, memories, skills, plugins and SQLite state
• internal crates, protocols, model identity and CODEX_* environment variables

Coexistence-sensitive files are isolated:

• packages: $CODEX_HOME/packages/codez/
• update metadata: $CODEX_HOME/codez/version.json
• logs: codez-tui.log and codez-login.log
• app-server daemon socket, PID and lock directories use codez-* names

The main process is named codez. Code Mode may start a child named codex-code-mode-host; that helper keeps its upstream name and stays beside the real Codez binary inside the private Codez release directory. It is not linked into the public PATH, so an installed Codex helper is not overwritten.

Development

The main branch is reserved for upstream tracking. Product changes live on the codez branch, which should be the repository default branch.

The internal Cargo binary target remains codex:

cd codex-rs
cargo build --bin codex --bin codex-code-mode-host

Build the Codez package layout by selecting the Codez package variant:

CODEZ_VERSION=0.144.4-r1 python3 scripts/build_codex_package.py \
  --variant codez \
  --target aarch64-apple-darwin \
  --cargo-profile release \
  --package-dir dist/codez-package \
  --archive-output dist/codez-package-aarch64-apple-darwin.tar.gz

Linux releases use musl and include a bundled bwrap. Build bwrap first, finalize its bytes, and pass its digest into the Codez build:

TARGET=x86_64-unknown-linux-musl
cd codex-rs
cargo build --target "$TARGET" --release --bin bwrap
strip --strip-debug --strip-unneeded "target/$TARGET/release/bwrap"
export CODEX_BWRAP_SHA256="$(sha256sum "target/$TARGET/release/bwrap" | awk '{print $1}')"
cd ..
CODEZ_VERSION=0.144.4-r1 python3 scripts/build_codex_package.py \
  --variant codez \
  --target "$TARGET" \
  --cargo-profile release \
  --bwrap-bin "codex-rs/target/$TARGET/release/bwrap" \
  --package-dir "dist/codez-package-$TARGET" \
  --archive-output "dist/codez-package-$TARGET.tar.gz"

Tags use codez-v<upstream-version>-r<N>, for example codez-v0.144.4-r1. The release workflow builds all three platform archives, publishes one checksum manifest, and caches Cargo dependencies and compiler outputs between runs. The scheduled upstream workflow detects stable rust-vX.Y.Z tags and opens a review PR without auto-merging.

Upstream documentation

Codez keeps Codex configuration and behavior compatible, so the Codex documentation remains the primary usage reference.

This repository is licensed under the Apache-2.0 License.