# madhav-gohel/codex-plusplus architecture

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

- Interactive diagram: https://gitdiagram.com/madhav-gohel/codex-plusplus
- Repository: https://github.com/madhav-gohel/codex-plusplus

## Overview

##### Project type and purpose
- This is an open-source, full-featured CLI tool named **OpenAI Codex CLI**. It lives in a monorepo but the core package is under `codex-cli/`.
- It’s a **terminal-based coding agent** that:
- Parses user commands/prompts
- Streams prompts to the OpenAI Responses API
- Renders an interactive text UI in your terminal
- Applies patch-based file modifications and/or executes shell commands under a sandbox
- Manages state (e.g., memory, config, approval mode)

##### File structure
- Top-level package: `codex-cli/`
- `bin/codex.js` – Node-executable entrypoint
- `src/` – TypeScript sources organized by feature:
– **components/** – React-style TUI components for chat, overlays, editors
– **utils/** – Helpers (API client, sandbox adapters, token counting, parsers, file ops, storage)
– **hooks/** – React hooks for terminal state
– **app.tsx**, **cli.tsx** – Main CLI application and argument parsing
- `scripts/` – OS sandbox or Docker helper scripts
- `examples/` – Recipe templates that demonstrate extensibility points
- `tests/` – Vitest + snapshot tests covering agent behaviors, UI, utils
- Config/build: `vite.config.ts`, `tsconfig.json`, `.eslintrc.cjs`, Husky hooks

##### Insights from the README
- **Core flows** described: interactive REPL, non-interactive/CI mode, approval modes
- **Security model**: sandboxing via Apple Seatbelt (macOS) or Docker+iptables (Linux)
- **Extensibility**: custom recipes (`examples/`), project-wide docs (`codex.md`), user config (`~/.codex/`)
- **Tech stack**: Node 22+, TypeScript, Vite, Vitest, ESLint, Prettier, Husky, pnpm, optional Nix flake

##### Detail
- Break out subcomponents where meaningful (e.g., chat renderer vs input parser)
- Both **interactive** and **CI-mode** flows
- **sandbox attachments** to the agent core (seatbelt vs Docker)
- Config/state stores and how they influence agent behavior (approval mode, memory)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Exec["Node Executable Entrypoint\nbin/codex.js"]:::frontend
        App["Main Application Entrypoint\napp.tsx"]:::frontend
        CLI["Interactive CLI Front-End\ncli.tsx"]:::frontend
        CI["CI Mode CLI Front-End\ncli-singlepass.tsx"]:::frontend
        Components["TUI Components\ncomponents/"]:::frontend
        Hooks["React Hooks for State\nhooks/"]:::frontend
    end

    %% Agent Core Layer
    subgraph "Agent Core" 
        direction TB
        Orchestrator["Agent Orchestrator\nagent-loop.ts"]:::core
        Parser["Apply-Patch Parser\nparse-apply-patch.ts"]:::core
        PatchLogic["Patch Application Logic\napply-patch.ts"]:::core
        ExecLogic["Command Execution Logic\nexec.ts"]:::core
        ExecHandler["Execution Handler & Approval\nhandle-exec-command.ts"]:::core
        Logging["Logging & Review\nlog.ts / review.ts"]:::core
        PlatformAdapter["Platform Commands Adapter\nplatform-commands.ts"]:::core
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        API["OpenAI API Client & Streaming\nmodel-utils.ts"]:::infra
        SandboxIfc["Sandbox Interface\nsandbox/interface.ts"]:::infra
        Seatbelt["macOS Seatbelt Adapter\nsandbox/macos-seatbelt.ts"]:::infra
        RawExec["Linux Raw Exec Adapter\nsandbox/raw-exec.ts"]:::infra
        FSGit["File System & Git\ncheck-in-git.ts"]:::infra
        Config["Configuration Management\nconfig.ts"]:::infra
        Session["Session & In-memory State\nsession.ts"]:::infra
        History["Command History Storage\nstorage/command-history.ts"]:::infra
        Rollout["Rollout Log Storage\nstorage/save-rollout.ts"]:::infra
        Examples["Examples & Plugins\nexamples/"]:::infra
        OpenAI["OpenAI Responses API"]:::external
    end

    %% Flow
    User([User]):::external
    User -->|"runs codex"| Exec
    Exec -->|"imports app"| App
    App -->|"parse args"| CLI
    App -->|"if --ci"| CI

    CLI -->|"user input"| Orchestrator
    CI -->|"batch prompts"| Orchestrator

    Orchestrator -->|"HTTP request"| API
    API -->|"stream tokens"| Orchestrator

    Orchestrator -->|"parse tokens"| Parser
    Parser --> PatchLogic
    PatchLogic -->|"applyPatch"| FSGit
    Parser --> ExecLogic
    ExecLogic --> ExecHandler
    ExecHandler --> PlatformAdapter
    PlatformAdapter --> SandboxIfc
    SandboxIfc --> Seatbelt
    SandboxIfc --> RawExec
    SandboxIfc -->|"execCmd"| FSGit

    ExecHandler --> Logging
    Orchestrator --> Logging

    Orchestrator --> Session
    Orchestrator --> Config
    Session --> History
    Session --> Rollout

    Orchestrator --> Examples

    Orchestrator -->|"update UI"| CLI
    Orchestrator -->|"update UI"| CI
    PatchLogic --> CLI
    ExecLogic --> CLI

    %% Click Events
    click Exec "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/bin/codex.js"
    click App "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/app.tsx"
    click CLI "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/cli.tsx"
    click CI "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/cli-singlepass.tsx"
    click Components "https://github.com/madhav-gohel/codex-plusplus/tree/main/codex-cli/src/components/"
    click Hooks "https://github.com/madhav-gohel/codex-plusplus/tree/main/codex-cli/src/hooks/"
    click Orchestrator "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/agent/agent-loop.ts"
    click Parser "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/agent/parse-apply-patch.ts"
    click PatchLogic "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/agent/apply-patch.ts"
    click ExecLogic "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/agent/exec.ts"
    click ExecHandler "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/agent/handle-exec-command.ts"
    click Logging "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/agent/log.ts"
    click PlatformAdapter "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/agent/platform-commands.ts"
    click API "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/model-utils.ts"
    click SandboxIfc "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/agent/sandbox/interface.ts"
    click Seatbelt "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/agent/sandbox/macos-seatbelt.ts"
    click RawExec "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/agent/sandbox/raw-exec.ts"
    click FSGit "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/check-in-git.ts"
    click Config "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/config.ts"
    click Session "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/session.ts"
    click History "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/storage/command-history.ts"
    click Rollout "https://github.com/madhav-gohel/codex-plusplus/blob/main/codex-cli/src/utils/storage/save-rollout.ts"
    click Examples "https://github.com/madhav-gohel/codex-plusplus/tree/main/codex-cli/examples/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef core fill:#CFF5D1,stroke:#228B22,color:#228B22
    classDef infra fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00
    classDef external fill:#E8E8E8,stroke:#888,color:#444
```
