# ymichael/open-codex architecture

> Architecture diagram of the GitHub repository ymichael/open-codex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ymichael/open-codex
- Repository: https://github.com/ymichael/open-codex

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLI1["cli.tsx"]:::cli
        CLI2["cli_singlepass.tsx"]:::cli
        Build["build.mjs / Dockerfile"]:::cli
    end

    %% Presentation/UI Layer
    subgraph "UI Layer"
        direction TB
        UIComp["src/components/**"]:::ui
    end

    %% Core Agent Logic
    subgraph "Core Agent Logic"
        direction TB
        AgentLoop["agent-loop.ts"]:::core
        ApplyPatch["apply-patch.ts / parse-apply-patch.ts"]:::core
        ExecHandler["exec.ts / handle-exec-command.ts"]:::core
        ReviewMod["review.ts / approvals.ts"]:::core
    end

    %% Sandbox Environment
    subgraph "Sandbox Environment"
        direction TB
        DockerSB["Docker + iptables"]:::infra
        SeatbeltSB["macOS Seatbelt"]:::infra
    end

    %% AI Provider Integration
    subgraph "AI Provider Integration"
        direction TB
        ModelUtils["model-utils.ts"]:::infra
        Config["config.ts"]:::infra
    end

    %% Persistence & DevOps
    subgraph "Persistence & DevOps"
        direction TB
        GitModule["check-in-git.ts"]:::infra
        Storage["save-rollout.ts"]:::infra
        Scripts["run_in_container.sh / init_firewall.sh / build_container.sh"]:::infra
        LocalRepo[(Local Git Repo)]:::infra
    end

    %% Testing & Tooling
    subgraph "Testing & Tooling"
        direction TB
        Tests["tests/**"]:::test
        CI[".github/workflows/ci.yml"]:::test
        Lint[".eslintrc.cjs /.prettierrc.toml /.prettierignore"]:::test
    end

    %% External Services
    AIProviders["AI Providers (OpenAI/Gemini/OpenRouter/Ollama)"]:::external

    %% Data Flows
    CLI1 -->|"start"| UIComp
    CLI2 -->|"start"| UIComp
    UIComp -->|"user input"| AgentLoop
    AgentLoop -->|"prepare prompt"| ModelUtils
    ModelUtils -->|"HTTP/REST"| AIProviders
    AIProviders -->|"completion"| ModelUtils
    ModelUtils -->|"response"| AgentLoop
    AgentLoop -->|"generate diffs"| ApplyPatch
    AgentLoop -->|"run commands"| ExecHandler
    ExecHandler -->|"shell cmds"| DockerSB
    ExecHandler -->|"shell cmds"| SeatbeltSB
    DockerSB -->|"results"| ExecHandler
    SeatbeltSB -->|"results"| ExecHandler
    AgentLoop -->|"approval request"| ReviewMod
    ReviewMod -->|"on approve"| GitModule
    GitModule -->|"commit"| LocalRepo
    AgentLoop -->|"update UI"| UIComp

    %% Click Events
    click CLI1 "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/cli.tsx"
    click CLI2 "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/cli_singlepass.tsx"
    click Build "https://github.com/ymichael/open-codex/blob/main/codex-cli/build.mjs"
    click Build "https://github.com/ymichael/open-codex/tree/main/codex-cli/Dockerfile"
    click UIComp "https://github.com/ymichael/open-codex/tree/main/codex-cli/src/components/"
    click ModelUtils "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/utils/model-utils.ts"
    click Config "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/utils/config.ts"
    click AgentLoop "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/utils/agent/agent-loop.ts"
    click ApplyPatch "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/utils/agent/apply-patch.ts"
    click ApplyPatch "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/utils/agent/parse-apply-patch.ts"
    click ExecHandler "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/utils/agent/exec.ts"
    click ExecHandler "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/utils/agent/handle-exec-command.ts"
    click ReviewMod "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/utils/agent/review.ts"
    click ReviewMod "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/approvals.ts"
    click DockerSB "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/utils/agent/sandbox/macos-seatbelt.ts"
    click DockerSB "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/utils/agent/sandbox/raw-exec.ts"
    click Config "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/utils/config.ts"
    click GitModule "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/utils/check-in-git.ts"
    click Storage "https://github.com/ymichael/open-codex/blob/main/codex-cli/src/utils/storage/save-rollout.ts"
    click Scripts "https://github.com/ymichael/open-codex/blob/main/codex-cli/scripts/run_in_container.sh"
    click Scripts "https://github.com/ymichael/open-codex/blob/main/codex-cli/scripts/init_firewall.sh"
    click Scripts "https://github.com/ymichael/open-codex/blob/main/codex-cli/scripts/build_container.sh"
    click Tests "https://github.com/ymichael/open-codex/tree/main/codex-cli/tests/"
    click CI "https://github.com/ymichael/open-codex/blob/main/.github/workflows/ci.yml"
    click Lint "https://github.com/ymichael/open-codex/blob/main/codex-cli/.eslintrc.cjs"
    click Lint "https://github.com/ymichael/open-codex/blob/main/.prettierrc.toml"
    click Lint "https://github.com/ymichael/open-codex/blob/main/.prettierignore"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef ui fill:#9f9,stroke:#333,stroke-width:1px
    classDef core fill:#9cf,stroke:#333,stroke-width:1px
    classDef infra fill:#fc9,stroke:#333,stroke-width:1px
    classDef test fill:#ccc,stroke:#333,stroke-width:1px
    classDef external fill:#ddd,stroke:#333,stroke-width:1px
```
