How ymichael/open-codex works
Project Type & Purpose
• This is an open‑source, terminal‑based coding agent CLI tool (“Open Codex CLI”) written in Node.js/TypeScript.
• It provides a REPL‑style interface (built with React components rendered to the terminal) that drives code changes via AI provider APIs, executes them in a sandbox, and commits to Git.
Main Architectural Layers & Components
a. CLI Layer
• Entry point (codex-cli/src/cli.tsx, cli_singlepass.tsx) – parses flags/commands and dispatches to the application.
• Build scripts (build.mjs) and Dockerfile for packaging the CLI.
b. Presentation/UI Layer
• React‑style components under src/components – chat UI, overlays (help, history, model), input widgets, approval prompts.
• Renders the interactive experience in the user’s terminal.
c. Core Agent Logic
• Agent loop (src/utils/agent/agent-loop.ts) – orchestrates request/response cycles.
• Patch application (apply-patch.ts, parse-apply-patch.ts) – calculates and stages file diffs.
• Command execution handlers (exec.ts, sandbox/raw-exec.ts, sandbox/macos-seatbelt.ts) – runs code and shell commands inside sandbox.
• Approval/review modules (review.ts, approvals.ts) – enforces user confirmation based on approval mode.
d. AI Provider Integration
• Model utils (src/utils/model-utils.ts) – abstracts calls to Chat Completion API across OpenAI, Gemini, OpenRouter, Ollama.
• Configuration loader (src/utils/config.ts) – reads ~/.codex/config.json and env variables for keys, provider selection, model.
e. Persistence & DevOps
• Git integration (check-in-git.ts) – stages and commits approved changes.
• Storage of rollouts (utils/storage/save-rollout.ts) – archives conversation history or changes.
• Container & sandbox scripts (scripts/run_in_container.sh, init_firewall.sh) – setup Docker or Seatbelt sandbox.
f. Testing & Tooling
• Vitest tests under codex-cli/tests.
• ESLint/Prettier config files.
• CI workflow (.github/workflows/ci.yml).
External Services & Infrastructure
• AI Providers (OpenAI/Gemini/OpenRouter/Ollama) – networked Chat Completion endpoints
• Sandbox runtimes:
– Apple Seatbelt (macOS)
– Docker container + iptables firewall (Linux)
• Git (local)
Relationships & Data Flows
1. User runs open‑codex → CLI parser
2. CLI launches Presentation Layer → displays prompt UI
3. On user input or auto mode → Core Agent Logic prepares a prompt
4. Model Utils sends request → External AI Provider → returns completion
5. Agent Loop interprets completion → applies diffs via Patch modules
6. Sandbox executes code/tests → results back to Agent Loop
7. Approval modules ask user (unless full‑auto) → on approval → Git integration commits changes
8. Presentation Layer updates UI with results
Architectural Patterns & Principles
• Layered architecture: CLI → UI → Core → Infrastructure → External.
• Modular code organization by concern (agent, UI, utils, sandbox).
• Clear separation of interfaces: AI adapter, sandbox adapter, UI renderer.
• Test‑driven modules with high coverage (Vitest).