OpenAI Codex CLI

--- name: software-codex description: Use this skill to manage and interact with the OpenAI Codex CLI across the skynet fleet. Ideal for automated code generation, refactoring, and large-scale repository analysis using GPT-5 models. metadata: author: skynet version: 1.0.0 --- # OpenAI Codex CLI The `codex` CLI is a specialized agentic interface for OpenAI's code-centric models. It is the primary tool for headless operations, batch refactoring, and fleet-wide code synthesis across the skynet network. ## Fleet Deployment & Versions The tool is distributed across core fleet machines with specific versioning. Note that older versions (0.114.0) may lack support for newer GPT-5.4 specific flags or the full 400K context window. | Machine | Host | Version | Role | |---------|------|---------|------| | **Workstation** | 192.168.86.22 | 0.117.0 | Development Master | | **Spark** | 192.168.86.48 | 0.116.0 | Inference/Batch Hub | | **Bots Mac** | 192.168.86.50 | 0.116.0 | Agent Hosting | | **Jarvis Mac** | 192.168.86.51 | 0.114.0 | Legacy Support | | **Dev1** | (Remote) | 0.114.0 | Remote Development | | **Vault** | 192.168.86.27 | - | **NOT INSTALLED** (Auth Source Only) | | **Dev Server** | 192.168.86.33 | - | **NOT INSTALLED** | ## Core Configuration ### Authentication Credentials must be synced from the **Vault** machine. Do not store keys in plaintext outside of the auth file. - **Location:** `~/.codex/auth.json` - **Primary Key:** `OPENAI_API_KEY` - **Sync Command:** `ssh vault 'cat ~/keys/openai.key' > ~/.codex/auth.json` ### Runtime Config Global behavior is defined in TOML format. - **Location:** `~/.codex/config.toml` - **Recommended Defaults:** - `model = "gpt-5.4"` - `max_context = 400000` - `temperature = 0.2` (Set low for deterministic code output) ## Key Commands & Usage ### Interactive Mode Launch with just `codex`. Use this for exploratory coding, debugging prompts, or quick iterative fixes where manual intervention is required. ### Headless/Print Mode The standard mode for all scripts and agent-driven tasks. - `codex -p`: **Print Mode**. Takes input from STDIN, outputs response to STDOUT. - `codex -p "Instruction" < file.py`: Processes the file and prints the modified code. ### Critical Flags - `-m, --model`: Override the default model (e.g., `gpt-5.4`, `gpt-5.3`, `gpt-5.2`). - `-c, --context`: Adjust the context window limit (max 400,000 tokens). - `--json`: Output result as a JSON object, useful for `fleet-build.py` and other automation scripts. ## Supported Models | Model | Context | Description | |-------|---------|-------------| | **gpt-5.4** | 400K | State-of-the-art for reasoning and complex architecture. | | **gpt-5.3** | 400K | Balanced speed and logic; standard for unit test generation. | | **gpt-5.2** | 400K | Low-latency; best for docstrings and minor syntax fixes. | ## Common Workflows ### 1. Recursive Code Refactoring Process all files in a directory and update them in-place using a pipe: ```bash for f in src/**/*.ts; do cat "$f" | codex -p "Refactor to use functional components" > "$f.tmp" && mv "$f.tmp" "$f" done ``` ### 2. Full-Repo Context Loading Leverage the massive 400K window to feed entire modules for global architectural analysis: ```bash cat src/*.py | codex -p "Identify potential race conditions in this module" ``` ### 3. Fleet Batch Execution Utilize the local scripts in `~/dev/projects/skills/scripts` to distribute heavy tasks: - `fleet-build.py`: Parallelizes Codex tasks across Workstation, Spark, and Bots. - `generate-missing.py`: Scans for `TODO` comments and fills them using `gpt-5.4`. ## Troubleshooting ### 'Command Not Found' Ensure `~/.local/bin` or the installation path is in your `PATH`. On macOS machines (**Bots/Jarvis**), ensure your `.zshrc` is correctly sourced before calling `codex` via SSH. ### Auth Failures (401) Verify that `~/.codex/auth.json` exists and the `OPENAI_API_KEY` hasn't rotated. Re-sync from the **Vault** if necessary. ### Rate Limiting (429) When running `fleet-batch.json` across multiple machines, you may hit global API rate limits. Use the `fleet-build.sh` wrapper which implements exponential backoff. ### Version Constraints (v0.114.0) Older versions on **Jarvis** and **Dev1** may not support the `--json` flag or may have lower default context limits. Explicitly pass `-c 400000` to force high-context mode if supported. ## Fleet Best Practices - **Prefer Spark for Heavy Lifting:** Use **DGX Spark** (192.168.86.48) for long-running batch jobs to keep the Workstation responsive. - **Verification:** Always follow a `codex` operation with a validation step (e.g., `npm test` or `pytest`). - **No Auto-Commit:** Never allow the CLI to commit directly to git. Always review changes via `git diff` before finalizing. - **Pipe for Consistency:** Prefer piping data (`cat file | codex -p`) over providing file paths to ensure consistent STDIN/STDOUT handling in shell scripts.