Windows global installs expose codex as codex.cmd; spawning 'codex' without shell hits ENOENT.
Enable shell to align with Claude's Windows behavior and resolve PATH lookup.
Shell spawn makes cmd.exe strip TOML double quotes in -c arrays, so args become a string.
Switch mcp args to TOML literal (single-quoted) arrays to preserve types; update tests.
Implements MCP server configuration and developer instructions support in
Codex local mode, bringing it to parity with remote mode.
Key additions:
- buildMcpServerConfigArgs() and buildDeveloperInstructionsArg() utilities
to construct -c config arguments for passing MCP servers and instructions
to the Codex CLI at runtime
- TITLE_INSTRUCTION for Codex to call hapi__change_title to update chat
session titles dynamically
- Codex local mode now starts hapi MCP bridge server and passes both MCP
configuration and developer instructions to Claude, enabling full feature
parity with remote mode
Files changed:
- New: codexMcpConfig.ts (utilities), systemPrompt.ts (prompt definition),
codexMcpConfig.test.ts (comprehensive tests)
- Updated: codexLocal.ts (accepts mcpServers, builds config args),
codexLocalLauncher.ts (starts hapi server, passes config),
codexStartConfig.ts (imports TITLE_INSTRUCTION)
Consolidate process lifecycle management (kill, check alive) into a new
utility module with proper Windows/Unix handling, replacing scattered
process.kill() calls with consistent async APIs.
Add checks to gracefully handle abort signals:
- Check if abort is already signaled before attempting spawn
- Check if abort caused the spawn error instead of rejecting
Added helpful error messages with cause preservation when spawning codex, gemini, or other CLI tools fails because the binary is not found in PATH. This follows the existing error handling pattern from claudeLocal.ts.
Collect unknown CLI arguments from index.ts and pass them through the execution chain (runCodex → loop → CodexSession → codexLocalLauncher → codexLocal), similar to how claude already works. This enables users to pass CLI arguments like --model and --sandbox to the underlying codex process.
Filter out the 'resume' subcommand which is managed internally by hapi, while allowing other CLI arguments to pass through. Add warning log in remote mode when CLI args are ignored since remote mode uses message-based configuration instead. Include unit tests for the resume filtering logic.
Extracts duplicated exit/switch confirmation handling from CodexDisplay and RemoteModeDisplay into a custom useSwitchControls hook. Centralizes terminal state restoration (raw mode, keyboard protocol cleanup) into a restoreTerminalState utility function used across codex modules. Improves code reusability and maintainability.
Reorganized runCodex.ts to improve maintainability by extracting:
- CodexSession class for session lifecycle management
- CodexLocalLauncher and CodexRemoteLauncher for mode-specific initialization
- CodexEventConverter for MCP message handling and UI buffer updates
- CodexSessionScanner for resume file discovery
- emitReadyIfIdle utility for ready event emission
Added codexSessionId field to metadata schema for session tracking.
Updated UI components to work with refactored architecture.
weishu