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-musloraarch64-unknown-linux-musland@openai/codex-linux-*. - macOS x64/arm64 use
x86_64-apple-darwinoraarch64-apple-darwinand@openai/codex-darwin-*. - Windows x64/arm64 use
x86_64-pc-windows-msvcoraarch64-pc-windows-msvcand@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/**:
- codex-cli/package.json: source metadata for the
@openai/codexmeta package andcodexbin. - codex-cli/…/codex.js: installed npm executable; resolves platform payloads, sets package-manager handoff env, and launches the Rust CLI.
- codex-cli/…/build_npm_package.py: package-specific staging/packing for the meta package, platform native packages, responses proxy package, and TypeScript SDK package.
- codex-cli/…/README.md: release operator notes for npm staging and native artifact handling.
- codex-cli/…/test_build_npm_package.py: Python archive-content regression tests for native npm packages.
- codex-cli/…/exit-status.test.mjs: Node wrapper process/signal/exit regression tests.
- codex-cli/…/run_in_container.sh and codex-cli/…/init_firewall.sh: Docker/firewall helper flow for running Codex in a restricted container.
codex-cli/.gitignore: excludes generated localvendor/payloads.
Coupling
- If codex-cli/…/codex.js changes the platform-to-target mapping or optional dependency names, update
CODEX_PLATFORM_PACKAGESin 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 andcopy_native_binaries()in codex-cli/…/build_npm_package.py; the launcher hard-codesvendor/<target>/bin/codex(.exe), while packaging stripsbin/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, andpackageManager, then overrideversion,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 theCODEX_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
execveand 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, orrg; codex-cli/…/test_build_npm_package.py guards that the rest of the vendor tree is byte-preserved.