High‑level overview of the Codex CLI codebase:

[heymaaz]

High-level overview of the Codex CLI codebase

Purpose:
Posting this summary (generated by Codex) to help onboard new contributors and document the project structure. Please review and suggest corrections or additions!

1. Project layout

   • package.json – defines the “codex” CLI (bundled to dist/cli.js), scripts (build, test, lint, etc.), dependencies (OpenAI SDK, Ink/React, meow, chalk, express, etc.) and dev‑dependencies (TypeScript, Vitest, ESLint, Prettier, esbuild).

   • build.mjs – an esbuild script that bundles src/cli.tsx → dist/cli.js (and a dev variant cli‑dev.js), strips out an incompatible React‑Devtools import,
     and injects a require shim for CJS modules.

   • src/ – the heart of the tool (all .ts/.tsx source):

     • src/cli.tsx – the entrypoint. Parses args with meow, sets up OpenAI API key, modes (interactive, quiet, full‑context), and then either invokes
       runSinglePass, runQuietMode, or renders the Ink TUI.
     • src/app.tsx – top‑level Ink component. If you’re inside a Git repo it hands off to <TerminalChat/>; if not, it forces you to confirm you really want to run
       outside version control.
     • src/cli_singlepass.tsx – the one‑shot “full‑context” editing mode, which gives the model your entire repo and a prompt and then exits.
     • src/components/… – reusable React/Ink components for chat UIs, single‑pass UI, command confirmations, etc.
     • src/utils/… – support modules:
       • config.ts – load and persist ~/.codex/config.{json,yml}, merge in project docs (codex.md), handle timeouts and base URLs.
       • agent/agent‑loop.ts – the core “agent” engine. Streams responses from OpenAI, turns function calls into shell commands or apply_patch calls, enforces
         cancellation/termination, and calls back to the UI.
       • agent/log.ts – debug logging.
       • agent/review.ts – handling user decisions (continue, reject, etc.).
       • auto‑approval‑mode.ts – maps CLI flags (--full-auto, --auto-edit) → approval policy.
       • model‑utils.js – check your account’s supported models, preload embeddings/models.
       • parsers.ts – parse the “tool calls” (e.g. ["bash","-lc","…"] or apply_patch) out of function_call items.
     • terminal.ts – setup/cleanup, raw‑mode key handling, signal handlers.
     • src/lib/… – standalone helpers for parsing & formatting patches, shell‑quote safety analysis, text buffers, etc. These are imported in many places via the TS
       path alias @lib/*.
     • src/typings.d.ts – any ambient type overrides.

   • dist/ – bundled CLI artifact, published to NPM (and consumed by the Dockerfile).

   • tests/ – ~100 Vitest suites covering the agent logic, patch parsing, safety rules, UI behavior (Ink Testing Library), multiline input, config, markdown
     rendering, etc.

   • examples/ – small demo projects (e.g. camerascii, prompt-analyzer, a “build‑codex‑demo”, plus a prompting guide).

   • scripts/ – helper shell scripts (container build, firewall setup, run‑in‑container).

   • Dockerfile – a Node 20 image that installs shell tooling, copies in the built codex.tgz, and sets up a minimal sandbox firewall script.

2. Core execution modes
   • Interactive (default):
     • codex <prompt> launches an Ink/React TUI (<TerminalChat/>)
     • Multi‑turn chat, model issues “function calls” for edits or shell commands, user is prompted to approve or reject.
     • Supports flags: --auto-edit, --full-auto, --no-project-doc, image inputs (-i), project doc overrides, quiet/full‑stdout toggles.
     • Quiet (-q, --quiet): no TUI, just streams the final assistant messages or JSON.
     • Full‑context (-f, --full-context): single‑pass editing mode, feeds the entire repo to the model and applies a batch of edits in one go, then exits.
3. Build & test
   • npm run build → build.mjs → dist/cli.js
   • npm test runs Vitest suites.
   • npm run lint / npm run format enforce code style via ESLint/Prettier.
   • Type‑checking is done with tsc --noEmit.
4. High‑level workflow
   • User runs codex “…”.
   • CLI parses flags, loads user config (~/.codex), discovers codex.md in repo.
   • In interactive mode, <App/> checks you’re in Git, then spin up an AgentLoop.
   • AgentLoop streams chat completions, emits function_call items.
   • Each call is parsed (edit vs shell), run through canAutoApprove → user prompts or auto‑approval.
   • Approved commands are executed (apply_patch for file edits, child_process for shell commands). Outputs are fed back to the loop as function_call_output
     items so the model sees the results.
   • Loop continues until the model signals it’s done.

[tibo-openai]

Please suggest additions / changes to the README and docs, we will happily accept the PR!