Analyze codex cli main loop

[jpollack]

External (non-OpenAI) Pull Request Requirements

Before opening this Pull Request, please read the dedicated "Contributing" markdown file or your PR may be closed:
https://github.com/openai/codex/blob/main/docs/contributing.md

This PR adds a new document, CODEX_MAIN_LOOP_ANALYSIS.md, providing a comprehensive top-down overview of the Codex CLI's architecture.

The document details:

• Main Loop Architecture: Explaining the submission loop and turn execution flow.
• Remote Inference Interaction: How the CLI communicates with LLM servers, including SSE streaming and API usage.
• Local Tool Execution: The pipeline for executing tools, including sandboxing, approval workflows, and different tool types.
• Information Flow: How conversation history and events are managed and propagated.

It includes ASCII diagrams and flowcharts to illustrate the key components and their interactions, offering insights into the turn lifecycle, error handling, and sandboxing mechanisms.

This document was generated in response to a request for a detailed analysis of the Codex CLI's internal workings, particularly its interaction with remote servers and local tool execution.

---

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}