codex-windows — Windows-Optimized Codex CLI

Unofficial fork.

This project is not supported by OpenAI. Use at your own risk.

Goal: Windows compatibility & releases that closely track upstream.

Maintained by @cpjet64.
Real life comes first; this is not a job.

---

# Install (Node.js ≥ 22 required)
npm install -g @cpjet64/codex-windows

# Launch
codex-windows
codex-windows --version

Already have @openai/codex installed? Both CLIs share ~/.codex/config.toml and can be used side-by-side.

---

Support Matrix

OS	Arch	Status	Notes
Windows 10/11	x64	Supported	Primary target
Windows 10/11	ARM64	Supported	Secondary target
macOS/Linux	—	Unsupported	Use official Codex

---

Installation

Option 1 – npm (Recommended)

You need Node.js 22 LTS or newer to install and run Codex-Windows via npm.

npm install -g @cpjet64/codex-windows

Need Node.js? Install Node 22 LTS (ensure "Add to PATH" is checked) or use nvm-windows:

nvm install 22
nvm use 22

Verify installation:

node --version
npm --version

---

Option 2 – Manual (ZIP)

If you can't or don't want to use npm:

1. Download the proper ZIP from Releases.
2. Extract codex-windows.exe.
3. Add its folder to your PATH.

---

Security & Integrity

When installing manually, always verify the hash:

$asset="codex-windows-x86_64-pc-windows-msvc.exe.zip"
$expected="<paste SHA256>"
(Get-FileHash $asset -Algorithm SHA256).Hash -eq $expected

PowerShell may block scripts:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

---

Corporate Proxy Setup

$env:HTTPS_PROXY="http://proxy.corp:8080"
$env:NO_PROXY="localhost,127.0.0.1"
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY","<your key>","User")

---

Usage

codex-windows                # Launch
codex-windows --help
codex-windows --version

Using beside the official Codex

npm install -g @openai/codex @cpjet64/codex-windows
codex --version
codex-windows --version

Both share the same configuration (~/.codex/config.toml) and authentication.

---

VS Code Integration

Set the ChatGPT: CLI Executable path in VS Code:

{
  "chatgpt.cliExecutable": "C:\\Users\\%USERNAME%\\AppData\\Roaming\\npm\\codex-windows.cmd"
}

Find your path quickly:

Get-Command codex-windows

Typical locations:

Method	Path
npm	%AppData%\npm\codex-windows.cmd
nvm-windows	C:\nvm4w\nodejs\codex-windows.ps1
Volta	%LocalAppData%\Volta\bin\codex-windows.cmd
Manual	custom .exe location

Use .cmd for cmd.exe, .ps1 for PowerShell, or .exe if installed manually. Restart VS Code after editing settings.json.

---

Troubleshooting (Windows)

Symptom	Fix
Command not found	Add %AppData%\npm (or your Node bin path) to PATH.
PowerShell blocks .ps1	Set-ExecutionPolicy RemoteSigned -Scope CurrentUser.
Proxy required	Set HTTPS_PROXY / HTTP_PROXY.
Antivirus flagged EXE	Right-click → Properties → Unblock or whitelist folder.
Both CLIs installed, wrong one runs	Adjust PATH order.

Uninstall:

npm uninstall -g @cpjet64/codex-windows

---

Authentication

Run once:

codex-windows

Then sign in with ChatGPT or provide an OPENAI_API_KEY. Auth is shared with official Codex.

---

Documentation

All official Codex docs apply:

• Getting Started
• Sandbox & Approvals
• Authentication
• Configuration
• MCP
• FAQ

Windows maintainers: see WINDOWS_RELEASE_GUIDE.md.

---

Reporting Issues

Windows-specific issues:

1. File in Official Codex Issues
2. Cross-reference in Codex-Windows Issues
3. Include the official issue link in your fork issue

We prioritize Windows-specific issues with official cross-references.

macOS/Linux issues: Report only to Official Codex.

---

Contributing

• Submit fixes to both repos:

  • openai/codex
  • cpjet64/codex-windows

• Branch from upstream/main, test on Windows, and cross-reference PRs.

• Feature work is accepted only if it benefits Windows users and doesn't break parity.

Maintainers: follow WINDOWS_RELEASE_GUIDE.md for automation and hotfix flow.

---

Versioning

Upstream	Windows Fork	Notes
0.46.0	0.46.0-win.1	Initial Windows build
0.46.0	0.46.0-win.2	Hotfix
0.46.1	0.46.1-win.1	Next upstream

Suffix -win.N → Windows release iteration.

---

Automated Releases

• Detects new OpenAI tags hourly.
• Rebases Windows overlay automatically.
• Builds x64 + ARM64 binaries.
• Publishes to GitHub Releases + npm.

When merges conflict, manual resolution is required.

Example test:

gh workflow run simulate-windows-release.yml \
  -f version=0.46.0-test1 \
  -f upstream_ref=rust-v0.46.0 \
  -f dry_run=true

---

Relationship to Official Codex

• Rebases directly on upstream releases.
• Submits Windows fixes back to OpenAI (acceptance not guaranteed).
• Maintains configuration and feature parity.

Use codex-windows if you're on Windows 10/11 or need fixes fast. Use official Codex for macOS/Linux or official support.

---

Links

• Repo: https://github.com/cpjet64/codex-windows
• npm: https://www.npmjs.com/package/@cpjet64/codex-windows
• Releases: https://github.com/cpjet64/codex-windows/releases
• Official Codex: https://github.com/openai/codex

---

License

Apache-2.0 — same as upstream Codex.

---

Acknowledgments

Thanks to the OpenAI Codex team for the original CLI and ongoing innovation.