---
name: "OpenAI Codex CLI"
description: "Fleet skill: OpenAI Codex CLI — software inventory and operations reference"
version: "1.0.0"
author: "skynet"
category: "fleet"
agents: ["claude-code", "codex", "gemini", "kimi"]
tags: ["software-codex", "fleet", "fleet", "software"]
---

# 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.