Introducing a new way to review your PRs.

Read the announcement

openai / codex

Lightweight coding agent that runs in your terminal

View on GitHub

13 documents · Updated Nov 16, 2026

docs / codex-cli-npm-launcher

Codex CLI npm launcher

Overview

codex-cli/ is the npm distribution wrapper for the Rust Codex CLI. The published meta package is declared in codex-cli/package.json as @openai/codex, exposes the codex bin at bin/codex.js, uses ESM ("type": "module"), requires Node >=16, and normally only publishes bin/codex.js from the source package. Release staging rewrites that package into a lightweight launcher plus platform optional dependencies.

The runtime entry point is codex-cli/…/codex.js. It maps Node's process.platform/process.arch to one of six Rust target triples and then to a platform package alias:

  • Linux x64/arm64 and Android x64/arm64 use x86_64-unknown-linux-musl or aarch64-unknown-linux-musl and @openai/codex-linux-*.
  • macOS x64/arm64 use x86_64-apple-darwin or aarch64-apple-darwin and @openai/codex-darwin-*.
  • Windows x64/arm64 use x86_64-pc-windows-msvc or aarch64-pc-windows-msvc and @openai/codex-win32-*.

codex-cli/…/codex.js first tries to resolve the installed platform package's package.json with createRequire() and looks for vendor/<target>/bin/codex or codex.exe under that package. If the optional dependency cannot be resolved, it falls back to codex-cli/vendor/ so staged/debug installs can run from a local hydrated vendor tree. Unsupported platform/CPU pairs throw immediately; a missing native binary throws a reinstall hint tailored by package-manager detection.

Package-manager detection in codex-cli/…/codex.js is used for two things: user-facing reinstall commands and environment handoff to the Rust CLI. It searches ancestors of both the real package root and lexical entrypoint for pnpm .modules.yaml ownership, Vite+ packages/…/codex.json metadata, and then checks Bun/npm environment hints. Before launching the native binary it sets CODEX_MANAGED_PACKAGE_ROOT to the canonical @openai/codex root, clears any previous CODEX_MANAGED_BY_* variables, and sets exactly one of CODEX_MANAGED_BY_NPM, CODEX_MANAGED_BY_BUN, CODEX_MANAGED_BY_PNPM, or CODEX_MANAGED_BY_VITE_PLUS.

On Unix with a Node runtime that exposes process.execve, codex-cli/…/codex.js replaces the Node wrapper with the native Rust CLI so signals and exit status come directly from the binary. Before execve, it installs a SIGXFSZ handler so ignored Node signal disposition does not leak into the Rust process. On Windows and older Node versions it falls back to child_process.spawn() with inherited stdio, forwards SIGINT, SIGTERM, and SIGHUP to the child, and mirrors either the numeric exit code or signal termination back to the shell.

Packaging is handled by codex-cli/…/build_npm_package.py. For --package codex, it copies codex-cli/…/codex.js, optionally copies the repo README.md, loads codex-cli/package.json, writes the release version, forces files to ['bin/codex.js'], and injects optionalDependencies that alias each platform package name to npm:@openai/codex@<version>-<platform-tag>. For platform packages such as codex-linux-x64, it writes a package named @openai/codex with unique version suffixes like <version>-linux-x64, OS/CPU constraints, files: ['vendor'], and copied engine/package-manager metadata. Those platform packages require --vendor-src; copy_native_binaries() copies only the requested target's hydrated vendor/<target> tree, removes standalone codex-exec-server/.exe, and removes the execServer entry from codex-package.json while leaving the normal codex exec-server path available through the main CLI. run_npm_pack() packs staged contents in an isolated npm cache/log directory and moves the tarball to --pack-output.

codex-cli/…/README.md documents the preferred release flow: use the repo-level scripts/stage_npm_packages.py helper to stage codex, codex-responses-api-proxy, and codex-sdk tarballs under dist/npm/. That helper imports constants from codex-cli/…/build_npm_package.py, downloads or reuses Rust release artifacts, hydrates vendor/, expands --package codex into the meta package plus all platform variants, and then calls build_npm_package.py for each staged package. Direct build_npm_package.py usage is intended for package-specific debugging with an already-hydrated --vendor-src.

Tests under codex-cli/tests/ focus on the wrapper's two fragile responsibilities. codex-cli/…/test_build_npm_package.py fabricates target-specific vendor trees, runs build_npm_package.py for every platform package, opens the generated tarballs, and asserts that all CLI/runtime support files are preserved while the standalone executor binary and execServer manifest entry are removed from the npm copy. codex-cli/…/exit-status.test.mjs installs a temporary wrapper around a local vendor symlink and verifies that the spawn fallback forwards repeated signals, preserves numeric CLI argument errors, uses execve when available, and reports child signals correctly. It requires CODEX_TEST_BINARY for the real CLI exit/signal checks.

The remaining codex-cli/scripts/ files are legacy/container helpers rather than npm release logic. codex-cli/…/run_in_container.sh starts a Docker container from an image named codex, mounts the requested work directory, writes allowed domains from OPENAI_ALLOWED_DOMAINS, runs init_firewall.sh, and then invokes codex --sandbox workspace-write --ask-for-approval on-request ... inside the container. codex-cli/…/init_firewall.sh configures iptables/ipset inside that container, allowing DNS, localhost, the host subnet, and resolved allowed domains, then rejects other TCP/UDP traffic and verifies example.com is blocked while api.openai.com is reachable. codex-cli/.gitignore ignores /vendor/, matching the fact that hydrated native payloads are generated or downloaded, not committed.

Path routing for codex-cli/**:

Coupling

  • If codex-cli/…/codex.js changes the platform-to-target mapping or optional dependency names, update CODEX_PLATFORM_PACKAGES in codex-cli/…/build_npm_package.py at the same time; the release script emits the packages that the runtime later tries to resolve.
  • If the Rust release artifact layout under vendor/<target>/ changes, verify both codex-cli/…/codex.js and copy_native_binaries() in codex-cli/…/build_npm_package.py; the launcher hard-codes vendor/<target>/bin/codex(.exe), while packaging strips bin/codex-exec-server(.exe) and edits codex-package.json.
  • If npm package metadata in codex-cli/package.json changes, check the staging rewrite in codex-cli/…/build_npm_package.py; the meta package and platform package paths selectively copy license, repository, engines, and packageManager, then override version, files, and optional dependencies.
  • If pnpm, Bun, npm, or Vite+ global install layouts change, verify detectPackageManager() in codex-cli/…/codex.js; its result controls both reinstall guidance and the CODEX_MANAGED_BY_* environment seen by the Rust CLI.
  • If release orchestration changes in the repo-level staging helper, keep codex-cli/…/README.md and exported constants in codex-cli/…/build_npm_package.py aligned; the helper imports those constants instead of duplicating package expansion and native-component metadata.

Risks

  • codex-cli/…/codex.js signal handling is easy to regress because behavior differs between execve and spawn fallback. If forwarding or exit mirroring changes, shells may see success for a signal-killed CLI or a second termination signal may not reach the Rust process; codex-cli/…/exit-status.test.mjs covers these cases.
  • codex-cli/…/build_npm_package.py intentionally removes only the standalone executor from npm native packages. If the strip list or manifest edit is broadened, npm packages can lose runtime helpers such as codex-code-mode-host, sandbox resources, or rg; codex-cli/…/test_build_npm_package.py guards that the rest of the vendor tree is byte-preserved.