Agent IDE — Codex fork for AI-native development environment
d9c014efce
https://github.com/openai/codex/pull/11318 introduced logic to publish platform artifacts as separate npm packages (for example, `@openai/codex-darwin-arm64`, `@openai/codex-linux-x64`, etc.). That requires provisioning and maintaining multiple package entries in npm, which we want to avoid. We still need to keep the package-size mitigation (platform-specific payloads), but we want that layout to live under a single npm package namespace (`@openai/codex`) using dist-tags. We also need to preserve pre-release workflows where users install `@openai/codex@alpha` and get platform-appropriate binaries. Additionally, we want GitHub Release assets to group Codex npm tarballs together, so platform tarballs should follow the same `codex-npm-*` filename prefix as the main Codex tarball. ## Release Strategy (New Scheme) We publish **one npm package name for Codex binaries** (`@openai/codex`) and use **dist-tags** to select platform-specific payloads. This avoids creating separate platform package names while keeping the package size split by platform. ### What gets published #### Mainline release (`x.y.z`) - `@openai/codex@latest` (meta package) - `@openai/codex@darwin-arm64` - `@openai/codex@darwin-x64` - `@openai/codex@linux-arm64` - `@openai/codex@linux-x64` - `@openai/codex@win32-arm64` - `@openai/codex@win32-x64` - `@openai/codex-responses-api-proxy@latest` - `@openai/codex-sdk@latest` #### Alpha release (`x.y.z-alpha.N`) - `@openai/codex@alpha` (meta package) - `@openai/codex@alpha-darwin-arm64` - `@openai/codex@alpha-darwin-x64` - `@openai/codex@alpha-linux-arm64` - `@openai/codex@alpha-linux-x64` - `@openai/codex@alpha-win32-arm64` - `@openai/codex@alpha-win32-x64` - `@openai/codex-responses-api-proxy@alpha` - `@openai/codex-sdk@alpha` As an example, the `package.json` for `@openai/codex@alpha` (using `0.99.0-alpha.17` as the `version`) would be: ``` { "name": "@openai/codex", "version": "0.99.0-alpha.17", "license": "Apache-2.0", "bin": { "codex": "bin/codex.js" }, "type": "module", "engines": { "node": ">=16" }, "files": [ "bin" ], "repository": { "type": "git", "url": "git+https://github.com/openai/codex.git", "directory": "codex-cli" }, "packageManager": "pnpm@10.28.2+sha512.41872f037ad22f7348e3b1debbaf7e867cfd448f2726d9cf74c08f19507c31d2c8e7a11525b983febc2df640b5438dee6023ebb1f84ed43cc2d654d2bc326264", "optionalDependencies": { "@openai/codex-linux-x64": "npm:@openai/codex@0.99.0-alpha.17-linux-x64", "@openai/codex-linux-arm64": "npm:@openai/codex@0.99.0-alpha.17-linux-arm64", "@openai/codex-darwin-x64": "npm:@openai/codex@0.99.0-alpha.17-darwin-x64", "@openai/codex-darwin-arm64": "npm:@openai/codex@0.99.0-alpha.17-darwin-arm64", "@openai/codex-win32-x64": "npm:@openai/codex@0.99.0-alpha.17-win32-x64", "@openai/codex-win32-arm64": "npm:@openai/codex@0.99.0-alpha.17-win32-arm64" } } ``` Note that the keys in `optionalDependencies` have "clean" names, but the values have the tag embedded. ### Important note **Note:** Because we never created the new platform package names on npm (for example, `@openai/codex-darwin-arm64`) since #11318 landed, there are no extra npm packages to clean up. ## What changed ### 1. Stage platform tarballs as `@openai/codex` with platform-specific versions File: `codex-cli/scripts/build_npm_package.py` - Added `CODEX_NPM_NAME = "@openai/codex"` and platform metadata `npm_tag` values: - `darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64`, `win32-arm64`, `win32-x64` - For platform package staging (`codex-<platform>` inputs), switched generated `package.json` from: - `name = @openai/codex-<platform>` to: - `name = @openai/codex` - Added `compute_platform_package_version(version, platform_tag)` so platform tarballs have unique versions (`<release-version>-<platform-tag>`), which is required because npm forbids re-publishing the same `name@version`. ### 2. Point meta package optional dependencies at dist-tags on `@openai/codex` File: `codex-cli/scripts/build_npm_package.py` - Updated `optionalDependencies` generation for the main `codex` package to use npm alias syntax: - key remains alias package name (for example, `@openai/codex-darwin-arm64`) so runtime lookup behavior is unchanged - value now resolves to `@openai/codex` by dist-tag - Stable releases emit tags like `npm:@openai/codex@darwin-arm64`. - Alpha releases (`x.y.z-alpha.N`) emit tags like `npm:@openai/codex@alpha-darwin-arm64`. ### 3. Publish with per-tarball dist-tags in release CI File: `.github/workflows/rust-release.yml` - Reworked npm publish logic to derive the publish tag per tarball filename: - platform tarballs publish with `<platform>` tags for stable releases - platform tarballs publish with `alpha-<platform>` tags for alpha releases - top-level tarballs (`codex`, `codex-responses-api-proxy`, `codex-sdk`) continue using the existing channel tag policy (`latest` implicit for stable, `alpha` for alpha) - Added fail-fast behavior for unexpected tarball names to avoid silent mispublishes. ### 4. Normalize Codex platform tarball filenames for GitHub Release grouping Files: `scripts/stage_npm_packages.py`, `.github/workflows/rust-release.yml` - Renamed staged platform tarball filenames from: - `codex-linux-<arch>-npm-<version>.tgz` - `codex-darwin-<arch>-npm-<version>.tgz` - `codex-win32-<arch>-npm-<version>.tgz` - To: - `codex-npm-linux-<arch>-<version>.tgz` - `codex-npm-darwin-<arch>-<version>.tgz` - `codex-npm-win32-<arch>-<version>.tgz` This keeps all Codex npm artifacts grouped under a common `codex-npm-` prefix in GitHub Releases. ### 5. Documentation update File: `codex-cli/scripts/README.md` - Updated staging docs to clarify that platform-native variants are published as dist-tagged `@openai/codex` artifacts rather than separate npm package names. ## Resulting behavior - Mainline release: - `@openai/codex@latest` resolves the meta package - meta package optional dependencies resolve `@openai/codex@<platform-tag>` - Alpha release: - users can continue installing `@openai/codex@alpha` - alpha meta package optional dependencies resolve `@openai/codex@alpha-<platform-tag>` - Release assets: - Codex npm tarballs share `codex-npm-` prefix for cleaner grouping in GitHub Releases This preserves platform-specific payload distribution while avoiding separate npm package names and improves release-asset discoverability. ## Validation notes - Verified staged `package.json` output for stable and alpha meta packages includes expected alias targets. - Verified staged platform package manifests are `name=@openai/codex` with unique platform-suffixed versions. - Verified publish tag derivation maps renamed platform tarballs to expected stable and alpha dist-tags. |
||
|---|---|---|
| .devcontainer | ||
| .github | ||
| .vscode | ||
| codex-cli | ||
| codex-rs | ||
| docs | ||
| patches | ||
| scripts | ||
| sdk/typescript | ||
| shell-tool-mcp | ||
| third_party/wezterm | ||
| .bazelignore | ||
| .bazelrc | ||
| .bazelversion | ||
| .codespellignore | ||
| .codespellrc | ||
| .gitignore | ||
| .markdownlint-cli2.yaml | ||
| .npmrc | ||
| .prettierignore | ||
| .prettierrc.toml | ||
| AGENTS.md | ||
| announcement_tip.toml | ||
| BUILD.bazel | ||
| CHANGELOG.md | ||
| cliff.toml | ||
| defs.bzl | ||
| flake.lock | ||
| flake.nix | ||
| justfile | ||
| LICENSE | ||
| MODULE.bazel | ||
| MODULE.bazel.lock | ||
| NOTICE | ||
| package.json | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| rbe.bzl | ||
| README.md | ||
npm i -g @openai/codex
or brew install --cask codex
Codex CLI is a coding agent from OpenAI that runs locally on your computer.
If you want Codex in your code editor (VS Code, Cursor, Windsurf), install in your IDE.
If you are looking for the cloud-based agent from OpenAI, Codex Web, go to chatgpt.com/codex.
Quickstart
Installing and running Codex CLI
Install globally with your preferred package manager:
# Install using npm
npm install -g @openai/codex
# Install using Homebrew
brew install --cask codex
Then simply run codex to get started.
You can also go to the latest GitHub Release and download the appropriate binary for your platform.
Each GitHub Release contains many executables, but in practice, you likely want one of these:
- macOS
- Apple Silicon/arm64:
codex-aarch64-apple-darwin.tar.gz - x86_64 (older Mac hardware):
codex-x86_64-apple-darwin.tar.gz
- Apple Silicon/arm64:
- Linux
- x86_64:
codex-x86_64-unknown-linux-musl.tar.gz - arm64:
codex-aarch64-unknown-linux-musl.tar.gz
- x86_64:
Each archive contains a single entry with the platform baked into the name (e.g., codex-x86_64-unknown-linux-musl), so you likely want to rename it to codex after extracting it.
Using Codex with your ChatGPT plan
Run codex and select Sign in with ChatGPT. We recommend signing into your ChatGPT account to use Codex as part of your Plus, Pro, Team, Edu, or Enterprise plan. Learn more about what's included in your ChatGPT plan.
You can also use Codex with an API key, but this requires additional setup.
Docs
This repository is licensed under the Apache-2.0 License.