OpenAI Codex is a open source CLI released with OpenAI o3/o4-mini to be a "chat-driven development" tool. It allows developers to use AI models via API directly in their terminal to perform coding tasks. Unlike a simple chatbot, it can read files, write files (via patches), execute shell commands (often sandboxed), and iterate based on the results and user feedback.
\nNote: This overview was generated with Gemini 2.5 Pro and updated collaboratively iterated on with Gemini 2.5 Pro and myself.
\nink and react, offering a richer experience than plain text. Key components reside in src/components/, particularly within src/components/chat/.src/cli.tsx (using meow for argument parsing), which sets up the main TerminalChat component via src/app.tsx.TerminalChat manages the overall display including history, input prompts, loading states, and overlays.TerminalChatInput (or TerminalChatNewInput), supporting command history and slash commands.TerminalMessageHistory, using components like TerminalChatResponseItem to render different message types.src/utils/agent/agent-loop.ts.AgentLoop class manages the interaction cycle with the OpenAI API.openai Node.js library (v4+) and specifically calls openai.responses.create, indicating use of the /responses endpoint which supports streaming and tool use.AgentLoop sends the context (history, instructions, user input) to the specified model (default o4-mini, configurable via --model or config file).message, function_call, function_call_output, reasoning).src/utils/model-utils.ts handles fetching available models and checking compatibility.shell (or container.exec), allowing the model to request shell command execution. See the tools array in src/utils/agent/agent-loop.ts.function_call for shell, the AgentLoop invokes handleExecCommand (src/utils/agent/handle-exec-command.ts).suggest, auto-edit, full-auto).src/approvals.ts (canAutoApprove) determines if the command is known-safe or needs user confirmation based on the policy.TerminalChatCommandReview) prompts the user.src/utils/agent/exec.ts.handleExecCommand decides how to run the command based on the approval policy and safety assessment.full-auto mode implies sandboxing.src/utils/agent/sandbox/ contains the sandboxing implementations:\nmacos-seatbelt.ts: Uses macOS's sandbox-exec to restrict file system access and block network calls (READ_ONLY_SEATBELT_POLICY). Writable paths are whitelisted.raw-exec.ts: Executes commands directly without sandboxing (used when sandboxing isn't needed or available).README.md, Dockerfile, and scripts/ indicate a Docker-based approach. The CLI runs inside a minimal container where scripts/init_firewall.sh uses iptables/ipset to restrict network access only to the OpenAI API. The user's project directory is mounted into the container.apply_patch)src/utils/agent/agent-loop.ts) to use a specific format like {"cmd":["apply_patch","*** Begin Patch..."]} when it wants to edit files.handleExecCommand detects this pattern.apply_patch as a shell command, it uses execApplyPatch (src/utils/agent/exec.ts), which calls process_patch from src/utils/agent/apply-patch.ts.src/utils/agent/apply-patch.ts parses the patch format and uses Node.js fs calls to modify files directly on the host system (or within the container on Linux).parse-apply-patch.ts (likely used by the UI) helps render diffs for user review.prefix within src/utils/agent/agent-loop.ts. This tells the model about its role as the Codex CLI, its capabilities (shell, patching), constraints (sandboxing), and coding guidelines.~/.codex/instructions.md) and project-specific (codex.md or similar, discovered via logic in src/utils/config.ts) files. These combined instructions are prepended to the conversation history sent to the model.items array (containing ResponseItem objects like user messages, assistant messages, tool calls, tool outputs) is passed back to the model on each turn, providing conversational context. src/utils/approximate-tokens-used.ts estimates context window usage.cat) or when file content appears in the output of a previous command (e.g., git diff).--full-context Mode): This mode utilizes a distinct flow (see src/cli_singlepass.tsx, src/utils/singlepass/). It involves:\nsrc/utils/singlepass/context_files.ts.src/utils/singlepass/context.ts.src/utils/singlepass/file_ops.ts.src/utils/config.ts, loads from ~/.codex/config.yaml (or .yml/.json) (not in repo).Let's imagine the user runs: codex "Refactor utils.ts to use arrow functions" in a directory /home/user/myproject.
Initialization (cli.tsx, app.tsx):
o4-mini), approval mode is default (suggest).loadConfig in src/utils/config.ts): Read ~/.codex/config.yaml and ~/.codex/instructions.md.loadProjectDoc in src/utils/config.ts): Find /home/user/myproject/codex.md and read its content.checkInGit in src/utils/check-in-git.ts): Confirm /home/user/myproject is a Git repo.TerminalChat).First API Call (AgentLoop.run in src/utils/agent/agent-loop.ts):
[{ role: "user", content: [{ type: "input_text", text: "Refactor..." }] }].prefix), combined instructions, and the user input message. Set model: "o4-mini", stream: true, tools: [...]. No previous_response_id.openai.responses.create(...) (using the openai library). UI shows "Thinking...".Model Response (Stream):
\nresponse.output_item.done with item: { type: "function_call", name: "shell", arguments: '{"cmd": ["cat", "utils.ts"]}', call_id: "call_1" }response.completed with output: [...] containing the same function call, id: "resp_1".onLastResponseId is called with "resp_1".Tool Call Handling (handleExecCommand in src/utils/agent/handle-exec-command.ts):
cmd = ["cat", "utils.ts"].canAutoApprove(["cat", "utils.ts"], "suggest", ["/home/user/myproject"]) (in src/approvals.ts) -> returns { type: "auto-approve", reason: "View file contents", group: "Reading files", runInSandbox: false }.execCommand in src/utils/agent/handle-exec-command.ts): Run cat utils.ts directly (no sandbox needed for safe commands). Note: Assuming utils.ts exists at the root for this example; in reality, the model might need to specify a path like src/utils.ts.stdout = "/* content of utils.ts */", stderr = "", exitCode = 0.Second API Call (AgentLoop.run continues):
function_call_output item like { type: "function_call_output", call_id: "call_1", output: '{"output": "/* content ... */", "metadata": {"exit_code": 0, ...}}' }.previous_response_id: "resp_1".Model Response (Stream):
\nresponse.output_item.done with item: { type: "function_call", name: "shell", arguments: '{"cmd": ["apply_patch", "*** Begin Patch\\n*** Update File: utils.ts\\n@@ ... -old +new ...\\n*** End Patch"]}', call_id: "call_2" }.response.completed with output: [...] containing the patch function call, id: "resp_2".onLastResponseId is called with "resp_2".Tool Call Handling (Patch):
\napply_patch and extract the patch text.canAutoApprove(["apply_patch", "..."], "suggest", ["/home/user/myproject"]). Since policy is suggest, this returns { type: "ask-user", applyPatch: { patch: "..." } }.requestConfirmation): The UI (TerminalChatCommandReview) displays the patch diff and asks "Allow command? [y/N/e/a]".submitConfirmation is called with { decision: ReviewDecision.YES }.execApplyPatch in src/utils/agent/exec.ts -> process_patch in src/utils/agent/apply-patch.ts): Reads utils.ts, applies the diff logic, and writes the modified content back using Node.js fs.writeFileSync.stdout = "Done!", stderr = "", exitCode = 0.Third API Call:
\nfunction_call_output item for the patch, { call_id: "call_2", output: '{"output": "Done!", ...}' }.previous_response_id: "resp_2".Model Response (Final):
\nresponse.output_item.done with item: { type: "message", role: "assistant", content: [{ type: "output_text", text: "OK, I've refactored utils.ts to use arrow functions." }] }.response.completed, id: "resp_3".onLastResponseId called with "resp_3".User Interaction:
\nutils.ts on their disk has been modified.